Structured output

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 and every row comes back in that shape.

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
  }'

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()

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());

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:

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

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))

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);

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

Send one output. To change it later, continue the task with a message describing the new shape; Autumn updates or replaces the output. Outputs and sources covers how.

Output kinds

kind tells Autumn what sort of artifact it is building: research, person, or company. See Outputs and sources for what each one is for.

Task API

The full task spec, field by field.

Follow-up tasks

Add a column to results you already have.

Get started

Core concepts

Guides

Best practices

Use with agents

Field types

Reading typed rows back

Output kinds

Task API

Follow-up tasks

​Field types

​Reading typed rows back

​Output kinds

​Related

Task API

Follow-up tasks

Field types

Reading typed rows back

Output kinds

Related