API - Twill

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_.

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

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

Endpoint reference

Interactive playground with request/response schemas for every endpoint.

Prefer a terminal? The CLI wraps this API — tasks, automations, teleport, and sandbox SSH included.