Create experiment

Creates a new experiment request for the Adaptyv Foundry platform.

The payload captures the target (from the catalog), antibody sequences, replicate plan, assay parameters, optional metadata, and an optional webhook for notifications. By default, experiments are created in Draft status so clients can review inputs before submission.

Set skip_draft: true to bypass Draft status and submit directly for processing. This is useful for automated pipelines with pre-validated payloads that don’t require manual review. The experiment will be created in “Waiting for confirmation” status instead of Draft.

API-originated experiments are automatically assigned to the organization’s API submissions project for traceability.

ExperimentSpec fields

Validation is strict: fields that are not applicable to a given experiment type (e.g., method on a non-binding type) cause a 400 rejection. Multiple validation errors are accumulated and returned together so callers can fix everything in one round-trip.

Field	Type	Description
experiment_type	string	Required. One of affinity, screening, thermostability, fluorescence, expression, epitope_binning, enzyme_activity.
method	string	Required for affinity/screening (bli or spr). Rejected for all other types.
target_id	string	Target UUID from the catalog. Required for affinity, screening, and epitope_binning. Rejected for non-binding types.
sequences	object	Required. Map of sequence name to amino acid string. epitope_binning requires exactly 4-28 sequences in multiples of 4.
n_replicates	integer	Optional for most types (default 3, range 1-5). Rejected for epitope_binning.
antigen_concentrations	array	affinity only; optional, defaults to [1000.0, 316.2, 100.0, 31.6, 0.0] nM.
parameters	object	Optional. Experiment-specific settings

Sequence Formats

The sequences field accepts two formats:

Simple format — amino acid string only:

"sequences": {
  "seq1": "EVQLVESGGGLVQPGGSLRLSCAAS"
}

Object format — with metadata:

"sequences": {
  "seq1": {
    "aa_string": "EVQLVESGGGLVQPGGSLRLSCAAS",
    "control": false,
    "metadata": { "type": "scfv", "tag_location": "C" }
  }
}

Example: Affinity (BLI)

Full kinetic characterization measuring on/off rates and KD. Target ID c383cc1d-fe22-5dbf-953c-378bc073019d is Human PD-L1 from the catalog.

{
  "name": "PD-L1 affinity panel",
  "experiment_spec": {
    "experiment_type": "affinity",
    "method": "bli",
    "target_id": "c383cc1d-fe22-5dbf-953c-378bc073019d",
    "sequences": {
      "pembrolizumab_vh": "QVQLVQSGVEVKKPGASVKVSCKASGYTFTNYYMYWVRQAPGQGLEWMGGINPSNGGTNFNEKFKNRVTLTTDSSTTTAYMELKSLQFDDTAVYYCARRDYRFDMGFDYWGQGTTVTVSS",
      "pembrolizumab_vl": "EIVLTQSPATLSLSPGERATLSCRASKGVSTSGYSYLHWYQQKPGQAPRLLIYLASYLESGVPARFSGSGSGTDFTLTISSLEPEDFAVYYCQHSRDLPLTFGGGTKVEIK"
    },
    "n_replicates": 3,
    "antigen_concentrations": [1000.0, 316.2, 100.0, 31.6, 0.0]
  },
  "webhook_url": "https://example.com/webhook"
}

Example: Screening (SPR)

High-throughput yes/no binding assessment using SPR.

{
  "name": "Library screening round 1",
  "experiment_spec": {
    "experiment_type": "screening",
    "method": "spr",
    "target_id": "c383cc1d-fe22-5dbf-953c-378bc073019d",
    "sequences": {
      "clone_A1": "EVQLVESGGGLVQPGGSLRLSCAASGFTFSSYAMSWVRQAPGKGLEWVSAISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRLSITIRPRYYGLDVWGQGTLVTVSS",
      "clone_A2": "QVQLVQSGAEVKKPGASVKVSCKASGYTFTSYGISWVRQAPGQGLEWMGWISAYNGNTNYAQKLQGRVTMTTDTSTSTAYMELRSLRSDDTAVYYCARDVGYCTDYSCYFDYWGQGTLVTVSS",
      "clone_A3": "EVQLLESGGGLVQPGGSLRLSCAASGFTFSTYAMSWVRQAPGKGLEWVSSISSGGSYIYYADSVKGRFTISRDNAKNSLYLQMNSLRAEDTAVYYCARRPWGYYALDIWGQGTTVTVSS"
    },
    "n_replicates": 2
  }
}

Example: Thermostability

Measures melting temperature (Tm) via differential scanning fluorimetry. No target required.

{
  "name": "Lead candidates stability",
  "experiment_spec": {
    "experiment_type": "thermostability",
    "sequences": {
      "candidate_1": "QVQLVQSGAEVKKPGASVKVSCKASGYTFTSYAMHWVRQAPGQRLEWMGWINAGNGNTKYSQKFQGRVTITRDTSASTAYMELSSLRSEDTAVYYCARAKFGATGAFDIWGQGTMVTVSS",
      "candidate_2": "EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCSRWGGDGFYAMDYWGQGTLVTVSS"
    },
    "n_replicates": 3,
    "parameters": {
      "buffer": "PBS",
      "ph": 7.4
    }
  }
}

