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

# Start a task

> Start a durable sandboxed Autumn task from a natural-language prompt. The response returns before the work is complete; store task_id and stream or poll status.



## OpenAPI

````yaml /openapi.json post /task
openapi: 3.1.0
info:
  title: Autumn Task API
  version: 1.0.0
  description: >-
    Start, stream, continue, execute, return to plan, and read sandboxed Autumn
    tasks. The public API surface is /task.
servers:
  - url: https://api.autumn.ai
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: POST
    x-group: POST
  - name: GET
    x-group: GET
paths:
  /task:
    post:
      tags:
        - POST
      summary: Start from prompt
      description: >-
        Start a durable sandboxed Autumn task from a natural-language prompt.
        The response returns before the work is complete; store task_id and
        stream or poll status.
      operationId: taskStart
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptRequest'
            example:
              prompt: >-
                Find 10 Series A AI security companies and return name, website,
                funding stage, and source URLs.
      responses:
        '200':
          description: Task accepted. Store task_id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/OutOfCredits'
components:
  schemas:
    PromptRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: Natural-language task for Autumn.
          example: Find 10 Series A AI security companies
        output:
          type: object
          nullable: true
          additionalProperties: true
          description: >-
            Optional single output hint. Include id, kind, path, name, and, for
            research outputs, schema, schema_order, and target_count.
        clarify:
          type: boolean
          nullable: true
          description: >-
            If true, the agent may ask one blocking planning question before
            execution. Defaults to false for public API starts.
        input_files:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Optional task-local input filenames or storage paths already
            available to Autumn.
        source_data:
          type: object
          nullable: true
          additionalProperties: true
          description: Optional caller metadata.
        version:
          type: string
          enum:
            - ranger
            - scout
          description: >-
            Model tier for the task. ranger (default) is the most capable model
            with the deepest reasoning; scout is faster on a tuned harness. Set
            at start only and fixed for the life of the task.
          example: scout
      additionalProperties: true
    Task:
      type: object
      properties:
        task_id:
          type: string
          example: 8fab6f34
        name:
          type: string
          nullable: true
          example: Series A AI security companies
        type:
          type: string
          nullable: true
          example: research
        status:
          type: string
          enum:
            - plan
            - execute
            - deleted
          description: >-
            A completed or stopped run reports `plan`; `execute` means the task
            is currently working.
          example: execute
        phase:
          type: string
          enum:
            - plan
            - execute
          nullable: true
          example: execute
        activity:
          type: string
          description: >-
            Fine-grained state: idle, planning, executing, thinking. A finished
            task is `idle`.
          nullable: true
          example: executing
        output_count:
          type: integer
          nullable: true
          example: 10
        poll_after_s:
          type: integer
          description: Suggested seconds to wait before polling status again.
          example: 5
        status_url:
          type: string
          example: /task/8fab6f34
        output_url:
          type: string
          example: /task/8fab6f34/output
        stream_url:
          type: string
          example: /task/8fab6f34/stream
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        detail:
          type: string
      additionalProperties: true
  responses:
    BadRequest:
      description: The request body was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    OutOfCredits:
      description: The account is out of credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Autumn API key
      description: 'Use `Authorization: Bearer YOUR_AUTUMN_API_KEY`.'
      x-default: YOUR_AUTUMN_API_KEY
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternate API-key header. Use the same Autumn API key.
      x-default: YOUR_AUTUMN_API_KEY

````