Create a Session
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.
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
data, next_page, and prev_page. Follow the returned opaque cursor rather
than constructing one.
Retrieve a Session
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
read and disables its other built-in tools:
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 for that
separate capability and its current limits.
Archive a Session
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
{ "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 for Audit pagination and export.
Session status
The public Session resource’sstatus field has four allowed values:
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:
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, includingsession.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
and 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:
An approval-required Custom tool follows the additional authorization path in
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 before depending
on an execution path. For compatibility and intentional differences, use the
Claude Managed Agents migration guide.