Example: Fluorescence

Fluorescence-based protein characterization measuring intrinsic properties. No target required.

{
  "name": "Fluorescence characterization",
  "experiment_spec": {
    "experiment_type": "fluorescence",
    "sequences": {
      "variant_1": "QVQLVQSGAEVKKPGASVKVSCKASGYTFTSYDINWVRQATGQGLEWMGWMNPNSGNTGYAQKFQGRVTMTRDTSISTAYMELRSLRSDDTAVYYCARGGFYGSTIWFDYWGQGTLVTVSS",
      "variant_2": "EVQLVESGGGLVQPGGSLRLSCAASGFTFSSYWMSWVRQAPGKGLEWVANIKQDGSEKYYVDSVKGRFTISRDNAKNSLYLQMNSLRAEDTAVYYCARDRYGNYVDYWGQGTLVTVSS"
    },
    "n_replicates": 3
  }
}

Example: Expression

Protein expression screening measuring yield and quality. No target required.

{
  "name": "Expression screening",
  "experiment_spec": {
    "experiment_type": "expression",
    "sequences": {
      "construct_A": "QVQLVQSGAEVKKPGASVKVSCKASGYTFTSYGISWVRQAPGQGLEWMGWISAYNGNTNYAQKLQGRVTMTTDTSTSTAYMELRSLRSDDTAVYYCARDVGYCTDYSCYFDYWGQGTLVTVSS",
      "construct_B": "EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCSRWGGDGFYAMDYWGQGTLVTVSS"
    },
    "n_replicates": 2
  }
}

Example: With skip_draft=true (Auto-Submit)

Bypass Draft status and submit directly for processing:

{
  "name": "Pre-validated batch",
  "skip_draft": true,
  "experiment_spec": {
    "experiment_type": "thermostability",
    "sequences": {
      "seq1": "EVQLVESGGGLVQPGGSLRLSCAASGFTFSSYAMSWVRQAPGKGLEWVSAISGSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRLSITIRPRYYGLDVWGQGTLVTVSS"
    },
    "n_replicates": 2
  }
}

POST /api/v1/experiments

Create experiment

cURL

curl --request POST \
  --url https://foundry-api-public.adaptyvbio.com/api/v1/experiments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "experiment_spec": {
    "antigen_concentrations": [
      1000,
      316.2,
      100,
      31.6,
      0
    ],
    "n_replicates": 3,
    "parameters": "<unknown>",
    "sequences": {},
    "target_id": "c383cc1d-fe22-5dbf-953c-378bc073019d"
  },
  "name": "PD-L1 affinity panel",
  "auto_accept_quote": false,
  "skip_draft": true,
  "webhook_url": "https://example.com/webhook"
}
'

201

{
  "experiment_id": "<string>",
  "error": "<string>",
  "stripe_hosted_invoice_url": "<string>",
  "stripe_invoice_id": "<string>"
}

Authorizations

Authorization · string · header · required

Biscuit-based bearer token. Obtain tokens from the Adaptyv Portal or via the /tokens endpoint. Tokens encode organization membership and role-based capabilities; the API verifies the token's cryptographic signature and authorization claims before processing requests. Use /tokens/attenuate to create restricted tokens for delegation.

Body

application/json

Request payload for creating a new experiment.

Created experiments start in Draft status. Use PATCH /experiments/{id} to modify existing experiments.

experiment_spec · object · required

Structured experiment definition (type, target, sequences, parameters)

Show child attributes

name · string · required

Human-readable name for the experiment

Example:

"PD-L1 affinity panel"

auto_accept_quote · boolean · default: false

Auto-accept the quote and create an invoice (without sending).

When true, the system will:

1. Create a Stripe quote (requires target_id and full pricing available)
2. Finalize and accept the quote
3. Create a draft invoice (not sent to customer)
4. Advance the experiment to "Waiting for materials" status

This enables fully automated experiment submission pipelines where payment is handled externally or the organization has pre-approved billing. Implies skip_draft: true.

skip_draft · boolean

Bypass Draft status and submit directly for processing.

When true, the experiment is created in "Waiting for confirmation" status instead of Draft, skipping the manual review step. Use this for automated pipelines with pre-validated payloads.

When an experiment is submitted with skip_draft: true and the target has existing inventory materials, those materials are automatically linked to expedite processing.

webhook_url · string | null

URL to which experiment status updates will be POSTed

Example:

"https://example.com/webhook"

Response

201

application/json

Experiment created

Response confirming experiment creation.

experiment_id · string · required

Unique identifier assigned to the new experiment

error · string | null

Error message when the request fails validation or processing

stripe_hosted_invoice_url · string | null

Stripe hosted invoice page. When the invoice is unpaid this is the checkout/payment page; after payment it becomes a receipt viewer.

stripe_invoice_id · string | null

Stripe invoice ID, present when auto_accept_quote created an invoice.