Skip to main content
POST
Fork a chat into a new chat of its task, or a new task in a sandbox or on one of your computers

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

taskID
string<uuid>
required
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
chatID
string<uuid>
required
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Body

application/json
idempotency_key
string<uuid>

Optional client-generated UUID, scoped to the caller and the chat's task. A repeat with the same key, chat and body answers the chat the first fork made and forks nothing; a repeat while the first is at work is 409 fork_in_progress; the same key with another body or chat is 409 idempotency_key_reused.

message
string

The new task's first prompt. Omitted, a prompt that says to continue the work. Refused beside this_task, whose new chat starts empty.

Minimum string length: 1
model
string

A model the destination lists for the chat's agent. Omitted, the chat's own model where the destination lists it, else the destination's default. Refused beside this_task.

Minimum string length: 1
reasoning_effort
string

A thinking level the destination lists for the model. Omitted, the chat's own where the destination lists it for the model, else the model's default. Refused beside this_task.

Pattern: ^[a-z][a-z0-9_]{0,31}$
to
object

Where a fork goes, a union on kind: this_task, a new chat of the chat's own task; sandbox, a new task in a cloud sandbox; or computer, a new task on one of the caller's own computers. The sandbox and computer members are the machine a create takes.

Response

Created

agent_session
object | null
required

The agent's own session behind the chat; null until the agent has one. A sandbox chat's was started by Aether, and it has one from the moment it has a checkpoint to continue from: it spans its first turn to its latest, and until its first turn (a chat forked into its task, seeded with its source's checkpoint) both its times are the chat's creation.

agent_type
enum<string>
required

The agent harness that runs a task, a profile or a connection: claude-code or claude_code is Claude Code, codex is Codex, opencode is OpenCode.

Available options:
codex,
claude-code,
opencode,
claude_code
archived
object | null
required

The chat's archive; null while it is not archived.

can
object
required

What the caller can do with the chat as things stand, each ability computed for them: send, sending it a message; compose, what the message may carry; steer, whether a message sent while a turn runs joins that turn, which says what a send would do whether or not a turn runs now; queue_for_later, a message that waits for the running turn to end; stop, stopping its turn; archive, archiving it and restoring it; remove, removing it; fork, forking it.

created_at
string<date-time>
required
forked_from
object | null
required

The chat this chat was forked from, in this task or another: it started from that chat's checkpoint, under its own harness session, and with a copy of its conversation. Null when it is no fork, when that chat's task was deleted, or when it is a session another person started in their own terminal.

forks
object[]
required

The tasks whose main chat was forked from this chat, newest first, at most 20.

id
string<uuid>
required
interaction_mode
string
required
Pattern: ^[a-z][a-z0-9_]{0,31}$
main
boolean
required

Whether this is the task's main chat, the one it was created with, which everything addressed to the task reaches. It is never archived.

model
string
required
Minimum string length: 1
name
string | null
required

The chat's first prompt on one line, cut to 200 characters; null before it has one.

Required string length: 1 - 200
notices
object[]
required

Things the person should know that need no answer.

outbox
object[]
required

The chat's messages the conversation does not show, oldest first. Always empty in a sandbox, whose waiting messages the conversation shows as queued turns.

Aether holds the message, and it can be taken back.

pending_inputs
object[]
required

Every request the chat's agent waits on, oldest first: in a cloud sandbox, the question or plan awaiting_input carries; on a person's computer, each permission request, question and plan open there, none once the chat is archived. Answer each with answerTaskChat, one on a computer while its can.answer is available.

The agent proposed a plan and waits for it to be approved or sent back.

reasoning_effort
string | null
required
Pattern: ^[a-z][a-z0-9_]{0,31}$
runs_on
object
required
status
enum<string>
required
Available options:
queued
stopping
object | null
required

A stop travelling to the chat's computer; null when none is, and always in a sandbox.

task_id
string<uuid>
required
waiting
object
required

Why the chat's oldest waiting message has not started. other_chat_turn: another chat's turn runs, which waits_for names. On a computer: task_start_pending while the task's start there is pending; turn_running while the chat's own turn runs; earlier_message while an earlier message of the chat is on its way; computer_unreachable while the computer cannot be reached; chat_being_forked while the chat's work is being handed to a fork; open_in_terminal, agent_starts_off, agent_limit, chat_busy, not_signed_in or agent_not_installed while the computer holds its run back for that reason; on_its_way once it is handed to the computer, which has not reported on it; with_agent once the agent has it and has not started it. In a sandbox: sandbox_not_ready while the task's sandbox is starting, resuming, stopping or preparing; billing_blocked, org_task_concurrency_exceeded, credits_exhausted or workspace_run_unavailable while the account's standing keeps the sandbox from starting, with the standing's own sentence; provider_overloaded while a turn waits to be retried; earlier_message while the task runs another chat's message first (the task's order, not the chat's); on_its_way while it is on its way to the agent.

waits_for
object | null
required

The turn another chat of the task runs while this chat's queue waits: one turn runs at a time per workspace. Set exactly when waiting's code is other_chat_turn.