Task API

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

https://api.autumn.ai

X-API-Key: YOUR_AUTUMN_API_KEY

Autumn also accepts Authorization: Bearer YOUR_AUTUMN_API_KEY. Use GET /task/metaprompt when another agent or app needs to generate a clean task.json-style spec before calling /task/start.

Core Ideas

One task

Store the returned task_id. It is the handle for status, streaming, continuation, files, and output.

Two start modes

Start from a prompt with /task, or start from a task.json-style spec with /task/start.

One planning flag

clarify:false plans without asking. clarify:true allows a blocking planning question.

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.

Use clarify:false for API automations. Use clarify:true only when the caller is present and a wrong assumption would be more expensive than a short question.

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: YOUR_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"
}

Set clarify:true when you want Autumn to pause in plan mode if the task has a genuinely blocking ambiguity.

{
  "prompt": "Find interesting AI companies for my thesis.",
  "clarify": true
}

Model Tiers

Every task runs on one model tier, chosen at start with version and fixed for the life of the task.

`version`	Tier	Character
`ranger`	Ranger	Most capable model, deepest reasoning. The default when `version` is omitted.
`scout`	Scout	Fast responses on a tuned harness.

curl -sS -X POST "https://api.autumn.ai/task" \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find 20 AI infrastructure startups hiring founding engineers.",
    "version": "scout",
    "clarify": false
  }'

Reach for scout on bounded, well-specified work where latency matters more than depth, and stay on ranger for open-ended research. Read the tier back from GET /task/{task_id} as tier. version only applies to the start routes. /task/{task_id}/continue and /task/{task_id}/execute stay on the tier the task started with. Any value other than ranger or scout is rejected with 403 and {"error": "forbidden"}: pinned selectors such as scout@<build_id> address internal builds and are not available on customer accounts.

Start From A Task Spec

Use this when your app already knows the task shape. The prompt field is optional and is appended to the task brief before the agent starts. Choose /task/start when you have enough structure to avoid schema inference:

enrichment jobs with known people or companies
workflows generated by your own app
repeatable research jobs with a known output schema
tasks restored from a saved task.json

Choose /task when you only have a user request and want Beanstalk to infer the task contract.

curl -sS -X POST "https://api.autumn.ai/task/start" \
  -H "X-API-Key: YOUR_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.

Outputs

output is the shape signal. It tells Beanstalk where durable rows should go for the current task contract. Keep it singular; if the desired artifact changes later, continue in plan mode and replan the task before executing again.

Kind	Use	Typical path
`research`	Lists, claims, evidence, jobs, sources, broad web research.	`outputs/ai-infra-startups.jsonl`
`person`	Rich person profiles, identity resolution, social links, relationships.	`outputs/scott-stephenson.jsonl`
`company`	Company profiles, funding, team, hiring, tech stack, news.	`outputs/deepgram.jsonl`

The same Beanstalk agent loop plans, executes, writes files, and streams events for every output kind. GET /task/{task_id}/output returns the task output rows, and GET /task/{task_id}/outputs lists known row artifacts for readback and compatibility.

Stream Events

Use /stream variants for the active turn, or subscribe to an existing task:

curl -N "https://api.autumn.ai/task/8fab6f34/stream" \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY"

Useful event names:

Event	Meaning
`tool_start`	A task operation or tool call began.
`tool_result`	A task operation or tool call produced a result.
`text_delta`	Assistant or status text from the sandboxed agent.
`beanstalk_error`	A user-visible task error.
`done`	The current turn finished.

GET /task/{task_id}/stream is task-specific. It only streams events for that task_id. If the current turn is already active, recent events are replayed. When the turn emits done, the stream can close; reconnect later only if you need the next active turn. Polling remains supported with GET /task/{task_id} and GET /task/{task_id}/output. To read a specific output, use GET /task/{task_id}/outputs/{output_id} or pass ?output=output_id to /output.

Continue A Task

Send new instructions to the same sandboxed task. Use this for refinements, more rows, fixes, or follow-up constraints.

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

Streaming form:

curl -N -X POST "https://api.autumn.ai/task/8fab6f34/continue/stream" \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Add founder LinkedIn URLs." }'

Read Status And Output

curl -sS "https://api.autumn.ai/task/8fab6f34" \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY"

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

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

Status responses include the task phase/status, credit usage, compatibility, and last event metadata. Output responses return rows from the active output file. Internal lineage and validation metadata may exist in storage, but downloads and UI exports should not expose internal fields unless explicitly requested by an internal tool.

Stop

Stop a task when the caller explicitly cancels it.

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

Attach A CSV Or Text File

Autumn accepts .csv, .txt, .md, and .markdown uploads up to 10 MB and 10,000 rows. Uploading is three calls: create a task to attach to, presign, then validate.

# 1. get a task to attach the file to (skip if you already have a task_id)
curl -X POST https://api.autumn.ai/tasks/draft \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lead enrichment"}'
# -> {"task_id":"ab12..."}

# 2. presign
curl -X POST https://api.autumn.ai/upload-url \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"ab12...","filename":"leads.csv"}'
# -> {"upload_url":"https://...","filename":"leads.csv"}

# 3. PUT the bytes to upload_url with NO Autumn auth headers, then validate
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/octet-stream" --data-binary @leads.csv

curl -X POST https://api.autumn.ai/validate-upload \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id":"ab12...","filename":"leads.csv"}'

Send the PUT to upload_url without X-API-Key or Authorization. The presigned URL carries its own signature and an extra auth header will be rejected.

/validate-upload converts a CSV to task-local JSONL and returns the filename to pass as input_files:

{
  "filename": "upload_9f2c1ab3.jsonl",
  "rows": 240,
  "fields": ["name", "email", "company"],
  "renamed": [],
  "delimiter": ",",
  "extra_columns": 0
}

Field	Meaning
`filename`	Pass this in `input_files` when starting or continuing a task.
`rows`	Data rows accepted, excluding the header.
`fields`	Final column names, after de-duplication and blank-header naming.
`renamed`	Columns Autumn had to rename, with the original name for each.
`delimiter`	Detected delimiter. Comma unless the header parses as a single column, in which case `;`, tab, and `\|` are tried.
`extra_columns`	Columns added because some row had more cells than the header. Those cells are kept as `column_N` rather than dropped.

Autumn reserves _row_id for its own row identity. A CSV that already has a _row_id column keeps its values under _row_id_2. Then reference the file when you start the task:

curl -X POST https://api.autumn.ai/task \
  -H "X-API-Key: YOUR_AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Enrich every row with the company domain","input_files":["upload_9f2c1ab3.jsonl"]}'

/upload-url is rate limited per account. Exceeding it returns 429 with a message; retry after a short pause.

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.

Get started

Guides

SDK

Skill

Task API

Core Ideas

One task

Two start modes

One planning flag

Request Fields

Start From A Prompt

Model Tiers

Start From A Task Spec

Outputs

Stream Events

Continue A Task

Read Status And Output

Stop

Attach A CSV Or Text File

Route Map

​Core Ideas

One task

Two start modes

One planning flag

​Request Fields

​Start From A Prompt

​Model Tiers

​Start From A Task Spec

​Outputs

​Stream Events

​Continue A Task

​Read Status And Output

​Stop

​Attach A CSV Or Text File

​Route Map

Core Ideas

Request Fields

Start From A Prompt

Model Tiers

Start From A Task Spec

Outputs

Stream Events

Continue A Task

Read Status And Output

Stop

Attach A CSV Or Text File

Route Map