Bundles
Create, retrieve, and delete immutable ordered sets of artifact references. Bundles assemble artifacts into a reusable agent prefix.
A bundle is an immutable, ordered set of artifact references. Ordering is semantic: items are stored exactly as supplied and never re-sorted. Every referenced artifact must already exist within the caller's project, so a bundle can never dangle or reach across a tenant boundary. The public id is prefixed bnd_. See bundles for the object model.
All requests require a bearer API key. See authentication.
Create a bundle
POST /v2/bundles
bundle_typestringdefault: agent_prefixA label for how the bundle is used, e.g. agent_prefix.
itemsarrayrequiredOrdered list of artifact references. Must not be empty. Each item:
item
artifact_idstringrequiredAn art_... id that exists in this project.
rolestringrequiredThe semantic role this artifact plays in the bundle, e.g. system, tools, schema.
curl https://api.zumik.ai/v2/bundles \
-H "Authorization: Bearer $ZUMIK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"bundle_type": "agent_prefix",
"items": [
{ "artifact_id": "art_01jy7n3q8v6kzr4w2m9bd5xpfh", "role": "system" },
{ "artifact_id": "art_01jy7p2r9w7laz5x3n0ce6yqgj", "role": "tools" }
]
}'from zumik import Zumik
zk = Zumik()
bundle = zk.bundles.create(
bundle_type="agent_prefix",
items=[
{"artifact_id": sys_artifact.id, "role": "system"},
{"artifact_id": tools_artifact.id, "role": "tools"},
],
){
"id": "bnd_01jy7n5t0x8mbs6y4p1ef7zrhk",
"object": "bundle",
"bundle_type": "agent_prefix",
"project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
"items": [
{ "artifact_id": "art_01jy7n3q8v6kzr4w2m9bd5xpfh", "role": "system" },
{ "artifact_id": "art_01jy7p2r9w7laz5x3n0ce6yqgj", "role": "tools" }
],
"created_at": "2026-06-15T16:05:02Z"
}idstringOpaque bundle id, prefixed bnd_.
objectstringAlways bundle.
bundle_typestringThe bundle type, echoed back.
project_idstringThe owning project.
itemsarrayThe ordered items, exactly as supplied.
created_atstringRFC 3339 creation timestamp.
Retrieve a bundle
GET /v2/bundles/{bundle_id}
bundle_idstringpathrequiredThe bundle id to fetch.
curl https://api.zumik.ai/v2/bundles/bnd_01jy7n5t0x8mbs6y4p1ef7zrhk \
-H "Authorization: Bearer $ZUMIK_API_KEY"Returns the same bundle object as create.
Delete a bundle
DELETE /v2/bundles/{bundle_id}
bundle_idstringpathrequiredThe bundle id to delete.
curl -X DELETE https://api.zumik.ai/v2/bundles/bnd_01jy7n5t0x8mbs6y4p1ef7zrhk \
-H "Authorization: Bearer $ZUMIK_API_KEY"{
"id": "bnd_01jy7n5t0x8mbs6y4p1ef7zrhk",
"object": "bundle.deleted",
"deleted": true
}idstringThe deleted bundle id.
objectstringAlways bundle.deleted.
deletedbooleantrue when the bundle was removed.
Errors
| Status | Code | When |
|---|---|---|
| 400 | invalid_request_error | items is empty, or a referenced artifact does not exist in this project. |
| 401 | invalid_api_key | Missing or invalid API key. |
| 404 | invalid_request_error | The bundle does not exist in this project. |
See the full table on errors.
Artifacts
Create, retrieve, and delete reusable immutable content units. Artifacts are the addressable building blocks of agent state on the native /v2 surface.
Sessions
Create, retrieve, and delete causal state containers for agent workflows. A session holds a default branch and an append-only event history.