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

# Start a task

> Start a new Task — one conversation with the agent — inside a Project.

The Task shares the Project's file Drive and starts in `idle`, doing nothing until you post the first message with `POST /messages`, which moves it to `running` (→ `completed` | `failed` | `cancelled`). Related: `GET /tasks/{id}` to poll status · `POST /tasks/{id}/cancel` to stop it.


## OpenAPI

````yaml api-reference/openapi.json POST /tasks
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 <your-api-key>`. The adapter
    forwards your key straight to Biomni; it never stores it.


    **Safe retries**: send `Idempotency-Key: <token>` 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:
  /tasks:
    post:
      tags:
        - tasks
      summary: Start a task
      description: Start a new Task — one conversation with the agent — inside a Project.
      operationId: create_task_tasks_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              minimal:
                summary: Minimal — just project_id + title
                value:
                  project_id: proj_a4374b138a
                  title: Quick variant lookup
              with_plan_mode:
                summary: With plan mode
                value:
                  project_id: proj_a4374b138a
                  title: BRCA1 variant clinical report
                  plan_mode: true
      responses:
        '201':
          description: Task created (status starts as `idle`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              example:
                id: sess_d9711ec9b477
                object: task
                created: 1779132780
                status: idle
                title: BRCA1 variant clinical report
                platform: api
      security:
        - bearerAuth: []
components:
  schemas:
    CreateTaskRequest:
      properties:
        project_id:
          type: string
          title: Project Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        plan_mode:
          type: boolean
          title: Plan Mode
          default: false
        auto_mode:
          type: boolean
          title: Auto Mode
          default: false
      type: object
      required:
        - project_id
      title: CreateTaskRequest
    Task:
      properties:
        id:
          type: string
          title: Id
        object:
          type: string
          const: task
          title: Object
          default: task
        created:
          type: integer
          title: Created
        status:
          type: string
          enum:
            - idle
            - running
            - completed
            - cancelled
            - failed
          title: Status
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        platform:
          type: string
          enum:
            - api
            - mcp
            - web
            - desktop
            - mobile
          title: Platform
          default: api
        review_status:
          anyOf:
            - type: string
              enum:
                - running
                - done
                - failed
            - type: 'null'
          title: Review Status
        review_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Review Error
      type: object
      required:
        - id
        - created
        - status
      title: Task
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Requires an API key. See the Authentication guide.

````