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

# Structured output

> Declare the exact columns a task should return, and read them back as typed rows.

By default Autumn infers the shape of its output from your prompt. When your app already
knows the columns it wants, declare them with `output.schema` on
[`POST /task/start`](/docs/api-routes#start-from-a-task-spec) and every row comes back in that
shape.

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -sS -X POST "https://api.autumn.ai/task/start" \
    -H "X-API-Key: $AUTUMN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "task": {
        "brief": "Find 20 AI infrastructure startups hiring founding engineers.",
        "output": {
          "id": "ai-infra-startups",
          "kind": "research",
          "path": "outputs/ai-infra-startups.jsonl",
          "target_count": 20,
          "schema": {
            "company": { "type": "str" },
            "domain": { "type": "url" },
            "notes": { "type": "str" },
            "sources": { "type": "list[url]" }
          },
          "schema_order": ["company", "domain", "notes", "sources"]
        }
      },
      "clarify": false
    }'
  ```

  ```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"]}

  task = requests.post(f"{AUTUMN}/task/start", headers=HEADERS, json={
      "task": {
          "brief": "Find 20 AI infrastructure startups hiring founding engineers.",
          "output": {
              "id": "ai-infra-startups",
              "kind": "research",
              "path": "outputs/ai-infra-startups.jsonl",
              "target_count": 20,
              "schema": {
                  "company": {"type": "str"},
                  "domain": {"type": "url"},
                  "notes": {"type": "str"},
                  "sources": {"type": "list[url]"},
              },
              "schema_order": ["company", "domain", "notes", "sources"],
          },
      },
      "clarify": False,
  }).json()
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const task = await fetch("https://api.autumn.ai/task/start", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.AUTUMN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      task: {
        brief: "Find 20 AI infrastructure startups hiring founding engineers.",
        output: {
          id: "ai-infra-startups",
          kind: "research",
          path: "outputs/ai-infra-startups.jsonl",
          target_count: 20,
          schema: {
            company: { type: "str" },
            domain: { type: "url" },
            notes: { type: "str" },
            sources: { type: "list[url]" },
          },
          schema_order: ["company", "domain", "notes", "sources"],
        },
      },
      clarify: false,
    }),
  }).then((r) => r.json());
  ```
</CodeGroup>

## Field types

`schema` is a flat map of column name to type. Supported types:

| Type                          | Meaning                     |
| ----------------------------- | --------------------------- |
| `str`                         | Text.                       |
| `int`                         | Whole number.               |
| `float`                       | Decimal number.             |
| `bool`                        | True or false.              |
| `url`                         | A URL, validated as one.    |
| `list[str]`, `list[url]`, ... | A list of any of the above. |

`schema_order` fixes column order for readback and exports. Keep the schema flat: one row
per entity, one column per fact.

## Reading typed rows back

`GET /task/{task_id}/output` returns rows whose fields are **cells**, not bare values.
Each cell pairs the value with the source it came from:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "rows": [
    {
      "company": { "value": "Acme Infra", "source_id": "s1" },
      "domain": { "value": "https://acme.example", "source_id": "s1" },
      "sources": { "value": ["https://acme.example/careers"], "source_id": "s2" },
      "_sources": { "s1": "https://acme.example", "s2": "https://acme.example/careers" }
    }
  ]
}
```

Flatten the cells when you want plain data, and keep `_sources` when you need to show or
audit provenance:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  def flatten(row):
      return {k: v["value"] for k, v in row.items()
              if not k.startswith("_") and isinstance(v, dict) and "value" in v}

  rows = requests.get(
      f"{AUTUMN}/task/{task['task_id']}/output",
      headers=HEADERS, params={"limit": 100},
  ).json()["rows"]

  for row in rows:
      print(flatten(row))
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const flatten = (row) =>
    Object.fromEntries(
      Object.entries(row)
        .filter(([k, v]) => !k.startsWith("_") && v && typeof v === "object" && "value" in v)
        .map(([k, v]) => [k, v.value]),
    );

  const { rows } = await fetch(`${AUTUMN}/task/${task.task_id}/output?limit=100`, {
    headers: HEADERS,
  }).then((r) => r.json());

  rows.map(flatten);
  ```
</CodeGroup>

Validate the flattened rows against your own types (Pydantic, Zod, or whatever your app
already uses) and drop rows that don't fit.

<Note>
  Keep `output` singular. If the artifact you want changes later, continue the task and
  replan rather than sending a second `output`. [Outputs and sources](/docs/concepts/outputs)
  covers why.
</Note>

## Output kinds

`kind` tells Autumn what sort of artifact it is building: `research`, `person`, or
`company`. See [Outputs and sources](/docs/concepts/outputs) for what each one is for.

## Related

<CardGroup cols={2}>
  <Card title="Task API" icon="terminal" href="/docs/api-routes#start-from-a-task-spec">
    The full task spec, field by field.
  </Card>

  <Card title="Follow-up tasks" icon="repeat" href="/docs/guides/follow-up">
    Add a column to results you already have.
  </Card>
</CardGroup>