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

# Sessions

> Create, inspect, and update durable Sessions, and distinguish API status from execution events.

A Session keeps the history of an interaction with an Agent. Create it from an
Agent and an Environment, send input, and read ordered events to follow the work.
One Session can contain multiple Turns, Runs, and attempts.

The Session resolves an Agent Version and records the Environment configuration
it starts with. The public Environment resource is reusable and unversioned;
its frozen Session snapshot is not a separately versioned Environment resource.
See [Environments](/concepts/work-environments) for the configuration boundary.

## 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": {
    "type": "agent",
    "id": "agent_0123456789abcdef0123456789abcdef"
  },
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "title": "Quarterly close review",
  "vault_ids": ["vlt_0123456789abcdef0123456789abcdef"]
}
```

| Field | Required | Meaning |
| - | - | - |
| `agent` | Yes | Select an existing Agent by ID, or by a `type: "agent"` reference with an optional exact `version`. Use `type: "agent_with_overrides"` with an existing Agent ID for supported Session-specific overrides. |
| `environment_id` | Yes | The reusable Environment whose execution configuration is recorded for this Session. |
| `budget` | No | A `limit` budget with `max_list_cost.amount` and USD currency. |
| `initial_events` | No | Up to 50 initial message or Outcome-definition events. More than one entry requires an `Idempotency-Key`. |
| `metadata` | No | Up to 16 caller-owned string pairs with no execution semantics. |
| `resources` | No | Supported repository, file, and memory Resources attached to the Session. |
| `title` | No | A display title, or `null`. |
| `vault_ids` | No | Ordered Vault attachments. |
| `acted_as` | Conditional | An explicitly delegated Principal. API-key creation requires it when the resolved Agent has governed Connection bindings. The Principal must be active in the Workspace and have `act_as` permission on the Agent. |
| `capture_policy` | No | An explicit capture/learning-consent policy. Supplying it requires a root/admin API key authorized for the Workspace; omission uses the no-learning-consent default. |

Authentication supplies Organization and Workspace authority. `acted_as` does
not retarget the API key, authenticate your application's user, or grant access
to a Connection. Your backend must authenticate the user and choose only an
authorized Principal. See [Session identity](/reference/access#session-identity).

For a connected delegated Session, driving or continuing the Session rechecks
the acting Principal’s required `act_as` permission on the Agent. Removing that
permission causes `403 policy.denied`; an existing placement or receipt does
not grant permission for a new action.

The Agent selector does not create an arbitrary inline Agent. An override
references an existing Agent and leaves its authored head unchanged.

Use an `Idempotency-Key` for retryable creation. It is required when
`initial_events` contains more than one entry. An identical keyed retry rejoins
the same retained creation; reuse with different input conflicts. Deleting the
original Session does not let the key recreate it: replay then returns
`409 validation.idempotency_conflict`. A successful create
returns `201` with the Session resource, not a completed Agent response.

## List Sessions

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

The directory is newest-first by default and supports Agent and creation-time
filters. Archived Sessions are excluded unless requested. Pagination returns
`data`, `next_page`, and `prev_page`. Follow the returned opaque cursor rather
than constructing one.

## Retrieve a Session

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

The following is an excerpt showing selected response fields, not a complete
Session resource:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "sess_0123456789abcdef0123456789abcdef",
  "agent": {
    "id": "agent_0123456789abcdef0123456789abcdef",
    "name": "close-reviewer",
    "type": "agent",
    "version": 3
  },
  "environment_id": "env_0123456789abcdef0123456789abcdef",
  "status": "idle",
  "title": "Quarterly close review",
  "type": "session"
}
```

The full resource also contains the resolved Agent configuration, Resources,
Vault IDs, budget, metadata, timestamps, usage, statistics, outcome evaluations,
and archival state. An Automation-created Session may contain `automation_id`.

`stats.active_seconds`, when present, is an activity statistic, not a receipt
that a process, sandbox allocation, or attached Computer was released. Neither
public `idle` nor a `session.status_paused` event certifies physical cleanup.
The public API currently exposes no compute-release receipt.

## Update a Session

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

