Skip to main content
POST
Create a task

Authorizations

Authorization
string
header
required

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

Path Parameters

orgID
string<uuid>
required

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
project_id
string<uuid>
required
prompt
string
required
Minimum string length: 1
agent_profile_id
string<uuid>

Optional agent profile the task is started through. Its connection pin applies to a task of the profile's agent unless runs_on chooses otherwise; the request's agent, model and effort are the task's.

auto_fix_ci
boolean

Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it.

auto_fix_pr_comments
boolean

Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it.

auto_rebase
boolean

Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it.

base_branch
string
Minimum string length: 1
context
object
idempotency_key
string<uuid>

Optional client-generated UUID, scoped to the authenticated user in the authenticated org. The first create with a key records it with the task; a retry with the same key and an equivalent request returns that same task (201, same body) without creating, admitting, or dispatching again, even if the task was since archived. Reusing a key for a different request fails with 409 code idempotency_key_reused and creates nothing.

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

Where a new task runs, a union on kind: sandbox, a cloud sandbox Aether runs, with its size, or computer, one of the caller's own computers. A start option's machine, as GET /projects/{projectID}/start-options lists it, is one as it is. Omitted, a sandbox of the project's default size.

merge_when_ready
boolean

Optional. True has the task squash-merge its own published pull request once external CI is green, Aether Review's verdict at the exact head is APPROVE, no review thread is unresolved and the task is idle. Omitted or false, the task never merges its own pull request.

model
string

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

Minimum string length: 1
post_pr_demo_video
boolean

Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it.

post_pr_screenshots
boolean

Optional per-task override. Omit to inherit the fresh project default; explicit true or false overrides it.

reasoning_effort
string

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

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

Optional initial task connection; an explicit choice is validated before the first turn. Omitted, the task runs on the pin of the agent profile agent_profile_id names when that profile pins a connection for the task's agent, else on the creator's default connection.

Response

Created

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