> ## Documentation Index
> Fetch the complete documentation index at: https://platform.autumn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Task API

> Start, stream, continue, execute, return to plan, and read sandboxed Autumn tasks.

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

```txt theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.autumn.ai
```

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CardGroup cols={3}>
  <Card title="One task" icon="box">
    Store the returned `task_id`. It is the handle for status, streaming, continuation, files, and output.
  </Card>

  <Card title="Two start modes" icon="split">
    Start from a prompt with `/task`, or start from a `task.json`-style spec with `/task/start`.
  </Card>

  <Card title="One planning flag" icon="flag">
    `clarify:false` plans without asking. `clarify:true` allows a blocking planning question.
  </Card>
</CardGroup>

## 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.

<CodeGroup>
  ```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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
    }'
  ```

  ```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "task_id": "8fab6f34",
    "status": "execute",
    "phase": "execute",
    "stream_url": "/task/8fab6f34/stream",
    "output_url": "/task/8fab6f34/output"
  }
  ```
</CodeGroup>

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.                                            |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<CodeGroup>
  ```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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
    }'
  ```

  ```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "task_id": "8fab6f34",
    "status": "execute",
    "phase": "execute",
    "stream_url": "/task/8fab6f34/stream",
    "output_url": "/task/8fab6f34/output"
  }
  ```
</CodeGroup>

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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

<CodeGroup>
  ```bash Status theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS "https://api.autumn.ai/task/8fab6f34" \
    -H "X-API-Key: YOUR_AUTUMN_API_KEY"
  ```

  ```bash Output theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS "https://api.autumn.ai/task/8fab6f34/output?limit=100" \
    -H "X-API-Key: YOUR_AUTUMN_API_KEY"
  ```

  ```bash List theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS "https://api.autumn.ai/task" \
    -H "X-API-Key: YOUR_AUTUMN_API_KEY"
  ```
</CodeGroup>

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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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"}'
```

<Warning>
  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.
</Warning>

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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. |