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 Autumn settings under API. 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.
`input_files`	both	Task-local filenames or storage paths already available to Autumn.
`version`	`/task`, `/task/start`	Model tier: `ranger` (default) or `scout`. Set at start only.

Keep clarify: false for automations. Human in the loop covers when the blocking question is worth it.

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",
  "status": "execute",
  "phase": "execute",
  "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",
  "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, 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" \
  -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 "https://api.autumn.ai/task" \
  -H "X-API-Key: $AUTUMN_API_KEY"

Status responses include the task phase/status, credit usage, compatibility, and last event metadata; see Task lifecycle for reading them correctly. 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 recent tasks.
`GET`	`/task/{task_id}`	Read status and metadata.
`GET`	`/task/{task_id}/stream`	Subscribe to live task events.
`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 another message to the same task.
`POST`	`/task/{task_id}/continue/stream`	Continue and stream the current turn.
`POST`	`/task/{task_id}/execute`	Ask the task to focus on output production.
`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