Skip to main content
Use the REST API to create tasks, read status and run history, send follow-ups, or stop work in a cloud workspace. Local project chats are not available through the API; start and continue them in Twill Desktop.

​
Authentication

Create a key in Settings → API Keys for the workspace you want to use. Keys start with twill_ and are shown once. Store yours in TWILL_API_KEY:
A key operates on its cloud workspace’s tasks. Personal workspaces, which hold your local projects, cannot create or use API keys. A key acts as the member who created it and stops working when that member leaves or is removed from the workspace.

​
Create a task

A successful request returns 201 with task (including its id, slug, and url) and the first job. Use the returned task ID or slug with Get task or List task jobs to follow progress.

​
Responses and limits

  • Base URL: https://twill.ai/api/v1.
  • Rate limits: 100 requests per minute and 1,000 per hour per API key. A 429 response includes Retry-After.
  • Errors: a JSON object with error.code, error.message, and optional error.details.
  • Pagination: task and job lists accept limit and cursor. Pass the returned nextCursor to fetch older entries.
Native plan approvals and interactive permission questions are handled in the Twill task chat. There is no current public plan-approval endpoint. Sending a follow-up message is not the same as answering a waiting native permission request.
The CLI provides terminal commands for tasks, automations, session export, and sandbox access. The desktop runner protocol is a separate interface for runner implementations, not ordinary task automation.