Skip to main content
POST
Cancel a session

Authorizations

Authorization
string
header
required

Your Reason API key from Settings > API. 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, automations:read, automations:write, agent_auth:read. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:debug is privileged: it expands diagnostic session events only for organization owners/admins.

Path Parameters

orgId
string
required

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

sessionId
string
required

The session id.

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.

status
string
required

Current public Session status.

mode
enum<string>
required

The cancel mode this request asked for.

Available options:
graceful,
hard