Skip to main content
POST
Start a chat in a task's workspace

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}$

Body

application/json
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
interaction_mode
string

A mode the start option of agent_type lists. Omitted, the option's default mode.

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

A model the start option of agent_type lists (GET /tasks/{taskID}/start-options). Omitted, the option's default model.

Minimum string length: 1
reasoning_effort
string

A thinking level the start option lists for model. Omitted, the model's default_reasoning_effort says what the chat runs at.

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

Optional connection the chat runs on, one the task's creator holds; omitted, the creator's default connection for the harness.

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.