# Artifacts

Every file Emboss makes or receives is an artifact with its own id. Fetch an artifact's metadata to see what it is, what produced it, and what it has been used for since, or fetch its bytes directly. An artifact survives its own file being deleted: metadata still answers, with status gone, once the bytes are swept. See the artifacts guide at /docs/artifacts for the sources list and page-selection grammar used to fax several artifacts as one packet.

## Get an artifact

```
GET /artifacts/{artifact_id}
```

Authentication: Bearer API key required.

The artifact's kind, size, page count and fingerprint, the process that produced it, the files that process used, and the processes that have used this artifact since.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| artifact_id | path | string | yes | From any response that returned this file. |
| X-Artifact-Token | header | string | no | For pay-per-call callers: the artifact_token returned next to this artifact_id, in place of a Bearer key. Also accepted as a token query parameter. |

```curl
curl https://api.getemboss.ai/artifacts/0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a \
  -H "Authorization: Bearer sk_..."
```

```js
const res = await fetch("https://api.getemboss.ai/artifacts/0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a", {
  headers: { Authorization: "Bearer sk_..." },
});
const artifact = await res.json();
```

```python
import requests

res = requests.get(
    "https://api.getemboss.ai/artifacts/0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
    headers={"Authorization": "Bearer sk_..."},
)
artifact = res.json()
```

### Response

```json
{
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "kind": "filled_pdf",
  "mime_type": "application/pdf",
  "size_bytes": 184320,
  "sha256": "f2ad6f...",
  "page_count": 1,
  "status": "available",
  "created_at": "2026-09-12T10:33:29Z",
  "swept_at": null,
  "produced_by": {
    "op_kind": "job",
    "op_id": "6c47f7f5-f921-4698-910f-95dd7d81310b",
    "skill": "commit",
    "status": "completed",
    "role": "filled",
    "position": null
  },
  "inputs": [
    { "artifact_id": "3e714663-ff2c-45ac-ae11-3c7015facfef", "kind": "fillable_pdf", "role": "form", "position": null }
  ],
  "used_by": [
    { "op_kind": "fax", "op_id": "9edecde3-74d8-4402-bfeb-49e61ca804b9", "skill": "send_fax", "status": "running", "role": "source" }
  ]
}
```

### Status codes

| Code | Meaning |
| --- | --- |
| 200 | The artifact's metadata. |
| 400 | Not a valid artifact id. |
| 401 | An Authorization header was sent, but its key or token is invalid. |
| 404 | No such artifact, or not yours. Also the answer when no key and no valid artifact token are sent. |

## Get an artifact's content

```
GET /artifacts/{artifact_id}/content
```

Authentication: Bearer API key required.

The artifact's bytes, with its original Content-Type. Answers 410 once the file has been swept under ephemeral processing; the metadata endpoint still answers for the same id.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| artifact_id | path | string | yes | From any response that returned this file. |
| X-Artifact-Token | header | string | no | For pay-per-call callers: the artifact_token returned next to this artifact_id, in place of a Bearer key. Also accepted as a token query parameter. |

```curl
curl https://api.getemboss.ai/artifacts/0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a/content \
  -H "Authorization: Bearer sk_..." \
  -o filled.pdf
```

```js
const res = await fetch("https://api.getemboss.ai/artifacts/0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a/content", {
  headers: { Authorization: "Bearer sk_..." },
});
const bytes = await res.arrayBuffer();
```

```python
import requests

res = requests.get(
    "https://api.getemboss.ai/artifacts/0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a/content",
    headers={"Authorization": "Bearer sk_..."},
)
open("filled.pdf", "wb").write(res.content)
```

### Response

```json
%PDF-1.7...
(Binary PDF, Content-Type: application/pdf)
```

### Status codes

| Code | Meaning |
| --- | --- |
| 200 | The file's bytes. |
| 400 | Not a valid artifact id. |
| 401 | An Authorization header was sent, but its key or token is invalid. |
| 404 | No such artifact, or not yours. Also the answer when no key and no valid artifact token are sent. |
| 410 | The file was deleted; its metadata still answers at GET /artifacts/{artifact_id}. |

## See also

- [Artifacts and lineage](https://getemboss.ai/docs/artifacts)
- [Pre-fill forms from context documents](https://getemboss.ai/use-cases/prefill-from-context)