---
title: "Design binders/proteins against a target (BoltzGen, RFdiffusion3 or PXDesign)."
method: POST
path: "/v1/designs"
tags: ["designs"]
---

# Design binders/proteins against a target (BoltzGen, RFdiffusion3 or PXDesign).

`POST /v1/designs`

## Request

- Base URL: `https://api.japanfold.aiand.com`
- URL: `https://api.japanfold.aiand.com/v1/designs`
- Auth: one of:
  - none
  - HTTP bearer

The protocol picks the design model: the six boltzgen protocols take a `spec` (YAML); rfd3-* takes `structure` + `contig`; pxdesign-* takes `structure` + `chains` + `binder_length`. An explicit `model` is optional but must match the protocol's model when given.

## Headers

- `Idempotency-Key` string

## Request body

- DesignRequest
  - `binder_length` integer: Residues in the designed binder (8-200). pxdesign-* protocols only.
  - `chains` string: Target chain ids to design against, e.g. 'A' or 'A,B'. pxdesign-* protocols only.
  - `contig` string: RFdiffusion3 contig string, e.g. 'A1-150,60-80': fixed chain-ranges plus designed-length segments. rfd3-* protocols only.
  - `hotspots` string: Optional target residues to aim the binder at, e.g. 'A64,A65,A66' (or bare numbers when one chain is named). pxdesign-* protocols only.
  - `model` 'boltzgen' | 'rfd3' | 'pxdesign': Design model. Optional: the protocol already implies it; when given, it must match (a mismatch is a 400).
  - `name` string
  - `params` object: BoltzGen: num_designs, budget, fast. RFdiffusion3: num_designs, num_timesteps, seed. PXDesign: num_designs, n_step, seed. Omitted params take the default GET /v1/models advertises (BoltzGen 10 designs, budget 10, fast off; RFdiffusion3 4 designs, 100 diffusion steps; PXDesign 4 designs, 200 diffusion steps). Numeric values outside the advertised range are clamped to the nearest bound; the accepted values are on the job's params.
  - `protocol` 'protein-anything' | 'peptide-anything' | 'nanobody-anything' | 'antibody-anything' | 'protein-small_molecule' | 'protein-redesign' | 'rfd3-binder' | 'rfd3-scaffold' | 'rfd3-na-binder' | 'pxdesign-binder'
  - `spec` string: BoltzGen protocols only. A YAML list under `entities:` (not predict's `sequences:`); the chain to design has a residue-count range as its sequence. A minimal protein binder: entities: - protein: id: A sequence: <target sequence> - protein: id: B sequence: 60..80 A spec the engine would reject is refused with a 400 at submit.
  - `structure` string: Target structure as PDB or mmCIF text. Required for the rfd3-* protocols (with contig) and the pxdesign-* protocols (with chains and binder_length).

## 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)