Skip to main content
POST
Merge a Reason into another
Everything the merged Reason holds moves: its Sessions with their history (its own conversation and Slack threads among them), its Loops with their schedules and run history, its files, its memory notes (lines into lacks are added; nothing is overwritten), the Slack channels it listens in, and its secrets, logins, skills, plugins and connection allowances wherever into has none of that name (the target’s own always win). The merged Reason is then deleted and leaves every list. Instructions are never overwritten: into takes the merged Reason’s when it has none, and when both have some instructions chooses between keep (default; the merged Reason’s are returned in instructions_left_behind) and append. into keeps its own sharing, look, model and computers, and the moved Sessions follow its sharing. Only the owner of both Reasons can merge them, and neither can be the main Reason. Calling it again with the same ids finishes a merge that stopped part way. Available where the workspace has the Merge Reasons early-access feature; 403 feature_not_enabled elsewhere. 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.

Body

application/json
into
string<uuid>
required

The caller's other named Reason that keeps everything: the Reason this one is merged into.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
instructions
enum<string>

What to do with this Reason's instructions when into has its own: keep (default) leaves into's unchanged, append adds this Reason's below them. A Reason without instructions takes this one's either way.

Available options:
keep,
append

Response

Where the merged Reason's work is now, and what moved.

reason_id
string<uuid>
required

The Reason that holds the merged Reason's work now: into, or the Reason into was itself merged into since.

merged_reason_id
string<uuid>
required

The merged Reason, now deleted.

sessions
integer
required

Sessions re-filed under reason_id, the merged Reason's own conversations among them.

loops
integer
required

Live Loops moved.

files
integer
required

Files (pinned Library items) moved.

notes
integer
required

Memory notes written into reason_id's memory.

notes_kept
integer
required

Memory notes that could not be copied (too large, refused, memory off); they stay in the merged Reason's memory folder.

slack_channels
integer
required

Slack channels reason_id listens in now because the merged Reason did.

instructions
enum<string>
required

What became of the merged Reason's instructions: none (it had none, or reason_id already says the same), moved (reason_id had none and took them), appended, or kept (reason_id kept its own; the merged Reason's are in instructions_left_behind).

Available options:
none,
moved,
appended,
kept
instructions_left_behind
string | null
required

The merged Reason's instructions when instructions is kept; otherwise null.