> ## 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.
# Quickstart
> From an API key to running an agent task and downloading its results
The Phylo API is currently in early access. To request access for your
organization, contact your Phylo representative or
[Phylo Support](mailto:support@phylo.bio).
## Prerequisites
* [A Phylo account](https://biomni.phylo.bio) with API access
* [An API key](/api/authentication)
The steps below assume your key is set as `PHYLO_API_KEY`:
```bash theme={null}
export PHYLO_API_KEY=""
```
To test your API key, try listing projects:
```bash theme={null}
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
To get started, let's create a project. Projects group related tasks and
files:
```bash theme={null}
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:
```json theme={null}
{
"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"
}
```
Now that we have a project, let's start a task. A task is one conversation
with the agent:
```bash theme={null}
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:
```json theme={null}
{
"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"
}
```
Now that the agent is working, let's check on it. `status` moves from
`running` to `completed`, `failed`, or `cancelled`:
```bash theme={null}
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:
```json theme={null}
{
"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.
Now that the task is done, let's collect its output. Save the files the
agent wrote:
```bash theme={null}
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:
```json theme={null}
{
"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.
Now that we have results, let's keep the conversation going. Ask a
follow-up in the same task:
```bash theme={null}
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:
```json theme={null}
{
"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](/api-reference/pages/upload-file) and attach it to a message
with `file_ids`, so the agent works on your own data.
* [Run a scientific review](/api-reference/pages/review-task) to have a reviewer
agent check a finished task's analysis for scientific accuracy.
* [Start a task](/api-reference/pages/start-task) with `plan_mode`, and the
agent writes a plan for you to approve before it starts work.
* [Errors](/api/errors) covers status codes, retries, and backoff.