> ## 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: <key>` or `Authorization: Bearer <key>`. Plain HTTP + JSON. Schemas: https://www.autumn.ai/docs/openapi.json. Every docs page is Markdown at its URL plus `.md`.

# Start from a task spec

> Start from a task.json spec with no planning turn. Without task, same as POST /task.



## OpenAPI

````yaml https://api.autumn.ai/openapi.json post /task/start
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: <key>` or `Authorization: Bearer <key>`. 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.
externalDocs:
  description: Guide and cookbook
  url: https://www.autumn.ai/docs
paths:
  /task/start:
    post:
      tags:
        - Tasks
      summary: Start from a task spec
      description: >-
        Start from a task.json spec with no planning turn. Without task, same as
        POST /task.
      operationId: taskStartDirect
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DirectTaskRequest'
        required: true
      responses:
        '200':
          description: Task accepted. Store task_id.
          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:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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
        '401':
          description: >-
            `unauthorized`: Missing or invalid credentials. Send your full API
            key as `X-API-Key: <key>` or `Authorization: Bearer <key>`.
          headers:
            WWW-Authenticate:
              description: Bearer realm="autumn"
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: unauthorized
                  value:
                    error: unauthorized
                    message: >-
                      Missing or invalid credentials. Send your full API key as
                      `X-API-Key: <key>` or `Authorization: Bearer <key>`.
                    retryable: false
                    request_id: req_3f9c2a1b0d4e5f6a7b8c
        '402':
          description: >-
            `out_of_credits`: Out of credits. Add credits at
            https://platform.autumn.ai (Settings > Usage), then send the request
            again. Retrying without credits fails the same way.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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 > Usage), then send the request again. Retrying
                      without credits fails the same way.
                    retryable: false
                    request_id: req_3f9c2a1b0d4e5f6a7b8c
                    resolve: https://platform.autumn.ai
        '404':
          description: >-
            `task_not_found`: No task with that task_id. Check the id, or list
            tasks with GET /task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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
        '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_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:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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_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
        '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:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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
        '502':
          description: >-
            `bad_gateway`: An upstream service failed. Send the request again
            shortly.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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
        '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:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              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
      security:
        - ApiKeyHeader: []
        - BearerApiKey: []
components:
  schemas:
    DirectTaskRequest:
      properties:
        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.
        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.
        outputs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
              maxItems: 1
            - type: 'null'
          title: Outputs
          description: Alternative to output. Only the first entry is used.
        input_schema:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Input Schema
          description: Column types of input_rows.
        input_rows:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Input Rows
          description: Rows to enrich, one object per row.
        rules:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Rules
          description: Task rules the agent must follow.
        count:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Count
          description: Target row count.
        target_count:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Target Count
          description: Alternative to count.
        version:
          anyOf:
            - type: string
              enum:
                - ranger
                - scout
            - type: 'null'
          title: Version
          description: >-
            Model tier. `scout` (default): faster. `ranger`: most capable. Fixed
            for the life of the task.
          examples:
            - scout
        source_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Source Data
          description: Caller metadata stored on the task and returned with it.
        task:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Task
          description: >-
            A task.json spec: brief, output, rules, input_schema, input_rows.
            Top-level fields apply only when task is omitted. skills is ignored.
        prompt:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt
          description: >-
            Appended to the brief, or used as the brief when task is omitted.
            One of task, prompt or message is required.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Alias of prompt.
      additionalProperties: true
      type: object
      title: DirectTaskRequest
      examples:
        - task:
            brief: Find 10 Series A AI security companies in the US.
            output:
              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
    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: >-
            `plan` (idle, or finished), `execute` (working), `accepted`
            (queued), `deleted`.
          examples:
            - execute
        phase:
          anyOf:
            - type: string
              enum:
                - plan
                - execute
            - type: 'null'
          title: Phase
          examples:
            - execute
        activity:
          anyOf:
            - type: string
            - type: 'null'
          title: Activity
          description: idle, planning, executing or thinking. 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
          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
      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
  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 <key>`.'
      x-default: YOUR_AUTUMN_API_KEY

````