Sessions
Create, retrieve, and delete causal state containers for agent workflows. A session holds a default branch and an append-only event history.
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 and the sessions and branching guide.
All requests require a bearer API key. See authentication.
Create a session
POST /v2/sessions
base_bundle_idsarrayOptional list of bnd_... ids that seed the session's reusable prefix. Each must exist in this project. Defaults to an empty list.
curl https://api.zumik.ai/v2/sessions \
-H "Authorization: Bearer $ZUMIK_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "base_bundle_ids": ["bnd_01jy7n5t0x8mbs6y4p1ef7zrhk"] }'from zumik import Zumik
zk = Zumik()
session = zk.sessions.create(base_bundle_ids=[bundle.id])
branch_id = session.default_branch_id{
"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"
}idstringOpaque session id, prefixed ses_.
objectstringAlways session.
project_idstringThe owning project.
default_branch_idstringThe id of the root branch created with the session, prefixed br_. Append events here, or fork from it. See branches.
statusstringOne of active, archived, tombstoned.
base_bundle_idsarrayThe base bundles, echoed back.
created_atstringRFC 3339 creation timestamp.
Retrieve a session
GET /v2/sessions/{session_id}
session_idstringpathrequiredThe session id to fetch.
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 /v2/sessions/{session_id}
Removes the session record. Its branches and events become unreachable.
session_idstringpathrequiredThe session id to delete.
curl -X DELETE https://api.zumik.ai/v2/sessions/ses_01jy7n7w2z9pcu7a5q2gh8askm \
-H "Authorization: Bearer $ZUMIK_API_KEY"{
"id": "ses_01jy7n7w2z9pcu7a5q2gh8askm",
"object": "session.deleted",
"deleted": true
}idstringThe deleted session id.
objectstringAlways session.deleted.
deletedbooleantrue when the session was removed.
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.
Bundles
Create, retrieve, and delete immutable ordered sets of artifact references. Bundles assemble artifacts into a reusable agent prefix.
Branches and events
Fork session branches and append events with optimistic concurrency. Compare-and-swap on branch version and head event id prevents silent history rewrites.