# Bundles (/api-v2/bundles)



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](/concepts/bundles) for the object model.

All requests require a bearer API key. See [authentication](/api-reference/authentication).

## Create a bundle [#create-a-bundle]

`POST /v2/bundles`

<ParamField body="bundle_type" type="string" default="agent_prefix">
  A label for how the bundle is used, e.g. `agent_prefix`.
</ParamField>

<ParamField body="items" type="array">
  Ordered list of artifact references. Must not be empty. Each item:

  <Expandable title="item">
    <ParamField body="artifact_id" type="string">
      An `art_...` id that exists in this project.
    </ParamField>

    <ParamField body="role" type="string">
      The semantic role this artifact plays in the bundle, e.g. `system`, `tools`, `schema`.
    </ParamField>
  </Expandable>
</ParamField>

```bash
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" }
    ]
  }'
```

```python
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"},
    ],
)
```

```json
{
  "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"
}
```

<ResponseField name="id" type="string">
  Opaque bundle id, prefixed `bnd_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `bundle`.
</ResponseField>

<ResponseField name="bundle_type" type="string">
  The bundle type, echoed back.
</ResponseField>

<ResponseField name="project_id" type="string">
  The owning project.
</ResponseField>

<ResponseField name="items" type="array">
  The ordered items, exactly as supplied.
</ResponseField>

<ResponseField name="created_at" type="string">
  RFC 3339 creation timestamp.
</ResponseField>

## Retrieve a bundle [#retrieve-a-bundle]

`GET /v2/bundles/{bundle_id}`

<ParamField path="bundle_id" type="string">
  The bundle id to fetch.
</ParamField>

```bash
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-a-bundle]

`DELETE /v2/bundles/{bundle_id}`

<ParamField path="bundle_id" type="string">
  The bundle id to delete.
</ParamField>

```bash
curl -X DELETE https://api.zumik.ai/v2/bundles/bnd_01jy7n5t0x8mbs6y4p1ef7zrhk \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

```json
{
  "id": "bnd_01jy7n5t0x8mbs6y4p1ef7zrhk",
  "object": "bundle.deleted",
  "deleted": true
}
```

<ResponseField name="id" type="string">
  The deleted bundle id.
</ResponseField>

<ResponseField name="object" type="string">
  Always `bundle.deleted`.
</ResponseField>

<ResponseField name="deleted" type="boolean">
  `true` when the bundle was removed.
</ResponseField>

## Errors [#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](/api-reference/errors).