# Artifacts and lineage

Every file Emboss makes or receives has an `artifact_id`: the fillable form,
a filled PDF, a receipt, a submission package, a batch row, a fax's
transmitted copy, an uploaded document, the `xfa_data` export a fill of an
[XFA form](/docs/xfa-forms) returns alongside its filled PDF, and the
`xfa_render` page Emboss draws from a dynamic XFA form's template. The id is
opaque and stays valid for as long as the file exists, so an agent can hand a
result straight to the next operation without downloading it.

## Chain without downloads

With MCP: run `commit_proposal`, poll `get_job` until `status` is `ready`,
then call `send_fax` with `to` and the job's `artifact_id`. Over the API the
same call is a JSON body:

```bash
curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "artifact_id": "<artifact id from the job>"}'
```

Every response that hands back a file carries its `artifact_id`. Jobs with
several outputs list them under `artifacts` with a `role` (`filled`,
`receipt`, `package`, `row`, `transmission`).

## Several sources at once

A fax can take a list of artifacts and send them as one packet. Each entry
names an `artifact_id`, adds an `artifact_token` when you are a pay-per-call
caller, and may pick `pages`.

Page selections are comma-separated ranges of 1-based page numbers, each `n` or `n-m`, for example `1-3,7`; whitespace is ignored and repeats are kept.

A call gives `sources`, or one of the single source fields, never both.

```bash
curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer $EMBOSS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "sources": [
        {"artifact_id": "<package>", "pages": "1-2"},
        {"artifact_id": "<filled form>"}]}'
```

The transmitted copy lists every source as an input, in order, so
`GET /artifacts/{artifact_id}` shows exactly which pages of which files went out.

Once an `artifact_id` exists, the bytes behind it never change; a new render, transformation or copy is a new artifact.

## Free utilities

Merge, compose, extract, delete, reorder, rotate, inspect and lock PDF artifacts
without downloading or re-uploading them, then use the result directly in a
fill or a fax. See [Free PDF utilities](/docs/pdf-utilities).

## Where a file came from

`GET /artifacts/{artifact_id}` returns what the file is (kind, size, page
count, `sha256`), the process that produced it (`produced_by`, with its
skill and status), the files that process used (`inputs`), and the
processes that used this file since (`used_by`). Follow ids to walk further.
`GET /artifacts/{artifact_id}/content` returns the bytes. See the
[reference](/docs/reference/artifacts).

## Pay-per-call callers

A pay-per-call result carries an `artifact_token` next to its
`artifact_id`. Send both to reuse the file in a later paid operation, for
example [send a fax](/docs/send-fax) of a form you just paid to fill. The
token is the proof of ownership; keep it with the id.

## After deletion

When a form's documents are deleted under
[ephemeral processing](/docs/ephemeral-processing), Emboss keeps
a record of each file, without the file: what kind of file it was, its
size, page count and fingerprint, when it was created, and which process
produced or used it.
The record holds no file names, no field values and no document content.
`GET /artifacts/{artifact_id}` still answers, with `status` set to `gone`;
the bytes and every operation that would use them answer 410.

## See also

- [Pre-fill forms from context documents](https://getemboss.ai/use-cases/prefill-from-context)
- [Fillable PDF](https://getemboss.ai/glossary/fillable-pdf)
- [Callbacks](https://getemboss.ai/docs/callbacks)
- [Send a fax](https://getemboss.ai/docs/send-fax)
- [Prepare, commit and verify](https://getemboss.ai/docs/prepare-commit-verify)
- [Free PDF utilities](https://getemboss.ai/docs/pdf-utilities)
- [XFA forms](https://getemboss.ai/docs/xfa-forms)
- [Artifacts](https://getemboss.ai/docs/reference/artifacts)
- [Free PDF utilities](https://getemboss.ai/docs/reference/utilities)