Create task

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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({command: 'Add a dark mode toggle to the settings page'})
};

fetch('https://twill.ai/api/v1/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://twill.ai/api/v1/tasks"

payload = { "command": "Add a dark mode toggle to the settings page" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "task": {
    "id": "<string>",
    "slug": "<string>",
    "title": "<string>",
    "url": "<string>",
    "repositoryUrl": "<string>",
    "baseBranch": "<string>"
  },
  "job": {
    "id": "<string>"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {
      "issues": [
        {
          "field": "command",
          "message": "command is required"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Max 100 requests per minute."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Server error"
  }
}

Create a task from a command prompt. No repository or branch is supplied — the agent picks the repo(s) at runtime from the workspace’s connected repos. Optional fields: userIntent sets the initial run type; agent pins a harness as a full <provider>/<model> id (a provider-only value is rejected); files attaches uploaded assets. Otherwise mode, model, and effort come from your routing configs — include a /trigger in command to select one. The response includes the created task plus its first queued job.

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. Include a routing /trigger to select a model, mode, and effort config.

agent

string

Optional explicit harness. Must be a complete provider/model id (e.g. claude-code/sonnet, codex/gpt-5.4, open-code/openai/gpt-5.4); a provider-only value is rejected. Overrides routing for the task.

userIntent

enum<string>

default:SWE

Run type: SWE (implement directly), PLAN (produce a plan), GOAL (work toward a goal, tracked by the harness), ASK (Q&A mode), or DEV_ENVIRONMENT (dev environment setup).

Available options:

SWE,

PLAN,

GOAL,

ASK,

DEV_ENVIRONMENT

title

string

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

files

object[]

Optional file attachments provided as UI message file parts.

Show child attributes

Response

Task created

task

object

required

Show child attributes

job

object

required

Show child attributes

List tasksList the workspace's tasks, newest first.

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"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({command: 'Add a dark mode toggle to the settings page'})
};

fetch('https://twill.ai/api/v1/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://twill.ai/api/v1/tasks"

payload = { "command": "Add a dark mode toggle to the settings page" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "task": {
    "id": "<string>",
    "slug": "<string>",
    "title": "<string>",
    "url": "<string>",
    "repositoryUrl": "<string>",
    "baseBranch": "<string>"
  },
  "job": {
    "id": "<string>"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": {
      "issues": [
        {
          "field": "command",
          "message": "command is required"
        }
      ]
    }
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Max 100 requests per minute."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Server error"
  }
}

Overview

Endpoints

Authorizations

Body

Response