Start from a task spec and stream

Authorizations

X-API-Key

string

header

default:YOUR_AUTUMN_API_KEY

required

Your Autumn API key.

Body

application/json

task_id

string | null

Continue this task instead of creating one.

name

string | null

Display name. Derived from the prompt when omitted. Applies only when the task is created; ignored on an existing task_id.

clarify

boolean

default:false

Allow one blocking planning question before work starts. Default false: plan and execute without asking.

input_files

string[] | null

Task-local filenames returned by POST /validate-upload.

output

Output · object | null

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.

Example:

{
  "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
}

outputs

Outputs · object[] | null

Alternative to output. Only the first entry is used. Applies only when the task is created; ignored on an existing task_id.

Maximum array length: 1

Example:

[
  {
    "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

Input Schema · object | null

Column types of input_rows. Applies only when the task is created; ignored on an existing task_id.

Example:

{
  "company_name": "string",
  "funding_stage": "string",
  "website": "string"
}

input_rows

Input Rows · object[] | null

Rows to enrich, one object per row. Applies only when the task is created; ignored on an existing task_id.

Example:

[
  {
    "company_name": "Acme Security",
    "website": "acme.security"
  }
]

rules

Rules · object | null

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.

Example:

{
  "us_only": "Only include companies headquartered in the United States."
}

count

integer | null

Target row count. Applies only when the task is created; ignored on an existing task_id.

Required range: x >= 1

Example:

10

target_count

integer | null

Alternative to count. Applies only when the task is created; ignored on an existing task_id.

Required range: x >= 1

Example:

10

version

enum<string> | null

Model tier. scout (default): faster. ranger: most capable. Fixed for the life of the task.

Available options:

ranger,

scout

Example:

"scout"

source_data

Source Data · object | null

Caller metadata stored on the task and returned with it.

task

Task · object | null

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 | null

Appended to the brief, or used as the brief when task is omitted. One of task, prompt or message is required.

message

string | null

Alias of prompt.

Response

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

The response is of type string.

Reference

Endpoints

Start from a task spec and stream

Authorizations

Body

Response