Skip to main content
POST
/
v1
/
therapeutic-candidates
Register a new therapeutic candidate
curl --request POST \
  --url https://api.example.com/v1/therapeutic-candidates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "antigen_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "description": "Humanized anti-HER2 lead",
  "drug_class": "naked_antibody",
  "format": "mab",
  "initial_chains": [
    {
      "chain_id": "H",
      "role": "heavy",
      "variable_sequence": "QVQLV..."
    },
    {
      "chain_id": "L",
      "role": "light",
      "variable_sequence": "DIQMTQ..."
    }
  ],
  "name": "anti-HER2 mab",
  "project_id": "7b4a3c0f-2e6d-4c7a-9e8f-1d3b5a2c4e6f",
  "source_antibody_ids": [
    "1111aaaa-2222-3333-4444-5555bbbbcccc"
  ]
}
'
{
  "antigen_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ],
  "created_at": "2026-04-23T14:15:00+00:00",
  "drug_class": "naked_antibody",
  "format": "mab",
  "format_metadata": {},
  "id": "c0f5e4b1-a7d2-4e0b-9f8c-1b2d3e4f5a6b",
  "initial_variant_id": "9999eeee-8888-dddd-7777-cccc66665555",
  "name": "anti-HER2 mab",
  "object": "therapeutic_candidate",
  "project_id": "7b4a3c0f-2e6d-4c7a-9e8f-1d3b5a2c4e6f",
  "source_antibody_ids": [
    "1111aaaa-2222-3333-4444-5555bbbbcccc"
  ],
  "updated_at": "2026-04-23T14:15:00+00:00"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body for POST /v1/therapeutic-candidates.

Mirrors :class:app.schemas.candidates.CandidateCreate but annotated for the /v1 OpenAPI surface. initial_chains is required — the service auto-creates the baseline variant (v1) and its chains atomically; failures roll the candidate row back, so the DB never ends up with a candidate missing its baseline.

​
project_id
string
required

Project the candidate belongs to. Must be owned by the caller's org.

Example:

"7b4a3c0f-2e6d-4c7a-9e8f-1d3b5a2c4e6f"

​
name
string
required

Short human label (e.g. anti-HER2 mab).

Required string length: 1 - 120
Example:

"anti-HER2 mab"

​
format
enum<string>
required

Molecular format — see the envelope's format field.

Available options:
mab,
nanobody,
scfv,
fc_fusion,
bispecific_kih,
bispecific_crossmab,
bispecific_common_lc,
bite,
dart,
dvd_ig,
tandem_scfv,
trispecific_tandem_scfv,
trispecific_igg_scfv,
trispecific_knh_scfv
​
initial_chains
VariantChainSpec · object[]
required

Chain specs used to build the baseline variant (v1). At least one chain is required. References in the chain specs (source_antibody_id, constant_region_id) are scope-checked before insert; custom constant-region rows must belong to the caller's org, but the built-in library (org_id IS NULL) is always accessible.

Minimum array length: 1
​
drug_class
enum<string>
default:naked_antibody

Therapeutic modality. Defaults to naked_antibody.

Available options:
naked_antibody,
adc,
car,
radioconjugate,
t_cell_engager
​
format_metadata
Format Metadata · object

Format-specific metadata (bispecific arm assignments, etc.).

​
description
string | null

Optional freeform note.

​
source_antibody_ids
string[]

IDs of parental antibodies to link at create time. Every id must walk back to the caller's org; cross-org ids return 404.

​
antigen_ids
string[]

IDs of antigens this candidate targets. Cross-org ids return 404.

Response

Successful Response

A therapeutic candidate as returned by /v1.

Carries the junction-table IDs (source antibodies, antigens) and the initial_variant_id surfaced by create_candidate so a caller can submit pipelines against it without a second round-trip.

​
id
string
required

Opaque therapeutic-candidate identifier (UUID).

Example:

"c0f5e4b1-a7d2-4e0b-9f8c-1b2d3e4f5a6b"

​
project_id
string
required

Project this candidate belongs to.

Example:

"7b4a3c0f-2e6d-4c7a-9e8f-1d3b5a2c4e6f"

​
name
string
required

Short human label shown in dashboards and logs.

​
format
enum<string>
required

Molecular format. Single-arm (mab, nanobody, scfv, fc_fusion) require one H+L pair or a single-chain spec. Multi-arm formats require all arms' chain specs at create time.

Available options:
mab,
nanobody,
scfv,
fc_fusion,
bispecific_kih,
bispecific_crossmab,
bispecific_common_lc,
bite,
dart,
dvd_ig,
tandem_scfv,
trispecific_tandem_scfv,
trispecific_igg_scfv,
trispecific_knh_scfv
​
drug_class
enum<string>
required

Therapeutic modality. naked_antibody is the default; adc and radioconjugate require a subsequent ADC-design record before payload synthesis.

Available options:
naked_antibody,
adc,
car,
radioconjugate,
t_cell_engager
​
created_at
string
required

ISO-8601 timestamp (UTC) when the candidate was registered.

​
updated_at
string
required

ISO-8601 timestamp (UTC) of the most recent mutation.

​
object
string
default:therapeutic_candidate

Polymorphic discriminator. Always therapeutic_candidate.

Allowed value: "therapeutic_candidate"
​
format_metadata
Format Metadata · object

Free-form metadata bag — the bispecific formats use this for arm assignments; other formats leave it empty.

​
description
string | null

Optional freeform note shown alongside the candidate.

​
source_antibody_ids
string[]

Source (parental) antibodies linked to this candidate. Maintained via the /v1/therapeutic-candidates/{id}/source-antibodies/{sa_id} endpoints.

​
antigen_ids
string[]

Antigens this candidate targets. Maintained via the /v1/therapeutic-candidates/{id}/antigens/{antigen_id} endpoints.

​
initial_variant_id
string | null

The baseline variant (v1) auto-created alongside this candidate. Populated on create responses; null on read responses — to walk variants post-creation, list them via the variants resource (not yet exposed in /v1, Phase 3 follow-up).