API overview

The Task API is the canonical HTTP surface for Autumn. Every task is backed by one sandbox and one agent.

https://api.autumn.ai

Authentication

Pass your API key as either header:

X-API-Key: YOUR_AUTUMN_API_KEY

Authorization: Bearer YOUR_AUTUMN_API_KEY

Create a key in Settings → Developer. Use the full key you copied when creating it; the shortened key shown later in settings is for display only. Keep it in an environment variable rather than in source.

Request fields

Field	Routes	Meaning
`prompt`	`/task`, `/task/start`	Natural-language instruction. On `/task/start`, this is appended to `task.brief`.
`task`	`/task/start`	`task.json`-style spec with `brief`, one optional `output`, inputs, and rules. The agent picks its own skills; any you send are ignored.
`clarify`	`/task`, `/task/start`	Defaults to `false`. `false` still plans, but does not stop for a question.
`output`	`/task`, `/task/start`	Optional output hint. Use `kind: "research"`, `"person"`, or `"company"` when your app already knows the desired shape. One object; an `outputs` list is not supported (a single-entry list is read as `output`, more entries return `400 invalid_request`).
`input_files`	both	Task-local filenames or storage paths already available to Autumn.
`version`	`/task`, `/task/start`	Model tier: `ranger` (default), `scout`, or `wren` (admin plans only). Set at start only.
`wait`	`GET /task/{task_id}`, `GET /task/{task_id}/state`	Query parameter from 0–50 seconds; returns on done, the first status change, or timeout.

Keep clarify: false for automations. Human in the loop covers when the blocking question is worth it. Starting always returns immediately; wait on /task and /task/start is accepted for compatibility and does not block. On /continue and /execute, the legacy body field "wait": true blocks for the turn; other values return immediately. Integer timeouts are only supported on the two GET status routes.

Start from a prompt

Use this when your app has natural language and wants Autumn to infer the task shape.

curl -sS -X POST "https://api.autumn.ai/task" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find 20 AI infrastructure startups hiring founding engineers.",
    "output": {
      "id": "ai-infra-startups",
      "kind": "research",
      "path": "outputs/ai-infra-startups.jsonl",
      "target_count": 20
    },
    "clarify": false
  }'

{
  "task_id": "8fab6f34",
  "state": "submitted",
  "done": false,
  "status": "plan",
  "phase": "plan",
  "stream_url": "/task/8fab6f34/stream",
  "output_url": "/task/8fab6f34/output"
}

Start from a task spec

Use this when your app already knows the task shape. prompt is optional and is appended to the task brief before the agent starts.

curl -sS -X POST "https://api.autumn.ai/task/start" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "brief": "Find 20 AI infrastructure startups hiring founding engineers.",
      "output": {
        "id": "ai-infra-startups",
        "kind": "research",
        "path": "outputs/ai-infra-startups.jsonl",
        "target_count": 20,
        "schema": {
          "title": { "type": "str" },
          "notes": { "type": "str" },
          "source_url": { "type": "url" },
          "sources": { "type": "list[url]" }
        },
        "schema_order": ["title", "notes", "source_url", "sources"]
      }
    },
    "prompt": "Prioritize current founding engineer or early engineer roles.",
    "clarify": false
  }'

{
  "task_id": "8fab6f34",
  "state": "working",
  "done": false,
  "status": "execute",
  "phase": "execute",
  "stream_url": "/task/8fab6f34/stream",
  "output_url": "/task/8fab6f34/output"
}

With clarify: true, Autumn initializes the task in plan mode and can ask before execution. See The task model for how the two start modes differ. Use GET /task/metaprompt when another agent or app needs to generate a clean task.json-style spec before calling /task/start.

Continue a task

Send new instructions to the same sandboxed task: refinements, more rows, fixes, a new output shape, or follow-up constraints.

curl -sS -X POST "https://api.autumn.ai/task/8fab6f34/continue" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Add founder LinkedIn URLs for every row, then continue until there are 25 rows."
  }'

Every route that advances a task has a streaming twin, with the same body and an SSE response. They are listed in the route map below, and Live messages covers the event names and SSE handling.

Read status and output

curl -sS "https://api.autumn.ai/task/8fab6f34?wait=50" \
  -H "X-API-Key: $AUTUMN_API_KEY"

curl -sS "https://api.autumn.ai/task/8fab6f34/output?limit=100" \
  -H "X-API-Key: $AUTUMN_API_KEY"

curl -sS -D headers.txt \
  "https://api.autumn.ai/task/8fab6f34/output?format=csv&limit=100" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -o page.csv

curl -sS "https://api.autumn.ai/task" \
  -H "X-API-Key: $AUTUMN_API_KEY"

Status responses include state, done, message, progress, and version, as well as the legacy status, phase, and activity fields. status: "plan" is the resting phase before and after every turn, so it never means an execute call is pending. Rows already saved are readable from /output while done is still false; progress.rows says how many. See Task lifecycle for reading them correctly. CSV returns only the requested page and uses X-Next-Cursor when more rows remain. Output responses return rows from the active output file; see Outputs and sources for their shape.

Stop

Stop a task when the caller explicitly cancels it. The task returns to plan.

curl -sS -X POST "https://api.autumn.ai/task/8fab6f34/stop" \
  -H "X-API-Key: $AUTUMN_API_KEY"

Route map

Method	Path	Use
`POST`	`/task`	Start from a prompt.
`POST`	`/task/stream`	Start from a prompt and stream the current turn.
`POST`	`/task/start`	Start from a task spec plus optional prompt.
`POST`	`/task/start/stream`	Start from a task spec and stream the current turn.
`GET`	`/task`	List tasks, 50 per page; follow `X-Next-Cursor` for more.
`GET`	`/task/{task_id}`	Read status and metadata.
`GET`	`/task/{task_id}/state`	Read state and queued work; accepts the same `wait=0-50` query.
`GET`	`/task/{task_id}/stream`	Subscribe to quiet status changes; add `?verbose=1` for the legacy raw feed.
`GET`	`/task/{task_id}/output`	Fetch output rows.
`GET`	`/task/{task_id}/outputs`	List named output artifacts.
`GET`	`/task/{task_id}/outputs/{output_id}`	Fetch rows for one output artifact.
`POST`	`/task/{task_id}/continue`	Send or queue another message to the same task.
`POST`	`/task/{task_id}/continue/stream`	Continue and stream the current turn.
`POST`	`/task/{task_id}/execute`	Run another output turn when the last one ended without rows. Not needed after a normal start; returns `409 already_complete` once the task has its rows.
`POST`	`/task/{task_id}/execute/stream`	Execute and stream the current turn.
`POST`	`/task/{task_id}/stop`	Stop a run and return the task to plan.
`GET`	`/credits`	Check credits.
`POST`	`/tasks/draft`	Create an empty task to attach uploads to.
`POST`	`/upload-url`	Presign a `.csv`/`.txt`/`.md` upload for a task.
`POST`	`/validate-upload`	Validate an uploaded file and get its `input_files` name.

Errors

Status codes and the ones worth designing around.

Task lifecycle

Telling a finished task from one that has not started.

Reference

Endpoints

Authentication

Request fields

Start from a prompt

Start from a task spec

Continue a task

Read status and output

Stop

Route map

Next

Errors

Task lifecycle

​Authentication

​Request fields

​Start from a prompt

​Start from a task spec

​Continue a task

​Read status and output

​Stop

​Route map

​Next

Errors

Task lifecycle

Authentication

Request fields

Start from a prompt

Start from a task spec

Continue a task

Read status and output

Stop

Route map

Next