API

Every part of Phage Annotation Server is scriptable. Submit a genome, poll for completion, and pull structured annotations back — no HTML parsing, no API key, no account.

Start here: api_client.py — a complete, dependency-free Python template that submits a job, waits for it, downloads the results and parses them. Copy it and adapt.

python3 api_client.py my_phage.fasta or python3 api_client.py --example

Base URL

https://phage-annotation.org

Send Accept: application/json on submission. Without it the server replies with a browser-style 303 redirect and you have to read the job id out of the Location header.

Endpoints

Method	Path	Returns	Purpose
`POST`	`/jobs`	JSON `202`	Submit a genome (multipart). Returns `job_id` plus status, results and download URLs. Send `example=1` and no file to run the bundled sample genome.
`GET`	`/jobs/{id}/status.json`	JSON	Current state, active stage, elapsed time, per-stage timings, and on failure an `error_code`, `error_message` and plain-English `error_hint`. Poll this.
`GET`	`/jobs/{id}/browser.json`	JSON	Per-contig CDS features with coordinates, strand, product and PHROG category — the most convenient machine-readable view of the annotations.
`GET`	`/jobs/{id}/files/{path}`	file	One result file, e.g. `phynteny/phynteny.tsv`, `phold/phold.gbk`, `pharokka/pharokka.gff`.
`GET`	`/jobs/{id}/download`	zip	Every user-facing result file, plus the per-stage tool logs and a version manifest.
`POST`	`/jobs/batch-status`	JSON	State for several job ids at once (max 50). Only ever returns data for ids you supply.

Submission parameters

All optional except the sequence itself. Anything omitted uses the tool's own default, and every value is re-validated server-side.

Field	Values	Default
`fasta`	the file (multipart)	—
`example`	`1` to use the bundled sample genome instead of a file	off
`gene_predictor`	`phanotate` / `prodigal` / `prodigal-gv`	`phanotate`
`fast`	`true` / omit	on
`email`	address for a completion notice	none
`meta_mode`	`auto` / `on` / `off`	`auto`

The full set of advanced pharokka / phold / phynteny parameters is on the submit form under Advanced options; each is labelled with its real CLI flag and accepts the same field name here.

A minimal example

curl -sS -H "Accept: application/json" \
     -F "example=1" -F "gene_predictor=phanotate" -F "fast=true" \
     https://phage-annotation.org/jobs

# -> {"job_id": "...", "status_url": "...", "results_url": "...", "download_url": "..."}

curl -sS https://phage-annotation.org/jobs/<job_id>/status.json

Fair use

Submissions are rate-limited per IP; the example counts too.
Poll status.json at a sensible interval — every 10–30 s is plenty. A typical job takes about a minute.
Results are deleted after the retention window in the terms of use. Download what you need.
For bulk annotation, install the tools locally — it will be faster for you and fairer to everyone sharing this server.

Interactive schema

An OpenAPI schema is generated automatically at /openapi.json, with browsable docs at /docs. The table above is the supported, stable surface; treat anything else in the schema as internal.