PRIME — Web Services
Everything the PRIME page does is an HTTP call, and a job submitted from a script is the same job as one submitted from the browser. There is no key, no account and no rate limit beyond an anti-flood cap of a few submissions per minute per address.
Download the Python client Sample structure
Quick start
The client is standard library only — no installation:
curl -O https://onodalab.ees.hokudai.ac.jp/static/prime/prime_client.py # one structure, by PDB id python3 prime_client.py --id 12CA --metals ZN # one structure from disk, every supported ion python3 prime_client.py --file 12ca.cif --metals ALL -o out/
Endpoints
Base URL https://onodalab.ees.hokudai.ac.jp/prime. All responses are JSON except artifact downloads.
POST /prime/api/jobs
Submit a job. multipart/form-data, returns a job id. Provide either structure_file or protein_id.
| Field | Default | Meaning |
|---|---|---|
structure_file | — | A .pdb, .cif, .mmcif or .ent file, up to 64 MB. Batch submission (an archive of structures) is disabled. |
protein_id | — | A 4-character PDB id or a UniProt accession, one per submission. |
metal_type | ZN | One ion, a comma-separated list, or ALL. Supported: ZN CA MG MN FE FE2 CU CU1 CO NI CD HG NA K. |
chain | every chain | Restrict the scan to one chain id. |
top_k | 0 | Maximum probes kept per chain, ranked by coordination statistics. Set to 0 to keep all probes. |
max_rot | 5 | Fixed rotations each probe is scored at, 1–5. |
rot_seed | 0 | Non-negative integer seed used to generate the fixed rotation set. Reusing a seed reproduces the same rotations. |
cluster_dist | 3.0 | Distance in Å within which predicted ion positions are merged into one site, 0.5–10. Use a smaller value, such as 1.0, for ion channels, whose sites sit close together along the selectivity filter. |
curl -s -F 'protein_id=12CA' -F 'metal_type=ZN' \
https://onodalab.ees.hokudai.ac.jp/prime/api/jobs
{"job_id": "j_3f2a91c07b5e", "status": "queued"}
GET /prime/api/jobs/<job_id>
Status and progress. status is queued, running, succeeded, failed, canceled or expired; a queued job also reports its position.
{"status": "running",
"progress": {"phase": "predict", "current": 3, "total": 4, "pct": 75.0,
"message": "3/4 structures, 11 sites"}}
GET /prime/api/jobs/<job_id>/result
The finished result. 409 while the job is still running, so poll the status endpoint rather than this one.
{"count": 1,
"batch": false,
"binding_sites": [
{"element": "ZN", "chain": "A", "position": [-7.316, 1.089, 15.204],
"confidence": 0.998, "n_probes": 6, "residue_id": 1000}],
"stats": {"metals": ["ZN"], "top_k": 0, "max_rot": 5,
"rot_seed": 0, "n_structures": 1, "n_sites": 1, "seconds": 0.61,
"proteins_per_second": 1.64}}
GET /prime/artifact/<job_id>/<name>
| Artifact | Job | Contents |
|---|---|---|
predicted.pdb | single | The predicted ions as HETATM records in chain Z, confidence in the B-factor column. |
complex.pdb | single | The input structure with those ions merged in, ready for a viewer. |
sites.csv | single | One row per site: metal, chain, x, y, z, confidence, n_probes. |
input.cif / input.pdb | single | The structure as it was submitted or fetched. |
Errors
Failures carry a JSON body. 400 is a problem with the submission (an unreadable file, an unknown ion, an id that does not resolve), 409 means the job is not finished or did not succeed, 429 means too many submissions from one address in a minute, and 503 means the prediction service is restarting.
Running it locally instead
For a scan larger than one structure at a time — a whole proteome, or a pipeline that should not depend on this server staying up — the engine runs anywhere ROCm or CUDA does. The code is MIT licensed and the published checkpoints come from the PRIME release.