# Artifacts (/concepts/artifacts)



An **artifact** is the smallest reusable thing in Zumik: one immutable unit of content with a stable opaque ID. Instead of maintaining separate, inconsistent registries for contexts, tool definitions, and schemas, Zumik folds them all into a single object type distinguished by an `artifact_type` tag.

```json
{
  "id": "art_01jy7n3q8v...",
  "object": "artifact",
  "artifact_type": "policy",
  "project_id": "prj_01jy...",
  "content_media_type": "text/plain",
  "created_at": "2026-06-09T20:15:00Z",
  "retention_class": "standard",
  "metadata": { "label": "repository-policy" }
}
```

## Artifact types [#artifact-types]

`artifact_type` records what the content *is*, which drives serialization and fingerprint domain separation. The supported values:

| Value                | Typical content                          |
| -------------------- | ---------------------------------------- |
| `text_context`       | Stable instructions or workspace context |
| `tool_bundle_source` | Tool / function definitions              |
| `response_schema`    | A structured-output JSON schema          |
| `document`           | A long-lived reference document          |
| `retrieval_chunk`    | A retrieved knowledge fragment           |
| `policy`             | A repository or tenant policy            |
| `checkpoint`         | A session checkpoint reference           |
| `compaction_summary` | A compacted summary of prior history     |
| `binary_attachment`  | Non-text attachment bytes                |

<Tip>
  The type participates in the internal fingerprint, so identical bytes registered as a `policy` and as a `document` are deliberately *not* treated as the same content. See [handles and fingerprints](/concepts/handles-and-fingerprints).
</Tip>

## Retention class [#retention-class]

Each artifact carries a `retention_class` of `ephemeral`, `standard`, or `extended`. This expresses how long the content should be kept available and feeds into [retention and purge](/concepts/retention-and-purge) behavior. It is a property of the content, not a billing knob.

## Immutability invariants [#immutability-invariants]

Artifacts are immutable after creation. This is not a convenience; it is what makes them safely reusable and what makes deletion meaningful.

<Steps>
  <Step title="Content never changes">
    There is no update operation. To change content, you create a new artifact and get a new ID. The old ID always refers to exactly the bytes it was created with.
  </Step>

  <Step title="The public ID is opaque">
    IDs are random `art_...` handles, never content hashes. You cannot infer equality between two artifacts from their IDs, and a leaked ID reveals nothing about its content.
  </Step>

  <Step title="Deletion is explicit and irreversible">
    `DELETE /v2/artifacts/{id}` revokes the handle. Re-uploading identical bytes later creates a *new* opaque handle; it does not resurrect the old one or any cache relationship tied to it.
  </Step>
</Steps>

<Warning>
  Because content is immutable, an artifact is the right home for anything stable and reused: system instructions, tool registries, schemas, long documents. Anything that mutates per turn belongs in a [session](/concepts/sessions) event, not an artifact.
</Warning>

## Where artifacts go next [#where-artifacts-go-next]

An artifact on its own is just content. It becomes useful when ordered into a [bundle](/concepts/bundles) and attached to a [session](/concepts/sessions), where the platform can measure how often it recurs and how much of it is actually reused.

<CardGroup cols="2">
  <Card title="Bundles" icon="boxes-stacked" href="/concepts/bundles">
    Order artifacts into a reusable prefix.
  </Card>

  <Card title="Artifacts API" icon="code" href="/api-v2/artifacts">
    Create, fetch, and delete artifacts.
  </Card>
</CardGroup>