> ## 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`.

# Human in the loop

> Let the agent ask a clarifying question, or hand control back and forth.

`clarify` is the only planning knob. By default (`clarify: false`) the agent infers
reasonable defaults and executes without asking. Set `clarify: true` when a human is present
and a missing answer would materially change the work.

| Value   | Agent behavior                                                                |
| ------- | ----------------------------------------------------------------------------- |
| `false` | Plan, infer defaults, and execute without asking. The default for automation. |
| `true`  | Allow **one** blocking planning question before execution.                    |

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS -X POST "https://api.autumn.ai/task" \
    -H "X-API-Key: $AUTUMN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"prompt": "Build a list of fintech companies", "clarify": true}'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os, requests

  AUTUMN = "https://api.autumn.ai"
  HEADERS = {"X-API-Key": os.environ["AUTUMN_API_KEY"]}

  # clarify=true: may ask one question, e.g. geography or target count
  task = requests.post(f"{AUTUMN}/task", headers=HEADERS, json={
      "prompt": "Build a list of fintech companies",
      "clarify": True,
  }).json()
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const task = await fetch("https://api.autumn.ai/task", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.AUTUMN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ prompt: "Build a list of fintech companies", clarify: true }),
  }).then((r) => r.json());
  ```
</CodeGroup>

With `clarify: true` the task initializes in plan mode and can stop before execution. Stream
the turn (or poll status) to see the question, answer it with
`POST /task/{task_id}/continue`, then let it execute.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# answer the planning question on the same task
curl -sS -X POST "https://api.autumn.ai/task/$TASK_ID/continue" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "US only, Series A or later, 50 rows"}'
```

## Review, then continue

A common pattern: run the first part, let a human review the rows, then continue the same
task with corrections.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
task_id = requests.post(f"{AUTUMN}/task", headers=HEADERS, json={
    "prompt": "Find Series A fintech companies in the US",
    "clarify": False,
}).json()["task_id"]

# ... wait for the turn to finish, then fetch rows ...
rows = requests.get(f"{AUTUMN}/task/{task_id}/output", headers=HEADERS).json()["rows"]

# ... human reviews rows ...

requests.post(f"{AUTUMN}/task/{task_id}/continue", headers=HEADERS, json={
    "message": "Drop anything past Series A and add the CEO name column",
})
```

Because the `task_id` is durable, you can interleave agent turns and human review as many
times as you need. See [Follow-up tasks](/docs/guides/follow-up).

## Guidance

* For background automation, keep `clarify: false`.
* Use `clarify: true` only when the user is present to answer.
* When continuing after review, restate the current goal as a clear instruction rather than
  passing the user's raw words.
* `POST /task/{task_id}/stop` returns a running task to `plan` if a reviewer needs to
  intervene mid-run.