Upload a file

curl --request POST \
  --url https://api.phylo.bio/v1/experimental/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": "prj_0126xxQZB9MmSUaTs1MtRAgU",
  "filename": "patient001_brca1.vcf",
  "size_bytes": 4321
}
'

{
  "type": "upload_intent",
  "file_id": "file_017jG6PPIYy41dqnVz47lrmo",
  "project_id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "path": "orgs/<org>/users/<user>/uploads/projects/proj_6b3606df1c/patient001_brca1.vcf",
  "upload_type": "single",
  "expires_at": "2026-08-12T22:20:08.147475Z",
  "filename": "patient001_brca1.vcf",
  "size_bytes": 4321,
  "mime_type": "text/plain",
  "upload_url": "https://<bucket>.s3.us-west-2.amazonaws.com/",
  "fields": {
    "Content-Type": "text/plain",
    "key": "orgs/<org>/users/<user>/uploads/projects/proj_6b3606df1c/patient001_brca1.vcf",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "<credential>/20260812/us-west-2/s3/aws4_request",
    "x-amz-date": "20260812T220508Z",
    "x-amz-security-token": "<token>",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0w...",
    "x-amz-signature": "5a8d..."
  }
}

POST

experimental

files

curl --request POST \
  --url https://api.phylo.bio/v1/experimental/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": "prj_0126xxQZB9MmSUaTs1MtRAgU",
  "filename": "patient001_brca1.vcf",
  "size_bytes": 4321
}
'

{
  "type": "upload_intent",
  "file_id": "file_017jG6PPIYy41dqnVz47lrmo",
  "project_id": "prj_014OwAG97UY0UfcHlLHQRnKO",
  "path": "orgs/<org>/users/<user>/uploads/projects/proj_6b3606df1c/patient001_brca1.vcf",
  "upload_type": "single",
  "expires_at": "2026-08-12T22:20:08.147475Z",
  "filename": "patient001_brca1.vcf",
  "size_bytes": 4321,
  "mime_type": "text/plain",
  "upload_url": "https://<bucket>.s3.us-west-2.amazonaws.com/",
  "fields": {
    "Content-Type": "text/plain",
    "key": "orgs/<org>/users/<user>/uploads/projects/proj_6b3606df1c/patient001_brca1.vcf",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "<credential>/20260812/us-west-2/s3/aws4_request",
    "x-amz-date": "20260812T220508Z",
    "x-amz-security-token": "<token>",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0w...",
    "x-amz-signature": "5a8d..."
  }
}

Uploads go directly to cloud storage. The API returns an upload target and never receives the bytes. The response’s upload_type selects the flow and is chosen from the size_bytes you declare.

`upload_type: "single"`

POST /experimental/files returns a file_id, an upload_url, and the fields to send with the bytes.
POST the bytes to upload_url as multipart form-data, with every key in fields included as a form field. Success returns 204 No Content.
POST /experimental/files/{file_id}/finalize with an empty body.

`upload_type: "multipart"`

POST /experimental/files returns a file_id, an upload_id, a part_size_bytes, and a part_count.
Split the file into part_count chunks of part_size_bytes. The last chunk is the remainder.
POST /experimental/files/{file_id}/parts with the upload_id and the part numbers you want, which returns a PUT URL per part. You can request them in batches.
PUT each chunk to its URL and keep the ETag response header for that part number.
POST /experimental/files/{file_id}/finalize with { "upload_id": "…", "parts": [{ "part_number": 1, "etag": "…" }, … ] }.

Once finalized, attach the file_id to a task with file_ids on POST /experimental/tasks/{id}/messages.

Authorizations

Authorization

string

header

required

Requires an API key. See the Authentication guide.

Body

application/json

project_id

string

required

filename

string

required

size_bytes

integer

required

mime_type

string | null

Response

200 - application/json

Upload started. For upload_type=single, POST the bytes to upload_url with fields. For upload_type=multipart, pass upload_id to POST /experimental/files/{file_id}/parts.

project_id

string

required

filename

string

required

size_bytes

integer

required

type

string

default:upload_intent

Allowed value: "upload_intent"

file_id

string | null

path

string | null

upload_type

enum<string>

default:single

Available options:

single,

multipart

upload_url

string | null

fields

Fields · object

upload_id

string | null

part_size_bytes

integer | null

part_count

integer | null

expires_at

string<date-time> | null

mime_type

string | null

Guides

Recipes

API reference

`upload_type: "single"`

`upload_type: "multipart"`

Authorizations

Body

Response

​upload_type: "single"

​upload_type: "multipart"

Authorizations

Body

Response

`upload_type: "single"`

`upload_type: "multipart"`