Start from a task spec

Authorizations

X-API-Key

string

header

default:YOUR_AUTUMN_API_KEY

required

Your Autumn API key.

Body

application/json

wait

any

default:false

Accepted for compatibility; starting a task always returns immediately.

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
}

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

string | null

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.

Example:

"ranger"

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

Task accepted. Store task_id.

task_id

string

required

Example:

"8fab6f34"

name

string | null

Example:

"Series A AI security companies"

status

string | null

Legacy; use state and done. plan (idle, or finished), execute (working), accepted (queued), deleted.

Example:

"execute"

phase

enum<string> | null

Legacy; use state and done.

Available options:

plan,

execute

Example:

"execute"

activity

string | null

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.

Example:

"executing"

output_count

integer | null

Example:

10

credits_used

integer | null

created_at

string | null

updated_at

string | null

poll_after_s

integer | null

Seconds to wait before polling status again.

Example:

5

status_url

string | null

Example:

"/task/8fab6f34/state"

task_url

string | null

API resource URL, relative to the API server. Open the chat in the browser at https://platform.autumn.ai/?task={task_id}.

Example:

"/task/8fab6f34"

output_url

string | null

Example:

"/task/8fab6f34/output"

stream_url

string | null

Example:

"/task/8fab6f34/stream"

queue

QueueState · object | null

Present while activity is queued.

Show child attributes

state

string | null

A2A lifecycle state: submitted, working, input-required, completed, canceled or failed.

done

boolean | null

True for input-required, completed, canceled and failed.

stage

string | null

Current stage while the task is active.

message

string | null

Latest public-facing task message.

answer

string | null

Full saved assistant answer for a completed chat task without output rows.

progress

Progress · object | null

Rows saved and optional target count.

Show child attributes

elapsed_s

integer | null

Elapsed seconds in the current or most recent run.

queue_position

integer | null

Place in line for a queued task, or null when not queued.

queued_messages

QueuedMessage · object[] | null

Follow-ups queued behind the current turn.

Show child attributes

queued_count

integer

default:0

Pending queued follow-ups.

outcome

string | null

Normalized completed outcome.

error

Error · object | null

Public failure code and recovery guidance.

Show child attributes

Next · object | null

Suggested next action and API call.

Show child attributes

version

string | null

Changes when public task status changes.

app_url

string | null

Open the task in the Autumn app.

Reference

Endpoints

Start from a task spec

Authorizations

Body

Response