Send a message
Send a message to the agent and get its reply.
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 passproject_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.
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 passproject_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
Requires an API key. See the Authentication guide.
Body
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).
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 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.
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
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.
