Skip to main content
POST
Cancel a session

Authorizations

Authorization
string
header
required

Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, knowledge:read, memory:read, memory:write, skills:read, skills:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. network:read and network:write are opt-in, excluded from default keys. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Path Parameters

orgId
string
required

Organization id or slug. Resolve it with GET /v3/self.

sessionId
string
required

The session id, returned as session_id by createSession and listSessions.

Body

application/json
mode
enum<string>
default:graceful

graceful (default) stops the agent and tries to preserve the workspace with a final snapshot before the Session ends. hard stops immediately without waiting for a snapshot; the Session resumes from its last verified checkpoint. A later hard request upgrades an in-progress graceful cancel.

Available options:
graceful,
hard

Response

Cancellation requested.

ok
boolean
required

True when this request newly flagged, or upgraded, the cancellation.

requested
boolean
required

True when cancellation is requested for the Session, by this or an earlier request. The Session may still be stopping.

status
string
required

Public Session status read after this request: suspended once the Session has stopped (at once for a Session that had not started), running while a running Session is still stopping.

mode
enum<string>
required

The cancel mode this request asked for.

Available options:
graceful,
hard