---
title: "Start from a task spec and stream"
method: POST
path: "/task/start/stream"
tags: ["Tasks"]
---

# Start from a task spec and stream

`POST /task/start/stream`

## Request

- Base URL: `https://api.autumn.ai`
- URL: `https://api.autumn.ai/task/start/stream`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Start from a task spec and stream the turn.

## Request body

- DirectTaskRequest
  - `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-<sha12>`, a variant name, or a version id.
  - `source_data` object, nullable: Caller metadata stored on the task and returned with it.
  - `task` object, nullable: A task.json spec: brief, output, rules, input_schema, input_rows. Top-level fields apply only when task is omitted. skills is ignored.
  - `prompt` string, nullable: Appended to the brief, or used as the brief when task is omitted. One of task, prompt or message is required.
  - `message` string, nullable: Alias of prompt.

## Response `200`

Server-sent events: task, tool, text, error, done. A failure after the stream opens is an error event.

## Other responses

- `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: <key>` or `Authorization: Bearer <key>`.
- `422`: `invalid_request`: a field failed validation. `param` names it; `detail` is the validator output.
- `503`: `auth_unavailable`: Key verification is temporarily unavailable. 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)