This example replaces the Session's tool collection with a built-in toolset
that enables `read` and disables its other built-in tools:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "agent": {
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": { "enabled": false },
        "configs": [{ "name": "read", "enabled": true }]
      }
    ]
  },
  "title": "Quarterly close, final review"
}
```

`agent.mcp_servers`, `agent.tools`, `budget`, `metadata`, `title`, and `vault_ids`
are optional update fields. Supplied tool, MCP-server, and Vault collections
are complete replacements: include every entry you intend to retain. Metadata
uses its resource-specific patch semantics.

Session-specific Agent changes govern subsequent Runs and produce a new
hash-bound runtime configuration. Already-created Runs retain their original
immutable RunSpec. Updating the Session does not update the reusable Agent.
Selecting a tool also does not grant account access or make an unsupported
harness capability available.

A vendor-specific Computer tool type is not an Agent toolset declaration in
this API. See [Computer and Screens](/concepts/computer-and-screens) for that
separate capability and its current limits.

## 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.

Archiving unfinished work returns `409 runtime.invalid_transition`, including
live asynchronous work or accepted input still queued. Let the work settle or
interrupt it before retrying. Public `idle` alone does not prove archive readiness.

## Retention and content availability

Retention is applied from the Workspace policy recorded at Session admission.
The public Workspace update API does not accept a retention-policy field, and
the public API provides no way to fast-forward expiry. Internal governance
configuration is not a customer configuration endpoint.

There is currently no public operation that erases retained content while
keeping the Session available. Content may become unavailable through the
configured retention lifecycle; deleting a Session instead removes public
access to the whole Session. Expiry or an unavailable read is not evidence that
every archival object or external cleanup operation has physically completed.

## Delete a Session

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

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

Repeating deletion does not create a replacement Session or a second deletion
record. For an existing Session, the retained `session.deleted` audit record has empty detail (`{}`)
and preserves the original actor and Session identifier; those identifiers are
not anonymous. Neither that record nor public unreadability proves that every
external cleanup operation has physically completed.

With permission to read the workspace Audit log, query `GET /v1/audit` with
`action=session.deleted`, `resource_kind=session`, and `resource_id` set to the
Session ID. The published record has `outcome=succeeded` after the local aggregate
and applicable fallback cleanup steps; it does not certify completion of every
durable cleanup worklist, participation cleanup, or external process. See
[Export your log](/guides/export-your-log) for Audit pagination and export.

## Session status

The public Session resource's `status` field has four allowed values:

| Public status | How to interpret it |
| - | - |
| `rescheduling` | A rescheduling value in the public contract. Handle it even when the selected execution path does not emit it. |
| `running` | Work is executing or being prepared or reconciled. |
| `idle` | No actively running work is represented by this resource state. The Session may still be waiting for input, approval, or a tool result. |
| `terminated` | The Session has ended or been archived. Read execution events to distinguish success, failure, and cancellation. |

**`idle` does not, by itself, prove that the requested work is finished.** The
public resource status summarizes a richer execution lifecycle. For an
unarchived Session, the current projection maps execution states as follows:

| Execution state | Public `status` |
| - | - |
| `pending`, `waiting`, `idle`, `paused` | `idle` |
| `provisioning`, `running`, `reconciling` | `running` |
| `completed`, `failed`, `canceled` | `terminated` |

Archival projects to `terminated`. The `rescheduling` enum member is not an
additional edge in the execution-state mapping above. Do not construct a
transition machine from the public enum alone.

A normally finished turn emits `session.status_idle` with
`stop_reason: "end_turn"`. A `requires_action` stop reason instead describes a
wait; correlate the matching question, approval, or tool result before treating
the requested turn as settled.

## Execution events and settlement

Execution events retain their own names, including `session.status_waiting`,
`session.status_idle`, `session.status_completed`, `session.status_failed`, and
`session.status_canceled`. They are not renamed to match the public resource's
four-value `status` field.

For a sequential interaction, begin following after the
accepted input event's `seq`. An idle event with
`payload.stop_reason: "requires_action"` is an intermediate boundary, not the
final result. Inspect `run.requires_action`, handle the exact wait, and keep
following the continuation. Other idle boundaries settle the current turn;
the completed, failed, and canceled events describe terminal execution outcomes.

A dropped stream is not settlement. See [Resume a stream](/guides/resume-a-stream)
and [Add an agent to your app](/guides/add-an-agent-to-your-app) for cursor and
continuation handling.

The following schematic shows one allowed Custom-tool interaction without a
human approval step. It omits other emitted events:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
  participant App as Your application
  participant Session as Checkfu Session
  participant Agent as Agent execution
  App->>Session: Send user.message
  Session-->>App: Accepted input event and seq
  Session->>Agent: Start work
  Agent->>Session: Request a declared Custom tool
  Session-->>App: run.requires_action (custom_tool)
  Note over App: Authorize and execute the application handler
  App->>Session: user.custom_tool_result for the recorded tool_use_id
  Session->>Agent: Continue with the result
  Session-->>App: Final response and settled execution boundary
```

An approval-required Custom tool follows the additional authorization path in
[Handle an approval](/guides/handle-an-approval). Approval alone does not run the
application handler or supply its result.

## Resources

Session Resources use a unified vocabulary: `repository` attaches a 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 and events

A Turn is one user-meaningful interaction. Independent input or follow-up work
owns a distinct Run intent; supported steering contributes to its targeted Run.
Matching approval decisions, question answers, and tool results continue the
original Run. Internal generations, tool rounds, waits, and recovery do not
create a new public Run.

Active and recovering work retains its original resolved inputs under current
authority. A RunAttempt, where exposed, records an execution attempt rather than
another user request. Session events remain append-only and ordered; an
accepted input event does not establish a completed Run or external effect.

The Workspace Run query reads the Session journal: `kind: "native"` carries
no public Principal or execution identity, while `kind: "attributed"` exposes
its committed `acted_as` as `principal` and carries its execution identity.
Do not treat missing native identity as an optional attributed value.

Run list pages use opaque keyset cursors. Erased journals cannot be rebuilt
from incomplete replay facts, and unavailable lifecycle evidence must not be
presented as an earlier healthy status.

Checkfu also exposes Run-control, checkpoint, fork, diff, export, and Watch
operations. Check [capability status](/getting-started/status) before depending
on an execution path. For compatibility and intentional differences, use the
[Claude Managed Agents migration guide](/guides/coming-from-claude-managed-agents).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.