Start from a task spec

curl --request POST \ --url https://api.autumn.ai/task/start \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data ' { "task": { "brief": "Find 10 Series A AI security companies in the US.", "output": { "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 } } } '

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.

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.

outputs

Outputs · object[] | null

Alternative to output. Only the first entry is used.

Maximum array length: 1

input_schema

Input Schema · object | null

Column types of input_rows.

input_rows

Input Rows · object[] | null

Rows to enrich, one object per row.

rules

Rules · object | null

Task rules the agent must follow.

count

integer | null

Target row count.

Required range: x >= 1

target_count

integer | null

Alternative to count.

Required range: x >= 1

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

Task accepted. Store task_id.

task_id

string

required

Example:

"8fab6f34"

name

string | null

Example:

"Series A AI security companies"

status

string | null

plan (idle, or finished), execute (working), accepted (queued), deleted.

Example:

"execute"

phase

enum<string> | null

Available options:

plan,

execute

Example:

"execute"

activity

string | null

idle, planning, executing or thinking. 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

Example:

"/task/8fab6f34"

output_url

string | null

Example:

"/task/8fab6f34/output"

stream_url

string | null

Example:

"/task/8fab6f34/stream"

Reference

Endpoints

Start from a task spec

Authorizations

Body

Response