# Sessions (/api-v2/sessions)



A session is a causal state container for an agent workflow, not a cache entry. Creating one mints a default branch you append events to. Sessions are prefixed `ses_`; their branches are prefixed `br_`. See [sessions](/concepts/sessions) and the [sessions and branching guide](/guides/sessions-and-branching).

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

## Create a session [#create-a-session]

`POST /v2/sessions`

<ParamField body="base_bundle_ids" type="array">
  Optional list of `bnd_...` ids that seed the session's reusable prefix. Each must exist in this project. Defaults to an empty list.
</ParamField>

```bash
curl https://api.zumik.ai/v2/sessions \
  -H "Authorization: Bearer $ZUMIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "base_bundle_ids": ["bnd_01jy7n5t0x8mbs6y4p1ef7zrhk"] }'
```

```python
from zumik import Zumik

zk = Zumik()
session = zk.sessions.create(base_bundle_ids=[bundle.id])
branch_id = session.default_branch_id
```

```json
{
  "id": "ses_01jy7n7w2z9pcu7a5q2gh8askm",
  "object": "session",
  "project_id": "prj_01jy7n0a4c8m2t6v9q3wrxk7bd",
  "default_branch_id": "br_01jy7n7w30ardv8b6r3jk9btln",
  "status": "active",
  "base_bundle_ids": ["bnd_01jy7n5t0x8mbs6y4p1ef7zrhk"],
  "created_at": "2026-06-15T16:06:11Z"
}
```

<ResponseField name="id" type="string">
  Opaque session id, prefixed `ses_`.
</ResponseField>

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

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

<ResponseField name="default_branch_id" type="string">
  The id of the root branch created with the session, prefixed `br_`. Append events here, or fork from it. See [branches](/api-v2/branches).
</ResponseField>

<ResponseField name="status" type="string">
  One of `active`, `archived`, `tombstoned`.
</ResponseField>

<ResponseField name="base_bundle_ids" type="array">
  The base bundles, echoed back.
</ResponseField>

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

## Retrieve a session [#retrieve-a-session]

`GET /v2/sessions/{session_id}`

<ParamField path="session_id" type="string">
  The session id to fetch.
</ParamField>

```bash
curl https://api.zumik.ai/v2/sessions/ses_01jy7n7w2z9pcu7a5q2gh8askm \
  -H "Authorization: Bearer $ZUMIK_API_KEY"
```

Returns the same session object as create.

## Delete a session [#delete-a-session]

`DELETE /v2/sessions/{session_id}`

Removes the session record. Its branches and events become unreachable.

<ParamField path="session_id" type="string">
  The session id to delete.
</ParamField>

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

```json
{
  "id": "ses_01jy7n7w2z9pcu7a5q2gh8askm",
  "object": "session.deleted",
  "deleted": true
}
```

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

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

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

## Errors [#errors]

| Status | Code                    | When                                                     |
| ------ | ----------------------- | -------------------------------------------------------- |
| 400    | `invalid_request_error` | A referenced base bundle does not exist in this project. |
| 401    | `invalid_api_key`       | Missing or invalid API key.                              |
| 404    | `invalid_request_error` | The session does not exist in this project.              |

See the full table on [errors](/api-reference/errors).