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

> Create an idle task inside a project, or start it immediately with initial messages.

The task shares the project's files and starts in `idle`. It stays idle until you send the first message with `POST /tasks/{id}/messages`, which moves it to `running`. Read its status with `GET /tasks/{id}` and stop it with `POST /tasks/{id}/cancel`.

`model` picks the tier the agent runs on. It is fixed when the task is created and cannot be changed afterwards, so start a new task to work on a different tier. Omit it to take the default.

Pass `initial_messages` to skip that second call: the messages are delivered to the task in the order you list them and the agent starts on the last one, reading the ones before it as the conversation so far. The task comes back as `running`.


## OpenAPI

````yaml api-reference/openapi.json POST /experimental/tasks
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:
    post:
      tags:
        - tasks
      summary: Start a task
      description: >-
        Create an idle task inside a project, or start it immediately with
        initial messages.
      operationId: create_task_experimental_tasks_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskRequest'
            examples:
              minimal:
                summary: 'Minimal: just project_id + title'
                value:
                  project_id: prj_0126xxQZB9MmSUaTs1MtRAgU
                  title: Quick variant lookup
              with_model:
                summary: On the highest-capability model
                value:
                  project_id: prj_0126xxQZB9MmSUaTs1MtRAgU
                  title: BRCA1 variant clinical report
                  model: max
              with_plan_mode:
                summary: With plan mode
                value:
                  project_id: prj_0126xxQZB9MmSUaTs1MtRAgU
                  title: BRCA1 variant clinical report
                  plan_mode: true
              with_initial_messages:
                summary: Start the agent right away
                value:
                  project_id: prj_0126xxQZB9MmSUaTs1MtRAgU
                  title: BRCA1 variant clinical report
                  initial_messages:
                    - role: user
                      content: Here are 3 BRCA1 variants to work up.
                    - role: user
                      content: Check ClinVar status for each.
      responses:
        '201':
          description: Task created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
              example:
                id: tsk_013ulkKbtuwHmE0ZlTLlnFU3
                type: task
                created_at: '2026-08-12T22:54:00.425353Z'
                status: running
                project_id: prj_0126xxQZB9MmSUaTs1MtRAgU
                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
        initial_messages:
          items:
            $ref: '#/components/schemas/InitialMessage'
          type: array
          maxItems: 20
          title: Initial Messages
        model:
          anyOf:
            - type: string
              enum:
                - standard
                - fast
                - max
            - type: 'null'
          title: Model
          description: >-
            Model tier for this task: `standard` (the default balance of speed
            and capability), `fast` (lower latency on a lighter model), or `max`
            (the highest-capability model).
        disable_fallbacks:
          type: boolean
          title: Disable Fallbacks
          description: Fail the task instead of switching to a fallback model or provider.
          default: false
        plan_mode:
          type: boolean
          title: Plan Mode
          default: false
        auto_mode:
          type: boolean
          title: Auto Mode
          default: false
      additionalProperties: false
      type: object
      required:
        - project_id
      title: CreateTaskRequest
    Task:
      properties:
        id:
          type: string
          title: Id
        type:
          type: string
          const: task
          title: Type
          default: task
        created_at:
          type: string
          format: date-time
          title: Created At
        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
        reviews:
          anyOf:
            - items:
                $ref: '#/components/schemas/TaskScientificReview'
              type: array
            - type: 'null'
          title: Reviews
      type: object
      required:
        - id
        - created_at
        - status
      title: Task
    InitialMessage:
      properties:
        role:
          type: string
          const: user
          title: Role
          default: user
        content:
          type: string
          minLength: 1
          title: Content
      additionalProperties: false
      type: object
      required:
        - content
      title: InitialMessage
      description: One message seeded into a new Task. Only `user` messages are accepted.
    TaskScientificReview:
      properties:
        type:
          type: string
          const: scientific_review
          title: Type
          default: scientific_review
        status:
          type: string
          enum:
            - running
            - done
            - failed
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        message_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Message Id
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
      type: object
      required:
        - status
        - created_at
      title: TaskScientificReview
      description: A scientific review recorded on a task.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Requires an API key. See the Authentication guide.

````