Skip to main content
POST
Sends to an existing task. Create one with POST /tasks first. If the agent is still working, the response holds the reply so far; the rest arrives on GET /tasks/{task_id}/messages/{id}.

Model tier

model sets the tier for a new task:
  • standard: the default balance of speed and capability
  • fast: lower latency on a lighter model
  • max: the highest-capability model
An unknown value returns 422. The tier is fixed when the task is created, so it is ignored when you pass task_id. POST /tasks does not accept a tier.

Skills

skill runs a skill on your message. Pass an id or name from List skills; your content is the input. An unknown skill returns 404. Ignored when you pass task_id.

Attached files

file_ids must reference files already finalized in the task’s project. A file that cannot be read is skipped: the message still sends, without that attachment.

Authorizations

Authorization
string
header
required

Requires an API key. See the Authentication guide.

Path Parameters

task_id
string
required

Body

application/json

Body for POST /tasks/{task_id}/messages.

content is a string or a list of content blocks. Task-level settings (title, model tier, plan/auto mode) belong to POST /tasks.

content
required
file_ids
string[]
skill
string | null

Skill to run, given as an id or name from GET /skills. Your content is the skill's input.

Response

200 - application/json

Message sent. Always includes user_message; includes assistant_message once the agent has replied.

type
string
default:message_result
Allowed value: "message_result"
task
Task · object | null
user_message
User Message · object | null
assistant_message
Assistant Message · object | null
raw
Raw · object | null