Sessions

Create, list, retrieve, update, archive, and run CMA-shaped Sessions.

A Session is a durable conversation with one resolved Agent Version and one versioned execution Environment. Checkfu follows the Claude Managed Agents Session resource and SDK layout. Its only naming substitution is automation_id for CMA’s deployment_id.

Create a Session

POST /v1/sessions

{
  "agent": { "id": "agent_0123456789abcdef0123456789abcdef" },
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "title": "Quarterly close review",
  "vault_ids": ["vlt_0123456789abcdef0123456789abcdef"]
}

The body matches CMA’s common Session-create path:

Field	Required	Meaning
agent	Yes	Select an Agent by ID and optional exact version, or supply the supported inline Agent configuration. The resolved Agent Version is embedded in the Session.
environment_id	Yes	The Environment containing the versioned package, setup, and networking recipe used by Runs.
budget	No	A CMA limit budget with max_list_cost.amount and USD currency.
initial_events	No	Up to 50 CMA initial events.
metadata	No	Up to 16 caller-owned string pairs with no execution semantics.
resources	No	Repository, file, and memory Resources attached to the Session.
title	No	A display title, or null.
vault_ids	No	Ordered Vault attachments.

Authentication supplies Organization and Workspace authority. A create request does not accept a Principal, Deployment, Revision, sandbox profile, wire version, client reference, or compatibility selector.

An Idempotency-Key is optional. Repeating the identical keyed request returns the original Session. A successful create returns 201 with the Session resource.

List Sessions

GET /v1/sessions

The directory is newest-first by default. It supports CMA’s Agent and creation time filters plus Checkfu’s bounded automation_id terminology substitution. Archived Sessions are excluded unless requested. Pagination returns data, next_page, and prev_page.

Retrieve a Session

GET /v1/sessions/{session_id}

{
  "id": "sess_0123456789abcdef0123456789abcdef",
  "agent": {
    "id": "agent_0123456789abcdef0123456789abcdef",
    "name": "close-reviewer",
    "type": "agent",
    "version": 3,
    "mcp_servers": [],
    "tools": []
  },
  "archived_at": null,
  "budget": null,
  "created_at": "2026-08-27T18:00:00.000Z",
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "metadata": {},
  "outcome_evaluations": [],
  "resources": [],
  "stats": {},
  "status": "idle",
  "title": "Quarterly close review",
  "type": "session",
  "updated_at": "2026-08-27T18:00:00.000Z",
  "usage": {},
  "vault_ids": []
}

The resource contains the resolved Agent Version snapshot, Environment ID, Resources, Vault IDs, budget, metadata, title, lifecycle state, timestamps, usage, statistics, and outcome evaluations. An Automation-created Session may also contain automation_id.

Update a Session

POST /v1/sessions/{session_id}

{
  "agent": { "tools": [{ "type": "computer_20250124", "name": "computer" }] },
  "title": "Quarterly close, final review"
}

The body follows CMA: agent.mcp_servers, agent.tools, budget, metadata, title, and vault_ids are optional. Supplied collections are complete replacements. Agent changes govern subsequent Runs and therefore produce a new hash-bound runtime configuration; already-created Runs retain their original immutable RunSpec.

Archive a Session

POST /v1/sessions/{session_id}/archive

Archive is one-way and retry-safe. It stops new work while retaining the Session for reads and evidence. The response is the archived Session resource.

Delete a Session

DELETE /v1/sessions/{session_id}

Deletion permanently erases the Session and returns { "id": "sess_…", "type": "session_deleted" }. Use archive when the goal is retirement rather than erasure.

Resources

Session Resources use CMA’s unified vocabulary:

• repository attaches a GitHub repository snapshot;
• file attaches an uploaded File; and
• memory attaches a MemoryStore.

Use /v1/sessions/{session_id}/resources to list or add supported Resources, and /v1/sessions/{session_id}/resources/{resource_id} to retrieve, update, or delete one.

Runs, events, and threads

Each turn is an immutable Run derived from the Session’s current hash-bound Agent and Environment configuration. Session events remain append-only and ordered. Multiagent coordination is exposed under /v1/sessions/{session_id}/threads with the CMA SDK hierarchy.

Checkfu also retains richer event, Run-control, checkpoint, fork, diff, export, and watch operations. These are additive capabilities; they do not change the CMA Session create, retrieve, update, archive, delete, Resource, or SDK shapes.