> ## 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.

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](/api-reference/pages/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.


## OpenAPI

````yaml api-reference/openapi.json POST /experimental/tasks/{task_id}/messages
openapi: 3.1.0
info:
  title: Phylo API — V1
  description: Public API for Phylo, the biomedical AI agent platform.
  version: 0.1.0
servers:
  - url: https://api.phylo.bio/v1
    description: >-
      Self-serve platform. Enterprise customers should contact the Phylo team to
      get their API base URL. Learn more at https://phylo.bio/enterprise.
security: []
paths:
  /experimental/tasks/{task_id}/messages:
    post:
      tags:
        - messages
      summary: Send a message
      description: Send a message to the agent and get its reply.
      operationId: send_message_experimental_tasks__task_id__messages_post
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            title: Task Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
            examples:
              string:
                summary: Plain text content
                value:
                  content: >-
                    Please re-check variant rs80357065 against the latest
                    ClinVar submission.
              with_file_ids:
                summary: Attach project files with typed content blocks
                value:
                  content:
                    - type: text
                      text: Compare this VCF against the baseline panel.
                  file_ids:
                    - file_014Cj9dpG90jsSrTLXhguYoq
              with_skill:
                summary: Run a Skill on this message
                value:
                  content: Summarize the findings for a clinical audience.
                  skill: literature-deep-review
      responses:
        '200':
          description: >-
            Message sent. Always includes `user_message`; includes
            `assistant_message` once the agent has replied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResult'
              example:
                type: message_result
                user_message:
                  type: message
                  id: msg_a4f9b5cc30d8
                  task_id: tsk_017ilCeuDpMWTSH9Ah1syUGJ
                  role: user
                  platform: api
                assistant_message:
                  id: msg_1a0ef0fa8e26
                  type: message
                  task_id: tsk_017ilCeuDpMWTSH9Ah1syUGJ
                  created_at: '2026-08-12T21:21:08.735000Z'
                  role: assistant
                  status: completed
                  completed_at: '2026-08-12T21:31:37.204000Z'
                  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.
                  platform: api
                  input:
                    user_message_id: msg_a4f9b5cc30d8
                    file_ids: []
      security:
        - bearerAuth: []
components:
  schemas:
    SendMessageRequest:
      properties:
        content:
          anyOf:
            - type: string
            - items:
                additionalProperties: true
                type: object
              type: array
          title: Content
        file_ids:
          items:
            type: string
          type: array
          title: File Ids
        skill:
          anyOf:
            - type: string
            - type: 'null'
          title: Skill
          description: >-
            Skill to run, given as an id or name from `GET /skills`. Your
            `content` is the skill's input.
      additionalProperties: false
      type: object
      required:
        - content
      title: SendMessageRequest
      description: |-
        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`.
    SendMessageResult:
      properties:
        type:
          type: string
          const: message_result
          title: Type
          default: message_result
        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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Requires an API key. See the Authentication guide.

````