Quickstart

Prerequisites

A Phylo account on a Pro or Team plan, with a prepaid balance. API usage draws only on the prepaid balance, not on your daily credit allowance. See Plan and billing.
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": "running",
    "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