Skip to main content
POST
Start from task spec

Authorizations

Authorization
string
header
default:YOUR_AUTUMN_API_KEY
required

Use Authorization: Bearer YOUR_AUTUMN_API_KEY.

Body

application/json
task
object

task.json-style spec with brief, one optional output, skills, rules, and input files.

brief
string | null

Convenience field for direct starts without nesting task.

prompt
string | null

Optional instruction appended to the task brief, or used as the task brief when task is omitted.

clarify
boolean | null

Only affects starts that plan (a prompt or bare brief). If true, the agent may ask one blocking planning question before work begins; if false (default) it plans autonomously and starts executing. Has no effect when a full task spec is provided: that executes directly.

output
object | null

Optional single output hint. Include id, kind, path, name, and, for research outputs, schema, schema_order, and target_count.

version
enum<string>

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.

Available options:
ranger,
scout
Example:

"scout"

Response

Task accepted from a spec.

task_id
string
Example:

"8fab6f34"

name
string | null
Example:

"Series A AI security companies"

type
string | null
Example:

"research"

status
enum<string>

A completed or stopped run reports plan; execute means the task is currently working.

Available options:
plan,
execute,
deleted
Example:

"execute"

phase
enum<string> | null
Available options:
plan,
execute
Example:

"execute"

activity
string | null

Fine-grained state: idle, planning, executing, thinking. A finished task is idle.

Example:

"executing"

output_count
integer | null
Example:

10

poll_after_s
integer

Suggested seconds to wait before polling status again.

Example:

5

status_url
string
Example:

"/task/8fab6f34"

output_url
string
Example:

"/task/8fab6f34/output"

stream_url
string
Example:

"/task/8fab6f34/stream"