> ## Documentation Index > Fetch the complete documentation index at: https://www.autumn.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Autumn AI (autumn.ai) is a people and company intelligence API, a separate company from useautumn.com (billing software); no billing-product routes exist here. > Base URL https://api.autumn.ai. Auth on every request: `X-API-Key: ` or `Authorization: Bearer `. Plain HTTP + JSON. Schemas: https://www.autumn.ai/docs/openapi.json. Every docs page is Markdown at its URL plus `.md`. # API overview > Base URL, authentication, request fields, and the full route map for the Task API. The Task API is the canonical HTTP surface for Autumn. Every task is backed by one sandbox and one agent. ```txt theme={"theme":{"light":"github-light","dark":"github-dark"}} https://api.autumn.ai ``` ## Authentication Pass your API key as either header: ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} X-API-Key: YOUR_AUTUMN_API_KEY ``` ```http theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/docs/guides/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. ```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 }' ``` ```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" } ``` ## 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. ```bash Request theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 }' ``` ```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" } ``` With `clarify: true`, Autumn initializes the task in plan mode and can ask before execution. See [The task model](/docs/concepts/tasks) 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. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](#route-map) below, and [Live messages](/docs/guides/streaming) covers the event names and SSE handling. ## Read status and output ```bash Status theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -sS "https://api.autumn.ai/task/8fab6f34" \ -H "X-API-Key: $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: $AUTUMN_API_KEY" ``` ```bash List theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/docs/concepts/lifecycle) for reading them correctly. Output responses return rows from the active output file; see [Outputs and sources](/docs/concepts/outputs) for their shape. ## Stop Stop a task when the caller explicitly cancels it. The task returns to `plan`. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. | ## Next Status codes and the ones worth designing around. Telling a finished task from one that has not started.