List the ways a task of a project can start
curl --request GET \
--url https://api.runaether.dev/projects/{projectID}/start-options \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.runaether.dev/projects/{projectID}/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/projects/{projectID}/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/projects/{projectID}/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/projects/{projectID}/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/projects/{projectID}/start-options")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/projects/{projectID}/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>"
}
]
}Projects
List the ways a task of a project can start
Lists the ways a new task of the project can start, in a cloud sandbox or on one of the caller's own computers: where it runs, with which agent, the models, thinking levels and modes it may choose, and whether the caller can start it now.
Use this tool when you need to:
- Choose agent_type, model, reasoning_effort and interaction_mode for createTask
- Show the labels of the agents, models, thinking levels and modes a task may start with
- See whether the account can start a task now
Examples:
- GET /projects/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/start-options
Hints:
- projectID is the project's uuid; one that is not a uuid is 422 from the schema.
- 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'.
- Every sandbox item comes before any computer item, and only the caller's own computers are listed: a computer lists its items whether or not it can start the task now. A computer can.start reads unsupported project_has_no_repository in a project with no repository, and not_now no_checkout_on_computer when Aether knows no checkout of the project's repository there.
- Every model and level is selectable here, and no retired agent is listed. can is for a task the caller would create, as the caller's credential may start it, the account's standing read for the cheapest VM size getProjectRuntimeOptions lists, so can.start says whether a task can start at any size; a create at a size the balance does not cover is refused with 402 credits_exhausted.
- Any owner, admin, member or viewer of the project's organization may call it: a viewer reads can.start not_permitted with org_role_insufficient. A billing member is refused with 403 org_role_insufficient, a suspended organization with 403 org_suspended, and a project that does not exist, is archived or is in an organization the caller does not belong to is 404; 503 when the membership check is unavailable.
GET
/
projects
/
{projectID}
/
start-options
List the ways a task of a project can start
curl --request GET \
--url https://api.runaether.dev/projects/{projectID}/start-options \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.runaether.dev/projects/{projectID}/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/projects/{projectID}/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/projects/{projectID}/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/projects/{projectID}/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/projects/{projectID}/start-options")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.runaether.dev/projects/{projectID}/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>"
}
]
}