> ## 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. Hosted MCP: https://api.autumn.ai/mcp. Schemas: https://api.autumn.ai/openapi.json. Every docs page is Markdown at its URL plus `.md`. # Start a task > Start a task from a prompt. Returns at once: store task_id, then stream or poll. Pass task_id to send the prompt to an existing task (202 while it queues). ## OpenAPI ````yaml https://api.autumn.ai/openapi.json post /task openapi: 3.1.0 info: title: Autumn Task API description: >- Durable research tasks run by a sandboxed agent. Auth on every request: `X-API-Key: ` or `Authorization: Bearer `. JSON over HTTP; `/stream` routes are server-sent events. Errors share one body: branch on `error`, retry when `retryable` is true. termsOfService: https://www.autumn.ai/terms contact: name: Autumn url: https://www.autumn.ai/ version: 1.0.0 x-llms-txt: https://api.autumn.ai/llms.txt servers: - url: https://api.autumn.ai security: - ApiKeyHeader: [] - BearerApiKey: [] tags: - name: Tasks description: Start, continue, execute, stop and read tasks. - name: Outputs description: Rows a task produced. - name: Credits description: Account balance. - name: Uploads description: Attach a CSV or text file to a task. - name: Team description: Read team usage and manage team membership. externalDocs: description: Guide and cookbook url: https://www.autumn.ai/docs paths: /task: post: tags: - Tasks summary: Start a task description: >- Start a task from a prompt. Returns at once: store task_id, then stream or poll. Pass task_id to send the prompt to an existing task (202 while it queues). operationId: taskStart requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromptRequest' responses: '200': description: Task accepted. Store task_id. content: application/json: schema: $ref: '#/components/schemas/Task' '202': description: >- Queued. The task picks the message up when the current turn ends; the body carries status `accepted`. content: application/json: schema: $ref: '#/components/schemas/Task' '400': description: >- `invalid_request`: The request is invalid. Fix the field in `param` (see `detail`), or read `message`. content: application/json: examples: invalid_request: summary: invalid_request value: error: invalid_request message: >- The request is invalid. Fix the field in `param` (see `detail`), or read `message`. retryable: false request_id: req_3f9c2a1b0d4e5f6a7b8c schema: $ref: '#/components/schemas/ErrorResponse' '401': description: >- `unauthorized`: Missing or invalid credentials. Send your full API key as `X-API-Key: ` or `Authorization: Bearer `. headers: WWW-Authenticate: description: Bearer realm="autumn" schema: type: string content: application/json: examples: unauthorized: summary: unauthorized value: error: unauthorized message: >- Missing or invalid credentials. Send your full API key as `X-API-Key: ` or `Authorization: Bearer `. retryable: false request_id: req_3f9c2a1b0d4e5f6a7b8c schema: $ref: '#/components/schemas/ErrorResponse' '402': description: >- `out_of_credits`: Out of credits. Add credits at https://platform.autumn.ai (Settings > Billing), then send the request again. Retrying without credits fails the same way. content: application/json: examples: out_of_credits: summary: out_of_credits value: error: out_of_credits message: >- Out of credits. Add credits at https://platform.autumn.ai (Settings > Billing), then send the request again. Retrying without credits fails the same way. retryable: false request_id: req_3f9c2a1b0d4e5f6a7b8c resolve: https://platform.autumn.ai schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- `task_not_found`: No task with that task_id. Check the id, or list tasks with GET /task. content: application/json: examples: task_not_found: summary: task_not_found value: error: task_not_found message: >- No task with that task_id. Check the id, or list tasks with GET /task. retryable: false request_id: req_3f9c2a1b0d4e5f6a7b8c schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- `task_executing`: A turn is running on this task. Poll GET /task/{task_id}/state until `active` is false, then send the request again. Stop it (POST /task/{task_id}/stop) only to abandon the turn. | `task_in_cron_mode`: This task runs on a schedule and does not take messages. Switch it to chat mode in the platform, or start a new task. | `task_exists`: A task with that task_id already exists. Continue it with POST /task/{task_id}/continue, or omit task_id to create a new one. content: application/json: examples: task_executing: summary: task_executing value: error: task_executing message: >- A turn is running on this task. Poll GET /task/{task_id}/state until `active` is false, then send the request again. Stop it (POST /task/{task_id}/stop) only to abandon the turn. retryable: true request_id: req_3f9c2a1b0d4e5f6a7b8c task_in_cron_mode: summary: task_in_cron_mode value: error: task_in_cron_mode message: >- This task runs on a schedule and does not take messages. Switch it to chat mode in the platform, or start a new task. retryable: false request_id: req_3f9c2a1b0d4e5f6a7b8c task_exists: summary: task_exists value: error: task_exists message: >- A task with that task_id already exists. Continue it with POST /task/{task_id}/continue, or omit task_id to create a new one. retryable: false request_id: req_3f9c2a1b0d4e5f6a7b8c schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- `invalid_request`: a field failed validation. `param` names it; `detail` is the validator output. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: invalid_request message: 'prompt: Field required' retryable: false param: prompt detail: - type: missing loc: - body - prompt msg: Field required request_id: req_3f9c2a1b0d4e5f6a7b8c '500': description: >- `internal_error`: Something went wrong on our end. If the body carries task_id, that task exists: continue it instead of starting another. Otherwise send the request again. content: application/json: examples: internal_error: summary: internal_error value: error: internal_error message: >- Something went wrong on our end. If the body carries task_id, that task exists: continue it instead of starting another. Otherwise send the request again. retryable: true request_id: req_3f9c2a1b0d4e5f6a7b8c schema: $ref: '#/components/schemas/ErrorResponse' '502': description: >- `bad_gateway`: An upstream service failed. Send the request again shortly. content: application/json: examples: bad_gateway: summary: bad_gateway value: error: bad_gateway message: >- An upstream service failed. Send the request again shortly. retryable: true request_id: req_3f9c2a1b0d4e5f6a7b8c schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- `auth_unavailable`: Key verification is temporarily unavailable. Wait `retry_after` seconds, then send the request again. | `service_unavailable`: Autumn is temporarily unavailable. Wait `retry_after` seconds, then send the request again. | `at_capacity`: Autumn is at capacity. Wait `retry_after` seconds, then send the request again. headers: Retry-After: description: Seconds to wait before the next request. schema: type: integer content: application/json: examples: auth_unavailable: summary: auth_unavailable value: error: auth_unavailable message: >- Key verification is temporarily unavailable. Wait `retry_after` seconds, then send the request again. retryable: true request_id: req_3f9c2a1b0d4e5f6a7b8c retry_after: 5 service_unavailable: summary: service_unavailable value: error: service_unavailable message: >- Autumn is temporarily unavailable. Wait `retry_after` seconds, then send the request again. retryable: true request_id: req_3f9c2a1b0d4e5f6a7b8c retry_after: 5 at_capacity: summary: at_capacity value: error: at_capacity message: >- Autumn is at capacity. Wait `retry_after` seconds, then send the request again. retryable: true request_id: req_3f9c2a1b0d4e5f6a7b8c retry_after: 5 schema: $ref: '#/components/schemas/ErrorResponse' security: - ApiKeyHeader: [] - BearerApiKey: [] components: schemas: PromptRequest: properties: wait: title: Wait description: >- Accepted for compatibility; starting a task always returns immediately. default: false task_id: anyOf: - type: string - type: 'null' title: Task Id description: Continue this task instead of creating one. name: anyOf: - type: string - type: 'null' title: Name description: >- Display name. Derived from the prompt when omitted. Applies only when the task is created; ignored on an existing task_id. clarify: type: boolean title: Clarify description: >- Allow one blocking planning question before work starts. Default false: plan and execute without asking. default: false input_files: anyOf: - items: type: string type: array - type: 'null' title: Input Files description: Task-local filenames returned by POST /validate-upload. output: anyOf: - additionalProperties: true type: object - type: 'null' title: Output description: >- The output artifact to collect: id, kind, path, name; for research also schema, schema_order, target_count. Applies only when the task is created; ignored on an existing task_id. examples: - id: ai-security-companies kind: research path: outputs/ai-security-companies.jsonl schema: company_name: string funding_stage: string source_urls: array[string] website: string schema_order: - company_name - website - funding_stage - source_urls target_count: 10 input_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Input Schema description: >- Column types of input_rows. Applies only when the task is created; ignored on an existing task_id. examples: - company_name: string funding_stage: string website: string input_rows: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Input Rows description: >- Rows to enrich, one object per row. Applies only when the task is created; ignored on an existing task_id. examples: - - company_name: Acme Security website: acme.security rules: anyOf: - additionalProperties: true type: object - type: 'null' title: Rules description: >- Each value is a rule in plain language; the key names it. Applies only when the task is created; ignored on an existing task_id. examples: - us_only: Only include companies headquartered in the United States. count: anyOf: - type: integer minimum: 1 - type: 'null' title: Count description: >- Target row count. Applies only when the task is created; ignored on an existing task_id. examples: - 10 target_count: anyOf: - type: integer minimum: 1 - type: 'null' title: Target Count description: >- Alternative to count. Applies only when the task is created; ignored on an existing task_id. examples: - 10 version: anyOf: - type: string - type: 'null' title: Version description: >- Model tier. `ranger` (default): most capable. `scout`: faster. `wren`: cheapest, admin plans only. Fixed for the life of the task. Admin-plan keys may also pin a build with `ranger@v-`, a variant name, or a version id. examples: - ranger source_data: anyOf: - additionalProperties: true type: object - type: 'null' title: Source Data description: Caller metadata stored on the task and returned with it. prompt: anyOf: - type: string - type: 'null' title: Prompt description: >- Natural-language task for Autumn. One of prompt or message is required. examples: - >- Find 10 Series A AI security companies and return name, website, funding stage, and source URLs. message: anyOf: - type: string - type: 'null' title: Message description: Alias of prompt. additionalProperties: true type: object title: PromptRequest examples: - prompt: >- Find 10 Series A AI security companies and return name, website, funding stage, and source URLs. Task: properties: task_id: type: string title: Task Id examples: - 8fab6f34 name: anyOf: - type: string - type: 'null' title: Name examples: - Series A AI security companies status: anyOf: - type: string - type: 'null' title: Status description: >- Legacy; use state and done. `plan` (idle, or finished), `execute` (working), `accepted` (queued), `deleted`. examples: - execute phase: anyOf: - type: string enum: - plan - execute - type: 'null' title: Phase description: Legacy; use state and done. examples: - execute activity: anyOf: - type: string - type: 'null' title: Activity description: >- Legacy; use state and done. idle, queued, planning, executing or thinking. `queued` is waiting for a free slot and starts on its own. Finished is `idle`. examples: - executing output_count: anyOf: - type: integer - type: 'null' title: Output Count examples: - 10 credits_used: anyOf: - type: integer - type: 'null' title: Credits Used created_at: anyOf: - type: string - type: 'null' title: Created At updated_at: anyOf: - type: string - type: 'null' title: Updated At poll_after_s: anyOf: - type: integer - type: 'null' title: Poll After S description: Seconds to wait before polling status again. examples: - 5 status_url: anyOf: - type: string - type: 'null' title: Status Url examples: - /task/8fab6f34/state task_url: anyOf: - type: string - type: 'null' title: Task Url description: >- API resource URL, relative to the API server. Open the chat in the browser at https://platform.autumn.ai/?task={task_id}. examples: - /task/8fab6f34 output_url: anyOf: - type: string - type: 'null' title: Output Url examples: - /task/8fab6f34/output stream_url: anyOf: - type: string - type: 'null' title: Stream Url examples: - /task/8fab6f34/stream queue: anyOf: - $ref: '#/components/schemas/QueueState' - type: 'null' description: Present while `activity` is `queued`. state: anyOf: - type: string - type: 'null' title: State description: >- A2A lifecycle state: submitted, working, input-required, completed, canceled or failed. done: anyOf: - type: boolean - type: 'null' title: Done description: True for input-required, completed, canceled and failed. stage: anyOf: - type: string - type: 'null' title: Stage description: Current stage while the task is active. message: anyOf: - type: string - type: 'null' title: Message description: Latest public-facing task message. answer: anyOf: - type: string - type: 'null' title: Answer description: >- Full saved assistant answer for a completed chat task without output rows. progress: anyOf: - additionalProperties: anyOf: - type: integer - type: 'null' type: object - type: 'null' title: Progress description: Rows saved and optional target count. elapsed_s: anyOf: - type: integer - type: 'null' title: Elapsed S description: Elapsed seconds in the current or most recent run. queue_position: anyOf: - type: integer - type: 'null' title: Queue Position description: Place in line for a queued task, or null when not queued. queued_messages: anyOf: - items: $ref: '#/components/schemas/QueuedMessage' type: array - type: 'null' title: Queued Messages description: Follow-ups queued behind the current turn. queued_count: type: integer title: Queued Count description: Pending queued follow-ups. default: 0 outcome: anyOf: - type: string - type: 'null' title: Outcome description: Normalized completed outcome. error: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Error description: Public failure code and recovery guidance. next: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Next description: Suggested next action and API call. version: anyOf: - type: string - type: 'null' title: Version description: Changes when public task status changes. app_url: anyOf: - type: string - type: 'null' title: App Url description: Open the task in the Autumn app. additionalProperties: true type: object required: - task_id title: Task ErrorResponse: properties: error: type: string title: Error description: Stable snake_case code. Branch on this field. examples: - out_of_credits message: type: string title: Message description: What went wrong and what to do next. retryable: type: boolean title: Retryable description: >- True: the same request can succeed later. False: change the request, key, balance or id first. request_id: type: string title: Request Id description: Also the X-Request-ID header. A client-sent X-Request-ID is echoed. examples: - req_3f9c2a1b0d4e5f6a7b8c retry_after: anyOf: - type: integer - type: 'null' title: Retry After description: Seconds to wait. Mirrors the Retry-After header. On 429. resolve: anyOf: - type: string - type: 'null' title: Resolve description: Where to fix the cause. On 402. param: anyOf: - type: string - type: 'null' title: Param description: The field that failed validation. On 422. detail: anyOf: - {} - type: 'null' title: Detail description: Full validator output. On 422. task_id: anyOf: - type: string - type: 'null' title: Task Id description: The task the error refers to. task_created: anyOf: - type: boolean - type: 'null' title: Task Created description: False when task creation was refused, so no task exists. additionalProperties: true type: object required: - error - message - retryable - request_id title: ErrorResponse QueueState: properties: position: type: integer title: Position description: Place in line, 1 is next. examples: - 3 eta_s: type: integer title: Eta S description: Estimated seconds until the run starts. examples: - 240 additionalProperties: true type: object required: - position - eta_s title: QueueState QueuedMessage: properties: id: type: string title: Id text: anyOf: - type: string - type: 'null' title: Text state: anyOf: - type: string - type: 'null' title: State description: queued, sending, sent or dropped. error: anyOf: - type: string - type: 'null' title: Error additionalProperties: true type: object required: - id title: QueuedMessage securitySchemes: ApiKeyHeader: type: apiKey in: header name: X-API-Key description: Your Autumn API key. x-default: YOUR_AUTUMN_API_KEY BearerApiKey: type: http scheme: bearer bearerFormat: Autumn API key description: 'The same key as `Authorization: Bearer `.' x-default: YOUR_AUTUMN_API_KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.