Skip to main content
POST
/
tasks
Create task
curl --request POST \
  --url https://twill.ai/api/v1/tasks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "Add a dark mode toggle to the settings page"
}
'
{
  "task": {
    "id": "<string>",
    "slug": "<string>",
    "title": "<string>",
    "url": "<string>",
    "repositoryUrl": "<string>",
    "baseBranch": "<string>"
  },
  "job": {
    "id": "<string>"
  }
}

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.

Create a new task from a command prompt. The agent picks the repository at runtime from the workspace’s connected repos, so no repository or branch needs to be supplied. You can optionally set userIntent to choose the initial run type and attach files so the agent can reference uploaded assets in its first message. The response includes the created task plus the first job that was queued for it.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
command
string
required

Task description or instructions for the agent.

​
agent
string

Provider+model id override (e.g. claude-code/sonnet, codex/gpt-5.4, open-code/openai/gpt-5.4).

​
userIntent
enum<string>
default:SWE

Run type: SWE (implement directly), PLAN (produce a plan), ASK (Q&A mode), or DEV_ENVIRONMENT (dev environment setup).

Available options:
SWE,
PLAN,
ASK,
DEV_ENVIRONMENT
​
title
string

Optional task title (auto-generated if not provided).

​
files
object[]

Optional file attachments provided as UI message file parts.

Response

Task created

​
task
object
required
​
job
object
required