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>"
  },
  "job": {
    "id": "<string>",
    "status": "PENDING"
  }
}

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

Send a command describing the work. The response includes the new task and its first job.

Cloud tasks

The agent selects repositories from the workspace’s connected repos. Set agent to a complete provider/model ID or use the workspace’s routing defaults. reasoningEffort selects a supported effort level. Normal tasks use "SWE" and run in their own fork of the workspace environment. Use userIntent: "DEV_ENVIRONMENT" to run in the main environment instead (Fork off in the app), for example to set it up or fix it. For planning, start command with /plan; approve the plan in the task chat, or send a follow-up starting with /agent to implement it.

Attachments and compatibility

Pass attachment content as data: URLs in files. Remote HTTP URLs are not fetched. Legacy userIntent values PLAN, ASK, and GOAL are accepted as SWE; use native commands in command for planning or supported goal tracking.

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 harness, model, and effort config. Start with /plan to have the harness plan first, or /goal (Claude Code and Codex) to track a goal.

Minimum string length: 1

agent

string

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

userIntent

enum<string>

default:SWE

Where the task runs: SWE (default) runs it in its own fork of the workspace environment; DEV_ENVIRONMENT runs it in the main environment (Fork off in the app), so what it installs or configures stays for future tasks. SCHEDULE is used by automations and runs like SWE. The legacy values PLAN, ASK, and GOAL are still accepted for backward compatibility and treated as SWE; start the command with /plan to plan first.

Available options:

SWE,

SCHEDULE,

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

executionTarget

object

API keys are cloud-only. Local project chats are started in Twill Desktop.

Show child attributes

reasoningEffort

enum<string>

Reasoning effort supported by the selected model.

Available options:

low,

medium,

high,

xhigh,

max,

ultra

parentId

string

Optional parent task ID.

Response

Task created

task

object

required

Show child attributes

job

object

required

Show child attributes

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>"
  },
  "job": {
    "id": "<string>",
    "status": "PENDING"
  }
}

{
  "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

Desktop internals

Cloud tasks

Attachments and compatibility

Authorizations

Body

Response

​Cloud tasks

​Attachments and compatibility

Authorizations

Body

Response

Cloud tasks

Attachments and compatibility