Send message

POST

tasks

{taskIdOrSlug}

messages

Send message

curl --request POST \
  --url https://twill.ai/api/v1/tasks/{taskIdOrSlug}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Use CSS variables for the theme colors instead of inline styles"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({message: 'Use CSS variables for the theme colors instead of inline styles'})
};

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

import requests

url = "https://twill.ai/api/v1/tasks/{taskIdOrSlug}/messages"

payload = { "message": "Use CSS variables for the theme colors instead of inline styles" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "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": "not_found",
    "message": "Task not found"
  }
}

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

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

Continues a cloud task with a new message to request changes or redirect the work. This API interrupts an active run before starting the follow-up. Answer waiting questions in the task chat. Start the message with /plan to have the agent plan first, or /goal <objective> to set a goal it works toward across turns. To implement a proposed plan, send a message starting with /agent, as the app’s Implement button does (/agent Implement the plan I just approved.). files attaches assets, with each file’s content inlined as a data: URL (remote http(s): URLs are not fetched). Omit userIntent to keep where the task runs: its own fork, or the main environment for a task created with "DEV_ENVIRONMENT" (Fork off in the app). Sending userIntent changes that for this and later runs. The legacy values "PLAN", "ASK", and "GOAL" are still accepted but treated as "SWE". Omit agent and reasoningEffort to keep the task’s model and effort. agent can select another full provider/model ID of the task’s existing harness, and reasoningEffort changes its effort. API keys reach cloud tasks only. Local project chats return 404; continue them in the Twill app.

Authorizations

Authorization

string

header

required

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

Path Parameters

taskIdOrSlug

string

required

Body

application/json

message

string

required

Follow-up message or instructions.

Minimum string length: 1

userIntent

enum<string>

Omit to keep where the task runs. SWE moves it to its own fork and DEV_ENVIRONMENT to the main environment, for this and later runs. The legacy values PLAN, ASK, and GOAL are still accepted for backward compatibility and treated as SWE.

Available options:

SWE,

SCHEDULE,

DEV_ENVIRONMENT

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

agent

string

Complete provider/model ID within the task's existing harness.

reasoningEffort

enum<string>

Reasoning effort supported by the selected model.

Available options:

low,

medium,

high,

xhigh,

max,

ultra

Response

Message accepted

job

object

required

Show child attributes

Send message

curl --request POST \
  --url https://twill.ai/api/v1/tasks/{taskIdOrSlug}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "Use CSS variables for the theme colors instead of inline styles"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({message: 'Use CSS variables for the theme colors instead of inline styles'})
};

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

import requests

url = "https://twill.ai/api/v1/tasks/{taskIdOrSlug}/messages"

payload = { "message": "Use CSS variables for the theme colors instead of inline styles" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "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": "not_found",
    "message": "Task not found"
  }
}

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

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

Overview

Endpoints

Desktop internals

Send message

Authorizations

Path Parameters

Body

Response