> ## Documentation Index > Fetch the complete documentation index at: https://docs.biomni.phylo.bio/llms.txt > Use this file to discover all available pages before exploring further. # Send a message > Send a message to the agent and get its reply. 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](/api-reference/pages/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. ## OpenAPI ````yaml api-reference/openapi.json POST /messages openapi: 3.1.0 info: title: Biomni Public API — V0 description: >- The public API for **Biomni** — the AI agent platform for clinical genomics (variant annotation, ClinVar lookups, PMID-cited literature, and project file drives). Create projects and Tasks, send messages to the agent, stream its replies, manage files, and check your usage — all from your own code. **Authentication**: send `Authorization: Bearer `. The adapter forwards your key straight to Biomni; it never stores it. **Safe retries**: send `Idempotency-Key: ` on POST endpoints (`/projects`, `/tasks`, `/messages`, `/files/uploads`) so a retried request won't create a duplicate. version: 0.1.0 servers: - url: https://api.phylo.bio/api/v1 security: [] paths: /messages: post: tags: - messages summary: Send a message description: Send a message to the agent and get its reply. operationId: send_message_messages_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendMessageRequest' examples: string_to_task: summary: String sugar → existing task value: task_id: sess_d9711ec9b477 content: >- Please re-check variant rs80357065 against the latest ClinVar submission. autocreate_with_project: summary: project_id only → auto-creates a task value: project_id: proj_a4374b138a content: >- Analyze the 3 BRCA1 variants in patient001_brca1.vcf — current ClinVar status, PARP inhibitor eligibility, conflicts in the literature. with_file_ids: summary: Reference files in the project Drive + typed content blocks value: task_id: sess_d9711ec9b477 content: - type: text text: Compare this VCF against the baseline panel. file_ids: - file_8a2c3b91de metadata: customer_request_id: REQ-2026-0042 responses: '200': description: >- Message sent. Response always contains `user_message`; contains `assistant_message` once Biomni produces output; contains `task` only when this call auto-created the task. content: application/json: schema: $ref: '#/components/schemas/SendMessageResult' examples: existing_task: summary: Sending to an existing task — completed reply value: user_message: id: msg_a4f9b5cc30d8 task_id: sess_d9711ec9b477 role: user platform: api assistant_message: id: msg_1a0ef0fa8e26 object: message task_id: sess_d9711ec9b477 created: 1779132785 role: assistant status: completed completed_at: 1779133414 content: - type: text text: >- Loaded the genetic-variant-annotation skill. For these 3 BRCA1 variants I'll (1) query ClinVar's REST API directly for each rsID to get current assertions, review status, star ratings, and conditions, and (2) cross-reference NCBI's ClinVar records for conflicting submissions and literature PMIDs. - type: tool_use id: toolu_01RkjLRcNtbVHBBwWDDk7gmF name: Skill input: action: load name: genetic-variant-annotation - type: tool_result tool_use_id: toolu_01RkjLRcNtbVHBBwWDDk7gmF content: >- # Skill: genetic-variant-annotation **Category**: genomics_genetics **Description**: Annotate genomic variants in VCF files with functional effects, clinical significance, and pathogenicity predictions. … (truncated) - type: text text: >- Here is the full structured report. Two deliverables are saved: `report_Patient001_BRCA1_variants.md` and `Patient001_BRCA1_variant_report.json`. All three variants are confirmed pathogenic by ClinVar (3-star review); PARP inhibitor eligibility applies for HBOC and ovarian indications. … (truncated; real response has 61 content blocks) metadata: {} platform: api input: user_message_id: msg_a4f9b5cc30d8 file_ids: [] autocreate: summary: >- project_id only → adapter auto-creates the task (response includes `task`) value: task: id: sess_2719df714819 object: task created: 1779131425 status: running title: BRCA1 variant exploration — adapter demo platform: api user_message: id: msg_a4f9b5cc30d8 task_id: sess_2719df714819 role: user platform: api assistant_message: id: msg_running01abcd object: message task_id: sess_2719df714819 created: 1779131500 role: assistant status: streaming content: - type: text text: Looking up ClinVar records for rs80357065… - type: tool_use id: toolu_01ABCD name: execute_python input: code: import requests; … metadata: {} platform: api security: - bearerAuth: [] components: schemas: SendMessageRequest: properties: content: anyOf: - type: string - items: additionalProperties: true type: object type: array title: Content task_id: anyOf: - type: string - type: 'null' title: Task Id project_id: anyOf: - type: string - type: 'null' title: Project Id file_ids: items: type: string type: array title: File Ids metadata: additionalProperties: true type: object title: Metadata stream: type: boolean title: Stream default: false background: type: boolean title: Background default: false plan_mode: type: boolean title: Plan Mode default: false auto_mode: type: boolean title: Auto Mode default: false session_name: anyOf: - type: string - type: 'null' title: Session Name description: >- 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: anyOf: - type: string - type: 'null' title: Model description: >- 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: anyOf: - type: string - type: 'null' title: Skill description: >- 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. type: object required: - content title: SendMessageRequest description: >- `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). SendMessageResult: properties: task: anyOf: - additionalProperties: true type: object - type: 'null' title: Task user_message: anyOf: - additionalProperties: true type: object - type: 'null' title: User Message assistant_message: anyOf: - additionalProperties: true type: object - type: 'null' title: Assistant Message raw: anyOf: - additionalProperties: true type: object - type: 'null' title: Raw type: object title: SendMessageResult description: >- 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. securitySchemes: bearerAuth: type: http scheme: bearer description: Requires an API key. See the Authentication guide. ````