List the ways a chat of a task can run
curl --request GET \
--url https://api.runaether.dev/tasks/{taskID}/start-options \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.runaether.dev/tasks/{taskID}/start-options"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.runaether.dev/tasks/{taskID}/start-options', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.runaether.dev/tasks/{taskID}/start-options",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/tasks/{taskID}/start-options"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.runaether.dev/tasks/{taskID}/start-options")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/tasks/{taskID}/start-options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"items": [
{
"agent_label": "<string>",
"agent_type": "codex",
"can": {
"change_pr_automation": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"compose": {
"attach": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_connection": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_interaction_mode": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_model": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_reasoning_effort": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"reference_files": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"use_slash_commands": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
}
},
"start": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
}
},
"choices": {
"attachment_types": [
"<string>"
],
"interaction_modes": [
{
"id": "<string>",
"label": "<string>"
}
],
"models": [
{
"default_reasoning_effort": {
"description": "<string>",
"label": "<string>"
},
"id": "<string>",
"label": "<string>",
"reasoning_efforts": [
{
"description": "<string>",
"id": "<string>",
"label": "<string>",
"selectable": true
}
],
"selectable": true
}
]
},
"defaults": {
"interaction_mode": "<string>",
"model": "<string>",
"reasoning_effort": "<string>"
},
"machine": {
"kind": "sandbox"
},
"machine_label": "<string>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}Tasks
List the ways a chat of a task can run
Lists the ways a chat of the task can run: with which agent, the models, thinking levels and modes it may choose, and whether the caller can start one now. A task on a person's computer lists one option per agent on its computer, which takes no other chat: can.start reads unsupported chats_not_addable.
Use this tool when you need to:
- Choose agent_type, model, reasoning_effort and interaction_mode for createTaskChat
- Show the labels of the models and thinking levels the task's chats hold, offered or not
Examples:
- GET /tasks/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/start-options
Hints:
- taskID is the task's lowercase uuid.
- Not paged. A sandbox's items hold one option per agent a cloud sandbox runs and a new selection may name, in the catalog's order (today codex and claude-code). An agent retired from new selections (today opencode) is listed only where a chat of the task already runs it. Each has machine ({"kind": "sandbox"} or {"kind": "computer", "computer_id": "..."}, exactly what a create will send as its machine; options with an equal machine are one place, offered once with a choice of agent), machine_label, agent_type, agent_label, can, choices and defaults.
- A computer's items hold one option per agent Aether runs on a person's computer (today claude-code). Its choices are what the agent's own CLI takes there: model default, the agent's own default there, then the models its CLI names (fable, opus, sonnet, haiku), each with thinking levels low to max, interaction mode default alone and no attachment types. Its defaults are model default, a null reasoning_effort and interaction_mode default: the computer's own settings. can.start reads unsupported with computer_cli_outdated or no_work_tree_folder when the computer's aether CLI cannot start a task, not_now with computer_unreachable, agent_starts_off or no_checkout_on_computer while it cannot now, and not_permitted credential_kind_not_admitted for a client app's grant or an agent. An agent the computer's bridge found signed out or missing reads available with the note not_signed_in or agent_not_installed: the start waits on the computer until it is put right. can.compose is what the bridge declared a run of the agent supports, and can.change_pr_automation reads unsupported pr_automation_unsupported.
- choices.models holds each model (id, label, selectable) with reasoning_efforts, the thinking levels it takes (id, label, description, selectable), empty when it takes none, and default_reasoning_effort, the words for what a null reasoning_effort runs (Codex chooses the level itself; Claude Code and OpenCode run their default level), null when it takes none. choices.interaction_modes holds each mode (id, label) and choices.attachment_types the media types a message may attach. Ids are open strings: show the label of an id you do not know.
- defaults is what a picker starts on: model, reasoning_effort (the agent's default level, null when the default model takes none) and interaction_mode. A request may also send no reasoning_effort, and the model's default_reasoning_effort says what that means. createTask and createTaskChat still require model and interaction_mode; a later change makes a create that leaves them out run with defaults.
- can holds start (whether a task or chat can be started with the option now: not_now or not_permitted with the account's standing, such as billing_blocked or org_suspended), compose (what its first message may carry: attach, reference_files, use_slash_commands, change_model, change_reasoning_effort, change_interaction_mode and change_connection) and change_pr_automation (whether the pull-request switches apply). Each is available with its notes, or not_now, unsupported or not_permitted with a reason: a code, an open set, and a sentence.
- VM sizes are getProjectRuntimeOptions', and the inference accounts an agent runs on are listConnections'. Computers are listComputers'.
- A model or thinking level a chat of the task holds that no new selection may name is listed with selectable false, after the selectable ones, so its label can be shown. A retired agent a chat of the task runs is offered like any other.
- can is for a chat of the task started by the caller: a reader who may not act in its chats reads can.start not_permitted with control_forbidden or org_role_insufficient.
- Any member of the task's organization may read it, a viewer included; a billing member is refused with 403 org_role_insufficient, a suspended organization with 403 org_suspended, and a task or chat outside the caller's reach is 404 not_found; 503 when the membership check is unavailable.
GET
/
tasks
/
{taskID}
/
start-options
List the ways a chat of a task can run
curl --request GET \
--url https://api.runaether.dev/tasks/{taskID}/start-options \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.runaether.dev/tasks/{taskID}/start-options"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.runaether.dev/tasks/{taskID}/start-options', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.runaether.dev/tasks/{taskID}/start-options",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.runaether.dev/tasks/{taskID}/start-options"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.runaether.dev/tasks/{taskID}/start-options")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/tasks/{taskID}/start-options")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"items": [
{
"agent_label": "<string>",
"agent_type": "codex",
"can": {
"change_pr_automation": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"compose": {
"attach": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_connection": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_interaction_mode": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_model": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"change_reasoning_effort": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"reference_files": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
},
"use_slash_commands": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
}
},
"start": {
"availability": "available",
"notes": [
{
"code": "<string>",
"message": "<string>"
}
]
}
},
"choices": {
"attachment_types": [
"<string>"
],
"interaction_modes": [
{
"id": "<string>",
"label": "<string>"
}
],
"models": [
{
"default_reasoning_effort": {
"description": "<string>",
"label": "<string>"
},
"id": "<string>",
"label": "<string>",
"reasoning_efforts": [
{
"description": "<string>",
"id": "<string>",
"label": "<string>",
"selectable": true
}
],
"selectable": true
}
]
},
"defaults": {
"interaction_mode": "<string>",
"model": "<string>",
"reasoning_effort": "<string>"
},
"machine": {
"kind": "sandbox"
},
"machine_label": "<string>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}{
"code": "account_deleting",
"error": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
]
}