Artifacts

View as Markdown

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}Bearer auth

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.

Status codes

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

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

Response

{
  "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" }
  ]
}

Get an artifact's content

GET/artifacts/{artifact_id}/contentBearer auth

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.

Status codes

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

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

Response

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