AUautumn-ai
Tasks

Start from a task spec

Start from a task.json spec with no planning turn. Without task, same as POST /task.

post/task/start

Request

  • Base URL
    https://api.autumn.ai
  • URL
    https://api.autumn.ai/task/start
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Request body

waitboolean

Accepted for compatibility; starting a task always returns immediately.

task_idstring nullable

Continue this task instead of creating one.

namestring nullable

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

clarifyboolean

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

input_filesstring[] nullable

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

outputobject 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_schemaobject nullable

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

input_rowsobject[] nullable

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

rulesobject 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.

countinteger nullable

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

target_countinteger nullable

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

versionstring 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_dataobject nullable

Caller metadata stored on the task and returned with it.

taskobject nullable

A task.json spec: brief, output, rules, input_schema, input_rows. Top-level fields apply only when task is omitted. skills is ignored.

promptstring nullable

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

messagestring nullable

Alias of prompt.

Example request

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

Response

Task accepted. Store task_id.

task_idstring required
namestring nullable
statusstring nullable

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

phase'plan' | 'execute' nullable

Legacy; use state and done.

activitystring nullable

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.

output_countinteger nullable
credits_usedinteger nullable
created_atstring nullable
updated_atstring nullable
poll_after_sinteger nullable

Seconds to wait before polling status again.

status_urlstring nullable
task_urlstring nullable

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

output_urlstring nullable
stream_urlstring nullable
statestring nullable

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

doneboolean nullable

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

stagestring nullable

Current stage while the task is active.

messagestring nullable

Latest public-facing task message.

answerstring nullable

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

progressobject nullable

Rows saved and optional target count.

elapsed_sinteger nullable

Elapsed seconds in the current or most recent run.

queue_positioninteger nullable

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

queued_countinteger

Pending queued follow-ups.

outcomestring nullable

Normalized completed outcome.

errorobject nullable

Public failure code and recovery guidance.

nextobject nullable

Suggested next action and API call.

versionstring nullable

Changes when public task status changes.

app_urlstring nullable

Open the task in the Autumn app.

Example response

{
  "task_id": "8fab6f34",
  "name": "Series A AI security companies",
  "status": "execute",
  "phase": "execute",
  "activity": "executing",
  "output_count": 10,
  "poll_after_s": 5,
  "status_url": "/task/8fab6f34/state",
  "task_url": "/task/8fab6f34",
  "output_url": "/task/8fab6f34/output",
  "stream_url": "/task/8fab6f34/stream",
  "queue": {
    "position": 3,
    "eta_s": 240
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.