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

# API

> Create and manage tasks programmatically with the Twill REST API.

The REST API covers the full task loop: create tasks, poll status, stream history, approve plans, send follow-ups, and cancel runs. Anything you can do from the web app's composer, you can script.

## Authentication

Create a key in workspace **Settings → API Keys** (it's shown once — store it safely; you can set an expiration). Keys are workspace-scoped and start with `twill_`.

```bash theme={"theme":"github-dark"}
curl https://twill.ai/api/v1/tasks \
  -H "Authorization: Bearer $TWILL_API_KEY"
```

## Basics

* **Base URL**: `https://twill.ai/api/v1`
* **Rate limits**: 100 requests/minute, 1000/hour per key
* **Errors**: JSON envelope `{ "error": { "code", "message", "details?" } }`
* **Pagination**: list endpoints take `limit` and `cursor`, and return `nextCursor` while older entries exist

## Quick example

```bash theme={"theme":"github-dark"}
# create a task
curl -X POST https://twill.ai/api/v1/tasks \
  -H "Authorization: Bearer $TWILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "Fix the flaky signup test"}'

# follow its history
curl "https://twill.ai/api/v1/tasks/{taskIdOrSlug}/jobs?limit=20" \
  -H "Authorization: Bearer $TWILL_API_KEY"
```

<Card title="Endpoint reference" icon="book" href="/api-reference/create-task">
  Interactive playground with request/response schemas for every endpoint.
</Card>

<Tip>
  Prefer a terminal? The [CLI](/cli) wraps this API — tasks, automations,
  teleport, and sandbox SSH included.
</Tip>