> ## Documentation Index
> Fetch the complete documentation index at: https://www.autumn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Autumn AI (autumn.ai) is a people and company intelligence API, a separate company from useautumn.com (billing software); no billing-product routes exist here.
> Base URL https://api.autumn.ai. Auth on every request: `X-API-Key: <key>` or `Authorization: Bearer <key>`. Plain HTTP + JSON. Schemas: https://www.autumn.ai/docs/openapi.json. Every docs page is Markdown at its URL plus `.md`.

# The task model

> Autumn exposes one primitive: a task. Everything else is a way to start, watch, or read one.

A **task** is a goal you hand to Autumn. It gets its own sandbox and agent, plans an
approach, works the web, and writes output rows. It keeps running in the cloud after your
request returns.

<Steps>
  <Step title="You send a prompt or task spec">
    A goal in plain language, or a structured spec carrying a schema, rules, and input rows.
  </Step>

  <Step title="Autumn writes a plan">
    The agent turns the goal into `task.json` — the approach it intends to take, before it spends anything.
  </Step>

  <Step title="A sandbox and agent start">
    The task gets its own container and workspace, and both persist across turns.
  </Step>

  <Step title="You read events, files, and output rows">
    Progress streams while the task runs; finished rows land in the task's output.
  </Step>
</Steps>

Every task has a durable `task_id`. That id is the handle for everything else: status,
streaming, continuation, files, and output.

<CardGroup cols={3}>
  <Card title="One task" icon="box">
    Store the returned `task_id`. It stays valid after the run finishes.
  </Card>

  <Card title="Two start modes" icon="split">
    Start from a prompt with `/task`, or from a `task.json`-style spec with `/task/start`.
  </Card>

  <Card title="One planning flag" icon="flag">
    `clarify: false` plans without asking. `clarify: true` allows one blocking question.
  </Card>
</CardGroup>

## Two ways to start

| Start mode                            | Use when                                                                                   |
| ------------------------------------- | ------------------------------------------------------------------------------------------ |
| `POST /task` with a `prompt`          | You have natural language and want Autumn to infer the task shape.                         |
| `POST /task/start` with a `task` spec | Your app already knows the shape: known columns, a repeatable job, or a saved `task.json`. |

Choose `/task/start` for enrichment jobs with known inputs, workflows your own app
generates, repeatable research with a fixed output schema, or a task restored from a saved
spec. Choose `/task` when you only have a user request.

Use `GET /task/metaprompt` when another agent or app needs to generate a clean
`task.json`-style spec before calling `/task/start`.

## Planning and `clarify`

`clarify` is the only planning knob. Left at its default of `false`, the agent plans,
infers defaults, and executes without stopping. Set to `true`, it may ask **one** blocking
question before execution.

Use `clarify: true` only when a caller is present and a wrong assumption would cost more
than a short question. [Human in the loop](/docs/guides/human-in-the-loop) covers both modes and
the review-then-continue pattern.

## Turns

A task runs one **turn** at a time. Starting a task is a turn; so is continuing it. A turn
ends with a `done` event, and the task returns to rest. The task itself is not
finished in any final sense. You can continue it later, and it picks up the same plan,
rows, and task-local files.

This is why continuing beats starting over: a new task loses the plan and the rows.

<Note>
  Because a task runs one turn at a time, continuing or executing while a turn is still in
  flight is rejected with `409`, not queued. See [Errors](/docs/api/errors).
</Note>

## Next

<CardGroup cols={2}>
  <Card title="Task lifecycle" icon="activity" href="/docs/concepts/lifecycle">
    The states a task moves through, and how to tell when it is done.
  </Card>

  <Card title="Outputs and sources" icon="table" href="/docs/concepts/outputs">
    What a task produces, and how every value carries its source.
  </Card>
</CardGroup>