Quickstart

The Phylo API is currently in early access. To request access for your organization, contact your Phylo representative or Phylo Support.

Prerequisites

A Phylo account with API access
An API key

The steps below assume your key is set as PHYLO_API_KEY:

export PHYLO_API_KEY="<your-api-key>"

To test your API key, try listing projects:

curl https://api.phylo.bio/v1/projects \
  -H "Authorization: Bearer $PHYLO_API_KEY"

Note that https://api.phylo.bio/v1 is the self-serve base URL. If you’re an Enterprise customer, contact your Phylo representative for your API base URL.

Using a Biomni agent

Create a project

To get started, let’s create a project. Projects group related tasks and files:

PROJECT_ID=$(curl -s -X POST https://api.phylo.bio/v1/projects \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "BRCA1 variant workup"}' | jq -r '.id')

This returns something like:

{
  "id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "type": "project",
  "title": "BRCA1 variant workup",
  "description": "",
  "created_at": "2026-08-12T21:21:01.919692Z",
  "updated_at": "2026-08-12T21:21:01.919698Z"
}

Start a task

Now that we have a project, let’s start a task. A task is one conversation with the agent:

TASK_ID=$(curl -s -X POST https://api.phylo.bio/v1/experimental/tasks \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$PROJECT_ID"'",
    "title": "BRCA1 variant workup",
    "auto_mode": true,
    "initial_messages": [
      {"role": "user", "content": "Look up the ClinVar status of BRCA1 variants rs80357065, rs28897696, and rs80357382, and write a short markdown summary report."}
    ]
  }' | jq -r '.id')

This returns something like:

{
  "id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
  "type": "task",
  "created_at": "2026-08-12T21:21:02.815306Z",
  "status": "running",
  "project_id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "title": "BRCA1 variant workup",
  "platform": "api"
}

Check the status

Now that the agent is working, let’s check on it. status moves from running to completed, failed, or cancelled:

curl -s https://api.phylo.bio/v1/experimental/tasks/$TASK_ID \
  -H "Authorization: Bearer $PHYLO_API_KEY" | jq -r '.status'

The full record returns something like:

{
  "id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
  "type": "task",
  "created_at": "2026-08-12T21:21:02.815000Z",
  "status": "completed",
  "project_id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "title": "BRCA1 variant workup",
  "platform": "api",
  "reviews": []
}

Agent tasks can run for hours, so design for long-running work rather than blocking a single request on the result.

Download the results

Now that the task is done, let’s collect its output. Save the files the agent wrote:

curl -s "https://api.phylo.bio/v1/experimental/tasks/$TASK_ID/results?with_urls=true" \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  | jq -r '.data[] | .download_url + " -o " + .name' \
  | xargs -L1 curl -s

The results list returns something like:

{
  "type": "list",
  "data": [
    {
      "type": "result_file",
      "result_id": "res_016YNAz7cvmPXcqvGoR1U57t",
      "name": "BRCA1_ClinVar_variant_summary.md",
      "size_bytes": 6149,
      "mime_type": "text/markdown",
      "message_id": null,
      "created_at": "2026-08-12T21:23:32Z",
      "download_url": "https://files.s3.us-west-2.amazonaws.com/...?X-Amz-Signature=..."
    }
  ],
  "has_more": false,
  "first_id": "res_016YNAz7cvmPXcqvGoR1U57t",
  "last_id": "res_016YNAz7cvmPXcqvGoR1U57t"
}

download_url is presigned and short-lived, so fetch it soon after listing.

Send a message

Now that we have results, let’s keep the conversation going. Ask a follow-up in the same task:

curl -s -X POST https://api.phylo.bio/v1/experimental/tasks/$TASK_ID/messages \
  -H "Authorization: Bearer $PHYLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Which of those three variants has the strongest PARP inhibitor evidence?"}'

This returns your message and the agent’s reply so far:

{
  "type": "message_result",
  "user_message": {
    "id": "msg_f6872d1e0fb242fd",
    "type": "message",
    "task_id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
    "created_at": "2026-08-12T21:26:51.413000Z",
    "role": "user",
    "content": [
      {"type": "text", "text": "Which of those three variants has the strongest PARP inhibitor evidence?"}
    ],
    "platform": "api"
  },
  "assistant_message": {
    "id": "msg_0e9eb143c44838c4",
    "type": "message",
    "task_id": "tsk_017ilCeuDpMWTSH9Ah1syUGJ",
    "created_at": "2026-08-12T21:26:28.611000Z",
    "role": "assistant",
    "content": [
      {
        "type": "text",
        "text": "Searching PubMed and CIViC for PARP inhibitor and functional HDR evidence for each of the three BRCA1 variants."
      },
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01BmvmDbqJwohi5WxdBoWk17",
        "content": "{\"delivered\": true}"
      }
    ],
    "status": "streaming",
    "platform": "api",
    "input": {"user_message_id": "msg_f6872d1e0fb242fd", "file_ids": []}
  }
}

Where to go next

Congratulations, you just ran a Biomni agent! That loop is the foundation, and there is a lot more the agent can do:

Upload a file and attach it to a message with file_ids, so the agent works on your own data.
Run a scientific review to have a reviewer agent check a finished task’s analysis for scientific accuracy.
Start a task with plan_mode, and the agent writes a plan for you to approve before it starts work.
Errors covers status codes, retries, and backoff.

Guides

Recipes

API reference

Prerequisites

Using a Biomni agent

Where to go next

​Prerequisites

​Using a Biomni agent

​Where to go next

Prerequisites

Using a Biomni agent

Where to go next