Skip to main content
POST
You get the reply so far if the agent is still working. Provide exactly one of task_id (continue an existing Task) or project_id (start a new Task in that Project). Attach files with file_ids. Follow a long reply with GET /messages/{id}/chunk or .../stream.

Choosing a model tier

When this call creates the Task for you (you pass project_id, not task_id), set model to choose the agent’s model tier:
  • standard — the default balance of speed and capability.
  • fast — lower latency on a lighter model.
  • max — the highest-capability model.
Omit it to use the account default; an unknown value returns 422. The tier is fixed when the Task is created, so it is ignored when you continue an existing Task (task_id). (POST /tasks does not take a tier — set it on the first message instead.)

Running a skill

When this call creates the Task (you pass project_id), set skill to a skill id or name from List skills to run that skill on your message. Your content is still the input. Unknown skill → 404; ignored when you continue an existing Task (task_id).

Attaching files

file_ids must reference files already finalized in the Task’s project (see the upload flow). A file id that can’t be read — wrong id, expired, or never finalized — is skipped: the message still sends, just without that attachment. Check the reply if an input looks like it was ignored.

Authorizations

Authorization
string
header
required

Requires an API key. See the Authentication guide.

Body

application/json

content may be a string (sugar) or list of content parts. Exactly one of task_id / project_id must be present (validated in the handler, not Pydantic, to keep the error envelope shape).

content
required
task_id
string | null
project_id
string | null
file_ids
string[]
metadata
Metadata · object
stream
boolean
default:false
background
boolean
default:false
plan_mode
boolean
default:false
auto_mode
boolean
default:false
session_name
string | null

Human-readable name for the auto-created task. When set, it is used verbatim as the task title and bypasses the automatic naming from the first message. When omitted, the title is auto-generated from the first message. Ignored when task_id is provided. Rejected with 422 if longer than 200 characters on a new-task send.

model
string | null

Model tier for the auto-created task: 'standard', 'fast', or 'max' (Max mode — highest-capability model). Defaults to 'standard' when omitted; an unknown tier is rejected with 422 on a new-task send. Ignored when task_id is provided.

skill
string | null

Explicitly run a Skill on this task. Pass a skill id or name from GET /skills. The Skill is attached to your message; your content is still the input (the skill's example prompt is not used). Rejected with 404 if the skill is not found. Ignored when task_id is provided.

Response

200 - application/json

Message sent. Response always contains user_message; contains assistant_message once Biomni produces output; contains task only when this call auto-created the task.

Send-message envelope: the task plus the user turn and the agent reply.

The sub-objects are left untyped because their shape varies with the send mode (sync / streaming / background); raw appears only as a fallback when nothing richer could be assembled.

task
Task · object | null
user_message
User Message · object | null
assistant_message
Assistant Message · object | null
raw
Raw · object | null