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

​
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.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), DEV_ENVIRONMENT (dev environment setup), or RALPH_LOOP (criteria-verified loop with budget).

Available options:
SWE,
PLAN,
ASK,
DEV_ENVIRONMENT,
RALPH_LOOP
​
ralphLoopBudgetUsd
integer

Maximum budget in USD for a Ralph loop task. Required when userIntent is RALPH_LOOP.

​
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