# Artifacts (/docs/sdk/artifacts)



`client.artifacts` exports files from a sandbox's workspace to durable
object storage and manages them afterward. Export is always explicit:
nothing is copied out automatically when a sandbox is destroyed. Artifacts
outlive the sandbox they came from.

A [`SandboxHandle`](/docs/sdk) exposes `sandbox.artifacts.create` and
`sandbox.artifacts.list` without the `sandboxId` argument. For methods
that take an artifact ID (`get`, `download`, `downloadUrl`, `delete`), use
the top-level client. [Previews](/docs/sdk/previews) are documented
separately.

## create [#create]

Copy a file from the sandbox workspace into object storage. Requires a
live sandbox and the `artifact:create` and `file:read` scopes.

```ts
create(
  sandboxId: `sbx_${string}`,
  input: { path: string; name?: string; idempotencyKey?: string },
): Promise<Artifact>
```

| Field            | Type     | Default           | Description                                  |
| ---------------- | -------- | ----------------- | -------------------------------------------- |
| `path`           | `string` | required          | Source path inside `/workspace`.             |
| `name`           | `string` | derived from path | Display name for the artifact.               |
| `idempotencyKey` | `string` | SDK-generated     | Idempotency key with a 24-hour retry window. |

```ts
const artifact = await client.artifacts.create(sandbox.id, {
  path: "dist/report.pdf",
  name: "quarterly-report",
});
console.log(artifact.id, artifact.sizeBytes);
```

You can also collect artifacts automatically when a command finishes with
the `collect` option on [`commands.run`](/docs/sdk/commands#run).

Error codes: `not_found`, `sandbox_destroyed`, `file_not_found`,
`path_outside_workspace`, `forbidden`, `quota_exceeded`.

## list [#list]

List artifacts exported from a sandbox.

```ts
list(sandboxId: `sbx_${string}`): Promise<ListArtifactsResponse>
```

```ts
const artifacts = await client.artifacts.list(sandbox.id);
for (const artifact of artifacts.data) {
  console.log(artifact.name);
}
```

## get [#get]

Fetch a single artifact's metadata by ID.

```ts
get(artifactId: `art_${string}`): Promise<Artifact>
```

```ts
const artifact = await client.artifacts.get("art_abc123");
```

Error codes: `not_found`, `forbidden`.

## download [#download]

Download an artifact's content as bytes.

```ts
download(artifactId: `art_${string}`): Promise<Uint8Array>
```

```ts
import { writeFile } from "node:fs/promises";

const bytes = await client.artifacts.download(artifact.id);
await writeFile("report.pdf", bytes);
```

Error codes: `not_found`, `forbidden`.

## downloadUrl [#downloadurl]

Get a short-lived signed URL for downloading the artifact, useful for
handing off to another process or service. Requests use `GET` with the
returned `headers`, authenticated as `authMode: "api_key"`.

```ts
downloadUrl(artifactId: `art_${string}`): Promise<{
  url: string;
  method: "GET";
  headers: Record<string, string>;
  authMode: "api_key";
}>
```

```ts
const { url, headers } = await client.artifacts.downloadUrl(artifact.id);
const response = await fetch(url, { headers });
```

<Callout type="info" title="Note">
  Artifacts can contain sensitive data. Download URLs are short-lived and signed; treat
  them as secrets while they're valid.
</Callout>

## delete [#delete]

Delete an artifact from storage. The operation is idempotent by state and
returns the artifact record with `deletedAt` set.

```ts
delete(artifactId: `art_${string}`): Promise<Artifact>
```

```ts
await client.artifacts.delete(artifact.id);
```

Error codes: `not_found`, `forbidden`.

## Artifact object [#artifact-object]

The `Artifact` type includes `id` (`art_` prefix), `orgId`, `projectId`,
`sandboxId`, `name`, `sourcePath`, `objectKey`, `sizeBytes`,
`contentType`, `createdAt`, and `deletedAt`.

## Next steps [#next-steps]

* [Previews](/docs/sdk/previews) — expose HTTP services from a sandbox.
* [Commands](/docs/sdk/commands) — collect artifacts automatically with
  `collect`.
* [Artifacts concept](/docs/concepts/artifacts) — retention and storage
  model.