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",
  "repository": "acme/web-app"
}
'
{
  "task": {
    "id": "<string>",
    "slug": "<string>",
    "title": "<string>",
    "url": "<string>",
    "repositoryUrl": "<string>",
    "baseBranch": "<string>"
  },
  "job": {
    "id": "<string>",
    "status": "PENDING"
  }
}
Create a new task from a command prompt and repository. 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.

​
repository
string
required

Repository in owner/repo format or full GitHub URL.

​
branch
string

Base branch (defaults to repository's default branch).

​
agent
string

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

​
mode
enum<string>
default:code

Run mode: plan (produce a plan) or code (implement directly).

Available options:
plan,
code
​
title
string

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

Response

Task created

​
task
object
required
​
job
object
required