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

# TypeScript SDK

> The official autumn-sdk package for TypeScript and JavaScript.

The TypeScript SDK is a thin wrapper around the [Task API](/docs/api-routes). `client.run()`
starts a task, polls until it finishes, and returns the output.

## Install

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install autumn-sdk
npm install zod@4   # for schema (structured output)
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export AUTUMN_API_KEY=your_key
```

## Client

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { AutumnClient } from "autumn-sdk";

const client = new AutumnClient();                          // reads AUTUMN_API_KEY
const client2 = new AutumnClient({ apiKey: "...", baseUrl: "https://api.autumn.ai" });
```

## High-level

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const result = await client.run("Find the top story on Hacker News");
console.log(result.output);
```

`client.run(prompt, opts)` returns a `RunHandle` that is both awaitable (resolves to a
`RunResult`) and async-iterable (yields live messages). After iterating, read
`run.result`.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const run = client.run("Find the top story on Hacker News");
for await (const msg of run) console.log(`[${msg.type}] ${msg.summary}`);
console.log(run.result?.output);
```

### RunOptions

| Option                 | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| `clarify`              | Allow one blocking planning question (default `false`).              |
| `schema`               | A Zod v4 schema; `result.output` is validated.                       |
| `outputLimit`          | Max rows to fetch (default `100`).                                   |
| `pollMs` / `timeoutMs` | Poll interval and overall timeout.                                   |
| *(any other key)*      | Forwarded into the task body (`output`, `rules`, `input_rows`, ...). |

### RunResult

`{ taskId, status, task, output, rows }`. `output` is the flattened rows
(`{ field: value }`), or validated objects when `schema` is set. `rows` is the raw rows
including sources and metadata.

Output rows come back as "cell" objects: each field is `{ value, source_id }` plus
metadata like `_sources`. `output` flattens these for you; use `rows` for the provenance.

## Resources

| Method                                          | Route                                               |
| ----------------------------------------------- | --------------------------------------------------- |
| `client.tasks.create(prompt, opts?)`            | `POST /task`                                        |
| `client.tasks.start(task, opts?)`               | `POST /task/start`                                  |
| `client.tasks.get(taskId)`                      | `GET /task/{task_id}`                               |
| `client.tasks.list()`                           | `GET /task`                                         |
| `client.tasks.output(taskId, opts?)`            | `GET /task/{task_id}/output`                        |
| `client.tasks.outputs(taskId)`                  | `GET /task/{task_id}/outputs`                       |
| `client.tasks.continue(taskId, message, body?)` | `POST /task/{task_id}/continue`                     |
| `client.tasks.execute(taskId, body?)`           | `POST /task/{task_id}/execute`                      |
| `client.tasks.stop(taskId)`                     | `POST /task/{task_id}/stop`                         |
| `client.credits()`                              | `GET /credits`                                      |
| `client.workflow()`                             | `GET /task/workflow`                                |
| `client.metaprompt()`                           | `GET /task/metaprompt`                              |
| `client.files.upload(path?, opts?)`             | `/tasks/draft` + `/upload-url` + `/validate-upload` |

## Attach a CSV

`files.upload()` runs the whole three-call upload for you: it creates a task if you do not
pass `taskId`, presigns, PUTs the bytes without your API key attached, and validates.

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { AutumnClient } from "autumn-sdk";

const client = new AutumnClient();

const attached = await client.files.upload("leads.csv");
const result = await client.run("Enrich every row with the company domain", {
  task_id: attached.task_id,
  input_files: [attached.filename],
});
```

`attached` carries the validated shape — `filename`, `rows`, `fields`, `renamed`,
`delimiter`, and `extra_columns`. Pass `{ content, filename }` instead of a path to upload
from memory. Accepts `.csv`, `.txt`, `.md`, `.markdown` up to 10 MB / 10,000 rows.

## Errors

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { OutOfCreditsError, TaskExecutingError, AuthenticationError } from "autumn-sdk";
```

`OutOfCreditsError` → 402, `TaskExecutingError` → 409, `AuthenticationError` → 401,
`TaskNotFoundError` → 404, `RunTimeoutError` when `run()` exceeds its timeout.

## Terminal state

A finished task returns to `status: "plan"` with `activity: "idle"`. Use the exported
`isTerminal(task)` rather than checking `status` directly. `run()` already does.