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

> Programmatically create and manage Twill tasks via REST API

Use the Twill REST API to create tasks, poll for status, and automate workflows.

For task history/chat timelines, use `GET /tasks/{taskIdOrSlug}/jobs` with cursor pagination (`limit`, `cursor`, `nextCursor`).

<CardGroup cols={1}>
  <Card title="API reference" icon="book" href="/api-reference/create-task">
    Interactive playground + request/response schemas for every endpoint.
  </Card>
</CardGroup>

## Get an API key

API requests use a workspace-scoped API key.

1. Navigate to your workspace settings
2. Go to the **API Keys** section
3. Click **Create API Key**
4. Give your key a descriptive name (e.g., "CI Pipeline", "GitHub Actions")
5. Optionally set an expiration date
6. **Copy the key immediately** - it will only be shown once

## Use the API key

Send it in the `Authorization` header as a Bearer token.

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

## API key security

<Warning>
  Never commit API keys to version control. Use environment variables or a
  secrets manager.
</Warning>

* Rotate keys periodically
* Use separate keys for different environments (dev, staging, prod)
* Revoke keys immediately if compromised