--- title: "Start a task" method: POST path: "/task" tags: ["Tasks"] --- # Start a task `POST /task` ## Request - Base URL: `https://api.autumn.ai` - URL: `https://api.autumn.ai/task` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer 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). ## Request body - PromptRequest - `wait` boolean: Accepted for compatibility; starting a task always returns immediately. - `task_id` string, nullable: Continue this task instead of creating one. - `name` string, nullable: Display name. Derived from the prompt when omitted. Applies only when the task is created; ignored on an existing task_id. - `clarify` boolean: Allow one blocking planning question before work starts. Default false: plan and execute without asking. - `input_files` string[], nullable: Task-local filenames returned by POST /validate-upload. - `output` object, nullable: 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. - `input_schema` object, nullable: Column types of input_rows. Applies only when the task is created; ignored on an existing task_id. - `input_rows` object[], nullable: Rows to enrich, one object per row. Applies only when the task is created; ignored on an existing task_id. - `rules` object, nullable: 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. - `count` integer, nullable: Target row count. Applies only when the task is created; ignored on an existing task_id. - `target_count` integer, nullable: Alternative to count. Applies only when the task is created; ignored on an existing task_id. - `version` string, nullable: 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. - `source_data` object, nullable: Caller metadata stored on the task and returned with it. - `prompt` string, nullable: Natural-language task for Autumn. One of prompt or message is required. - `message` string, nullable: Alias of prompt. ## Response `200` Task accepted. Store task_id. - Task - `task_id` string, required - `name` string, nullable - `status` string, nullable: Legacy; use state and done. `plan` (idle, or finished), `execute` (working), `accepted` (queued), `deleted`. - `phase` 'plan' | 'execute', nullable: Legacy; use state and done. - `activity` string, nullable: 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`. - `output_count` integer, nullable - `credits_used` integer, nullable - `created_at` string, nullable - `updated_at` string, nullable - `poll_after_s` integer, nullable: Seconds to wait before polling status again. - `status_url` string, nullable - `task_url` string, nullable: API resource URL, relative to the API server. Open the chat in the browser at https://platform.autumn.ai/?task={task_id}. - `output_url` string, nullable - `stream_url` string, nullable - `queue` QueueState - `position` integer, required: Place in line, 1 is next. - `eta_s` integer, required: Estimated seconds until the run starts. - `state` string, nullable: A2A lifecycle state: submitted, working, input-required, completed, canceled or failed. - `done` boolean, nullable: True for input-required, completed, canceled and failed. - `stage` string, nullable: Current stage while the task is active. - `message` string, nullable: Latest public-facing task message. - `answer` string, nullable: Full saved assistant answer for a completed chat task without output rows. - `progress` object, nullable: Rows saved and optional target count. - `elapsed_s` integer, nullable: Elapsed seconds in the current or most recent run. - `queue_position` integer, nullable: Place in line for a queued task, or null when not queued. - `queued_messages` QueuedMessage[], nullable: Follow-ups queued behind the current turn. - `id` string, required - `text` string, nullable - `state` string, nullable: queued, sending, sent or dropped. - `error` string, nullable - `queued_count` integer: Pending queued follow-ups. - `outcome` string, nullable: Normalized completed outcome. - `error` object, nullable: Public failure code and recovery guidance. - `next` object, nullable: Suggested next action and API call. - `version` string, nullable: Changes when public task status changes. - `app_url` string, nullable: Open the task in the Autumn app. ## Other responses - `202`: Queued. The task picks the message up when the current turn ends; the body carries status `accepted`. - `400`: `invalid_request`: The request is invalid. Fix the field in `param` (see `detail`), or read `message`. - `401`: `unauthorized`: Missing or invalid credentials. Send your full API key as `X-API-Key: ` or `Authorization: Bearer `. - `402`: `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. - `404`: `task_not_found`: No task with that task_id. Check the id, or list tasks with GET /task. - `409`: `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. - `422`: `invalid_request`: a field failed validation. `param` names it; `detail` is the validator output. - `500`: `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. - `502`: `bad_gateway`: An upstream service failed. Send the request again shortly. - `503`: `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. --- [API](https://skmtc.dev/autumn-ai/apis/autumn-task-api.md) - [All operations](https://skmtc.dev/autumn-ai/apis/autumn-task-api/llms.txt) - [OpenAPI document](https://skmtc.dev/autumn-ai/apis/autumn-task-api/revisions/78fb43699783?raw)