Skip to main content
POST
Keep a task's full context

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

Response

OK

agent_type
enum<string> | null
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_at
string<date-time> | null
required
auto_fix_ci
boolean
required
auto_fix_pr_comments
boolean
required
auto_rebase
boolean
required
binding
object | null
required
campaign
object | null
required
can
object
required

What the caller can do with the task as things stand, each ability computed for them and the kind of credential they hold: add_chat, starting a chat beside its main chat; rename, giving it a name; archive, archiving it and restoring it; pin, pinning it; change_pr_automation, its six pull-request switches (auto_fix_ci, auto_fix_pr_comments, auto_rebase, post_pr_screenshots, post_pr_demo_video, merge_when_ready), whose notes say when merge_when_ready cannot turn on; download, downloading its files; stop, stopping its main chat's turn; fork, carrying its main chat's work into a new task, in the cloud or, for a task on a computer, on a computer; connect_live, opening a live connection to its machine (connectTask), available for a stopped sandbox, which the connection can start. The operation an ability governs refuses with the code and sentence the ability shows. A download may still be refused by what only its workspace knows: task_has_no_files, task_branch_missing and workspace_outdated; a live connection by what only the call knows: live_protocol_unsupported, too_many_live_connections, and the account's standing when it starts a sandbox.

conversation
object
required
created_at
string<date-time>
required
creator_reauth_required
boolean
required
head_branch
string | null
required
Minimum string length: 1
id
string<uuid>
required
interaction_mode
string | null
required
Pattern: ^[a-z][a-z0-9_]{0,31}$
latest_message_revision
integer<int64>
required

Maximum revision_sequence of currently stored task messages, including soft-deleted rows; zero means no messages. Compare equality only: hard deletion can decrease it. Not an activity/stream cursor or a task-wide version.

Required range: 0 <= x <= 9007199254740991
latest_status_message
string | null
required
machine
object
required

Where the task runs: a cloud sandbox, or a folder on one of its creator's computers.

merge_when_ready
boolean
required

Whether the task merges its own published pull request once it is ready: external CI green, Aether Review's APPROVE at the exact head, no unresolved review thread and the task idle.

model
string | null
required
Minimum string length: 1
name
string
required
Minimum string length: 1
org_id
string
required
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
outcome
enum<string>
required

The one word a client renders for the task: its lifecycle rolled up with its pull request's state. status is the lifecycle alone.

Available options:
running,
awaiting_input,
approved,
awaiting_ci,
merged,
unmerged,
errored,
archived
parent_task_id
string<uuid> | null
required
pinned_at
string<date-time> | null
required
post_pr_demo_video
boolean
required
post_pr_screenshots
boolean
required
pr_review_mode
enum<string> | null
required
Available options:
review_only,
fix_on_request,
apply_fixes
pr_review_summary
object | null
required
primary_pull_request
object | null
required
project
object
required
project_id
string<uuid>
required
pull_requests
object[]
required
reasoning_effort
string | null
required
Pattern: ^[a-z][a-z0-9_]{0,31}$
review_subject_pull_request
object | null
required
run_context
object | null
required
runs_on
object
required
runtime_timing
object
required
save_to_github
enum<string>
required
Available options:
offered,
saved,
not_started,
agent_child,
bound_at_creation
source
enum<string>
required
Available options:
manual,
web,
mobile,
cli,
ci,
sentry,
linear,
slack,
automation,
pr_review,
teleport,
agent,
delegation
source_metadata
object | null
required
start
object
required

What still has to happen before the task's first turn runs: on its computer, or, for a task forked from a chat on a computer, on that computer, which hands the chat's work over. null for any other cloud task, for a person's own checkout, and once the first run has started or ended.

status
enum<string>
required
Available options:
queued
updated_at
string<date-time>
required
url
string<uri>
required

The task's page in the Aether web app.

Minimum string length: 1
usage
object
required
user_id
string<uuid> | null
required
plan_progress
object