> ## Documentation Index
> Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/sessions
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/sessions/{session_id}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v1/sessions/{session_id}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.