---
title: "client.elements"
description: "Elements API resource."
section: "Libraries"
group: "SDK resources"
order: 204
---

Accessed via `client.elements`.

## Usage

```ts
const element = await client.elements.create({
  workspaceId: "wsp_abc123",
  name: "RevenueCard",
});

// Write the source file, then build:
await client.elements.updateVersionFile({
  versionId: element.defaultVersionId!,
  path: "src/element.tsx",
  content: source,
});
const build = await client.elements.build({
  id: element.id,
  versionId: element.defaultVersionId!,
});
```

## Methods

### `build`

Trigger a build for a specific element version.

```ts
build(params: BuildElementParams): Promise<Build>
```

**Types:** [BuildElementParams](/types/build-element-params) · [Build](/types/build)

### `create`

Create a new element.

```ts
create(params: CreateElementParams): Promise<Element>
```

**Types:** [CreateElementParams](/types/create-element-params) · [Element](/types/element)

### `createVersionFile`

Create a file in a specific element version.

```ts
createVersionFile(params: CreateElementVersionFileParams): Promise<SuccessResponse>
```

**Types:** [CreateElementVersionFileParams](/types/create-element-version-file-params) · [SuccessResponse](/types/success-response)

### `delete`

Soft-delete an element.

```ts
delete(params: DeleteElementParams): Promise<SuccessResponse>
```

**Types:** [DeleteElementParams](/types/delete-element-params) · [SuccessResponse](/types/success-response)

### `deleteVersionFile`

Delete a file from a specific element version.

```ts
deleteVersionFile(params: DeleteElementVersionFileParams): Promise<SuccessResponse>
```

**Types:** [DeleteElementVersionFileParams](/types/delete-element-version-file-params) · [SuccessResponse](/types/success-response)

### `getBundle`

Fetch the element's active bundle JS (resolves to the default version).
`GET /api/elements/:id/bundle`

Returns the raw JavaScript text. Pin to a version with
`versions.getBundle({ id, versionId })`.

```ts
async getBundle(params: GetElementBundleParams): Promise<string>
```

**Types:** [GetElementBundleParams](/types/get-element-bundle-params)

```ts
const js = await client.elements.getBundle({ id: "elm_abc123" });
```

### `getPreview`

Get a preview session's current state.

```ts
getPreview(params: { sessionId: string }): Promise<unknown>
```

### `keepalivePreview`

Heartbeat a preview session. Call every ~30s while the preview is
visible to prevent the idle reaper from tearing it down.

```ts
keepalivePreview(params: { sessionId: string; }): Promise<{ id: string; status: string }>
```

### `list`

List elements.

```ts
list(params?: Omit<ListElementsParams, "filter" | "orderBy"> & { filter?: ElementFilter; orderBy?: ElementOrderBy[]; } & ElementShorthands): Promise<Page<Element>>
```

**Types:** [ListElementsParams](/types/list-elements-params) · [ElementFilter](/types/element-filter) · [ElementOrderBy](/types/element-order-by) · [ElementShorthands](/types/element-shorthands) · [Page](/types/page) · [Element](/types/element)

### `listFiles`

List files in an element's working tree.

```ts
listFiles(params: ListElementFilesParams): Promise<AppFileListResponse>
```

**Types:** [ListElementFilesParams](/types/list-element-files-params) · [AppFileListResponse](/types/app-file-list-response)

### `listVersionFiles`

List files in a specific element version.

```ts
listVersionFiles(params: ListElementVersionFilesParams): Promise<AppFileListResponse>
```

**Types:** [ListElementVersionFilesParams](/types/list-element-version-files-params) · [AppFileListResponse](/types/app-file-list-response)

### `purge`

Permanently delete a soft-deleted element.

```ts
purge(params: PurgeElementParams): Promise<SuccessResponse>
```

**Types:** [PurgeElementParams](/types/purge-element-params) · [SuccessResponse](/types/success-response)

### `readVersionFile`

Read a file's content from a specific element version.

```ts
readVersionFile(params: ReadElementVersionFileParams): Promise<AppFileContentResponse>
```

**Types:** [ReadElementVersionFileParams](/types/read-element-version-file-params) · [AppFileContentResponse](/types/app-file-content-response)

### `restore`

Restore a soft-deleted element.

```ts
restore(params: RestoreElementParams): Promise<Element>
```

**Types:** [RestoreElementParams](/types/restore-element-params) · [Element](/types/element)

### `retrieve`

Get a single element.

```ts
retrieve(params: RetrieveElementParams): Promise<Element>
```

**Types:** [RetrieveElementParams](/types/retrieve-element-params) · [Element](/types/element)

### `startPreview`

Start a live preview sandbox for a version.
`POST /api/elements/:id/versions/:versionId/preview`

```ts
startPreview(params: { id: string; versionId: string }): Promise<unknown>
```

### `stopPreview`

Stop a preview session and tear down the sandbox.

```ts
stopPreview(params: { sessionId: string }): Promise<SuccessResponse>
```

**Types:** [SuccessResponse](/types/success-response)

### `update`

Update an element.

```ts
update(params: UpdateElementParams): Promise<Element>
```

**Types:** [UpdateElementParams](/types/update-element-params) · [Element](/types/element)

### `updateVersionFile`

Update a file in a specific element version.

```ts
updateVersionFile(params: UpdateElementVersionFileParams): Promise<SuccessResponse>
```

**Types:** [UpdateElementVersionFileParams](/types/update-element-version-file-params) · [SuccessResponse](/types/success-response)

## client.elements.versions

Raw-text bundle accessors scoped to an element version. Basic CRUD on
versions lives at `client.elementVersions`; file CRUD lives directly
on `client.elements` as `*VersionFile` methods (manifest-driven).

Accessed via `client.elements.versions`.

### `getBundle`

Fetch the compiled bundle JS for a specific version.
`GET /api/elements/:id/versions/:versionId/bundle`

```ts
async getBundle(params: GetElementVersionBundleParams): Promise<string>
```

**Types:** [GetElementVersionBundleParams](/types/get-element-version-bundle-params)