Skip to main content
POST
Make a Reason the main one
Every person has exactly one main (primary) Reason in a workspace: it is listed first, is never deleted, and holds their unfiled Sessions and Loops. This moves that role to one of the caller’s own named Reasons in one step. The chosen Reason keeps its id, name, instructions, memory and Sessions, and its conversation becomes the caller’s main conversation; the former main becomes an ordinary named Reason that keeps its own conversation and history. Only a personal Reason that has never been shared with people can become main, and a main Reason shared with others is not replaced. Scope: run

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, devices:read, devices:write, devices:use, computers:read, computers:write, ssh:write, knowledge:read, memory:read, memory:write, skills:read, skills:write, pages:read, pages: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. devices:write, devices:use, computers:read, computers:write, ssh:write, network:read and network:write are opt-in, excluded from default keys. computers:read lists visible cloud and connected computers without waking them or granting execution access. devices:read discovers local Device targets; devices:use separately consents to local execution, so a discover-and-run local workflow needs both. devices:write manages enrollment and device grants; computers:write creates or deletes cloud computers; ssh:write manages retained SSH access. 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).

Scopes

run

Path Parameters

orgId
string
required

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

reasonId
string<uuid>
required

The Reason id, returned as id by listReasons and createReason.

Response

The caller's new main Reason and the former one.

main_reason_id
string<uuid>
required

The caller's main (primary) Reason now: the Reason this call named.

previous_main_reason_id
string<uuid>
required

The former main Reason, now an ordinary named Reason with its own conversation.

session_id
string | null
required

The caller's main conversation now; null until the new main Reason is first opened.