--- title: "Predict the 3D structure (and affinity) of a protein/complex." method: POST path: "/v1/predictions" tags: ["predictions"] --- # Predict the 3D structure (and affinity) of a protein/complex. `POST /v1/predictions` ## Request - Base URL: `https://api.japanfold.aiand.com` - URL: `https://api.japanfold.aiand.com/v1/predictions` - Auth: one of: - none - HTTP bearer Provide `sequence` (single chain), `input` (one fasta/yaml string), or `targets` (a list). Returns a job to poll. ## Headers - `Idempotency-Key` string ## Request body - PredictRequest - `input` string: One FASTA or YAML input. FASTA headers can be plain names or UniProt headers, on every model: a record whose id the model can't hold (Boltz-2 takes 5 characters, OpenFold3 and OpenBind-0 4, ESMFold-2 16) or that repeats one is named A, B, ... with its type read from the sequence, and the job's `warnings` say which record became which chain. - `model` 'boltz2' | 'esmfold2' | 'esmfold2-fast' | 'openfold3' | 'openbind' | 'rf3' | 'opendde' | 'opendde-abag' | 'af2ig' - `name` string - `params` object: Model params: use_msa_server, fast, recycling_steps, sampling_steps, diffusion_samples, output_format, seed, write_pae, use_tfg_guidance. Not every model takes every one, and a param the chosen model cannot honour is a 400 naming the model and the param rather than a value accepted and ignored: fast only on models whose caps list it, use_msa_server only on models with the msa cap, and neither recycling_steps on OpenFold3/OpenBind-0 nor sampling_steps on RoseTTAFold3 (their engine resolves those when it loads the model, not per job). ESMFold-2 always runs fast on this hardware, so its job reports fast: true whatever you send. Fast mode is off unless you send fast: true (higher throughput, may be slightly less accurate); the workbench turns it on for you, the API does not. Omitted params take the default GET /v1/models advertises for that model, and an explicit null means omitted. The two exceptions are recycling_steps and sampling_steps: leave them out and each model uses its own recommended value (recycling: Boltz-2, OpenFold3, OpenBind-0 and AF2-IG 3, the others 10; diffusion steps: ESMFold-2 100, RoseTTAFold3 50, the others 200). A number outside the advertised range is clamped to the nearest bound; a value that is not a number at all is a 400. The accepted values are on the job's params, including the seed the fold ran with (0 unless you send one). write_pae, on a model whose caps list pae, adds _pae.npz to the artifacts: the predicted aligned error matrix of the top-ranked structure, which is what Adaptyv's ipSAE pipeline reads. - `sequence` string: Single protein chain (convenience). - `targets` Target[] - `content` string, required: FASTA or YAML input. FASTA headers can be plain names or UniProt headers, on every model: a record whose id the model can't hold (Boltz-2 takes 5 characters, OpenFold3 and OpenBind-0 4, ESMFold-2 16) or that repeats one is named A, B, ... with its type read from the sequence, and the job's `warnings` say which record became which chain. - `name` string ## Response `202` Job - Job - `artifacts` object[]: Present on a succeeded job read by its id (not in the list), when it has at most 20 files: the same entries as `artifacts` in its results. A job with more files lists them only in its results. - `attempt` integer: Present only when the job's structure is on its second run, because the box running it stopped answering (hung, or its agent died); its progress started over. A job of several structures carries it on the retried entry of targets. Billed once. - `created_at` string, date-time, nullable - `done` integer - `download` string: Present on a succeeded job read by its id: one shell command that fetches every result file into the current directory, reading the key from `JAPANFOLD_API_KEY`. Past 20 files it fetches and unzips the archive instead. - `email_when_done` boolean: Present once POST /v1/jobs/{id}/notify has been asked. - `error` string, nullable: Why the job failed; on a succeeded job, what it could not deliver (see partial). - `finished_at` string, date-time, nullable - `id` string, required - `kind` 'predict' | 'design' | 'embed', required - `links` object - `model` string, nullable - `name` string - `object` 'job', required - `partial` object: Present only on a succeeded job that delivered less than it was asked for, because a design shard or a target failed. What did finish is in the results and was billed; error says what was lost. - `delivered` integer - `requested` integer: designs you would get back (the smaller of budget and num_designs), or structures submitted - `shards` integer - `shards_failed` integer - `unit` 'designs' | 'structures' - `progress` number, nullable: 0..1, or null when indeterminate - `protocol` string, nullable - `queue` object: Present while any of the job's tasks waits for a chip. Facts, never a time: how long the work ahead takes is not known until it ends. The next free chip goes to the account holding the fewest chips, then the one that used the least in the last hours; an account's own jobs run in the order it sent them. - `reason` 'busy': On a submit's 429, why: the queue ahead of the submission was longer than the API will hold a request open for, so it was refused rather than admitted late. Nothing is written and nothing is charged. Honour `Retry-After`. - `results_ready` boolean - `stage` string, nullable - `started_at` string, date-time, nullable - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required - `total` integer - `waiting_for_device` boolean: Present and true only while the job has been accepted but no processor is free for it yet. The job is queued, not stalled. ## Other responses - `400`: Invalid request - `401`: Unauthorized - `402`: Insufficient balance: what the run would cost, and where to add funds - `422`: Idempotency-Key already used with a different body - `429`: Over a rate limit, or the queue is too busy to admit this in time - `503`: No Galaxy serves this model right now --- [API](https://skmtc.dev/aiand/apis/japanfold-api.md) · [All operations](https://skmtc.dev/aiand/apis/japanfold-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aiand/apis/japanfold-api/revisions/9f4be813b447?raw)