adaptyv – Coding skill for AI agents

Adaptyv Bio Foundry API

Use this skill to turn protein sequences into experimentally measured data through

Adaptyv's cloud laboratory. Confirm the target construct, assay conditions, controls,

and replicate plan before submitting a batch; turnaround depends on the experiment.

Reviewed against the deployed [OpenAPI schema](https://devs.adaptyvbio.com/api/v1/openapi.json)

(info.version: 0.0.2) and official SDK 0.1.0 at commit

cdf207819ed5a58e0c127453626d2bce125c8064. The schema version alone does not identify

all changes. See the [endpoint reference](references/api-endpoints.md) for current

request/response details and discrepancies in upstream examples.

Connect

Base URL: https://devs.adaptyvbio.com/api/v1. The schema is at

/openapi.json; never append that filename to normal endpoint requests.

Create a bearer token in [Foundry](https://foundry.adaptyvbio.com/) under

Organization → Settings → Tokens. Use Viewer for reads and Member for experiment

writes. Read credentials from ADAPTYV_API_KEY; the documentation's

FOUNDRY_API_TOKEN is an alternative variable name for the same token. If using a

project .env, explicitly call python-dotenv.load_dotenv() before SDK setup;

the SDK does not load that file automatically. Never print or commit tokens.

# ADAPTYV_API_KEY is already set in the environment.
curl --fail-with-body 'https://devs.adaptyvbio.com/api/v1/targets?limit=3' \
  -H "Authorization: Bearer $ADAPTYV_API_KEY"

Resource endpoints require bearer authentication. The schema and liveness endpoint

GET /info/health are public. GET /whoami reports the active organization and

permissions; check it when account scope is unclear.

Python SDK

Install the reviewed revision in your project environment (requires Python 3.11+):

uv pip install "git+https://github.com/adaptyvbio/adaptyv-sdk.git@cdf207819ed5a58e0c127453626d2bce125c8064"

Import from adaptyv, not adaptyv_sdk. FoundryClient requires explicit api_key

and base_url; the lab convenience object reads ADAPTYV_API_KEY and

ADAPTYV_API_URL. Set the latter to the base URL above to override the SDK's

older hostname default.

The following examples are illustrative for authenticated use. Their request

construction and parsing were checked with mocked HTTP responses, not a paid lab

run. Replace environment inputs with real, reviewed sequence data and catalog IDs.

Browse, estimate, create a draft

import json
import os
from pathlib import Path
from adaptyv import FoundryClient

client = FoundryClient(
    api_key=os.environ["ADAPTYV_API_KEY"],
    base_url="https://devs.adaptyvbio.com/api/v1",
)

# Review vendor, catalog number, construct, and pricing before selecting an ID.
targets = client.targets.list(search="EGFR", selfservice_only=True, detailed=True)
for target in targets.items:
    print(target.id, target.name, target.vendor_name, target.catalog_number)

# candidates.json is a map of unique names to full amino acid sequences.
sequences = json.loads(Path("candidates.json").read_text())
spec = {
    "experiment_type": "screening",
    "method": "bli",
    "target_id": os.environ["ADAPTYV_TARGET_ID"],
    "sequences": sequences,
    "n_replicates": 3,
}

# SDK takes the spec itself; REST takes {"experiment_spec": spec}.
estimate = client.experiments.cost_estimate(spec)
if estimate.breakdown is None:
    raise ValueError("Incomplete estimate: review warnings and obtain a full quote")
print("Estimated USD cents, excluding VAT:", estimate.breakdown.total_cents)

# After the batch and estimated cost have been reviewed:
exp = client.experiments.create(name="EGFR binder screen batch 1", experiment_spec=spec)
experiment_id = exp.experiment_id
client.close()

create(name=..., experiment_spec=...) does not accept a single REST-body dictionary.

cost_estimate(spec) wraps the spec itself; do not wrap it a second time.

For an affinity experiment, the SDK additionally requires explicit

antigen_concentrations, even though REST supplies a default when omitted.

Submit, then inspect and confirm the quote

With a configured client and the saved experiment_id:

client.experiments.submit(experiment_id)
# Quote generation is asynchronous. Retry get_quote with a bounded timeout if it
# returns 404 after successful submission; a draft has no forthcoming quote.
quote = client.experiments.get_quote(experiment_id)
print(quote.amount_total, quote.currency, quote.expires_at)

# Once the quote is accepted within the user's authorized scope:
accepted = client.experiments.confirm_quote(experiment_id)
print(accepted.invoice_id, accepted.hosted_invoice_url)

Confirmation creates/finalizes an invoice; it does not settle payment. Use the

returned hosted invoice URL or the current REST payment pointer. SDK 0.1.0 does

not expose invoice payment, organization webhooks, or whoami helpers.

Avoid the reviewed SDK's lab.experiment(target="EGFR") shortcut: it passes only

UUID-shaped targets and does not resolve a target name. auto_confirm=True and

lab.confirm_experiment() call submission, not the quote-confirm endpoint. Use

the explicit client methods above. The decorator also supplies method for

non-binding experiments, which the current API rejects.

Retrieve every result without losing fields

The SDK's generated models predate some live result fields and may discard them.

Use REST JSON when archiving results, target references, or newer kinetic fits:

import json
import os
from pathlib import Path
import httpx

experiment_id = os.environ["ADAPTYV_EXPERIMENT_ID"]
with httpx.Client(
    base_url="https://devs.adaptyvbio.com/api/v1",
    headers={"Authorization": f"Bearer {os.environ['ADAPTYV_API_KEY']}"},
    timeout=30,
) as api:
    response = api.get(f"/experiments/{experiment_id}")
    response.raise_for_status()
    experiment = response.json()
    if experiment["results_status"] != "all":
        raise RuntimeError("Results are not complete; inspect status before analysis")
    results, offset = [], 0
    while True:
        response = api.get(f"/experiments/{experiment_id}/results",
                           params={"limit": 100, "offset": offset})
        response.raise_for_status()
        page = response.json()
        results.extend(page["items"])
        offset += len(page["items"])
        if not page["items"] or offset >= page["total"]:
            break
Path("foundry-results.json").write_text(json.dumps(
    {"experiment": experiment, "results": results}, indent=2
))

Archive raw data packages when available, plus sequence/target identities, assay

method, units, conditions, replicate measurements and fit quality. Null kinetic

values are missing/unresolved measurements, not zero. A screening binding call is

not a measured affinity. Compare KD values only under compatible assay conditions;

the schema's kd_mean averages strong-binding replicates and is not an unbiased

summary of every tested replicate.

Experiment types and validation

| experiment_type | method | target_id | Sequence count | Replicates |

|---|---|---|---|---|

| affinity | Required: bli or spr | Required | At least 1 | Optional, 1–5; default 3 |

| screening | Required: bli or spr | Required | At least 1 | Optional, 1–5; default 3 |

| thermostability | Omit | Omit | At least 1 | Optional, 1–5; default 3 |

| expression | Omit | Omit | At least 1 | Optional, 1–5; default 3 |

| fluorescence | Omit | Omit | At least 1 | Optional, 1–5; default 3 |

| epitope_binning | Omit | Required | 4–28, multiple of 4 | Omit |

| enzyme_activity | Omit | Omit | At least 1 | Optional, 1–5; default 3 |

Inapplicable fields are rejected. antigen_concentrations is affinity-only, in nM;

REST's default is [1000.0, 316.2, 100.0, 31.6, 0.0]. parameters holds optional

assay settings; coordinate any nonstandard configuration with the laboratory.

Sequences accept full strings or rich entries such as

{"candidate": {"aa_string": "EVQLVESGGGLVQPGGSLRLSCAAS", "control": false}}.

Use the 20 standard amino acid letters; inputs are case-insensitive and stored

uppercase. Colons separate chains. Ellipses are not valid sequence characters.

Rich creation metadata is constrained by SequenceMetadata, not arbitrary JSON:

use SingleChain, ScFv, FAB, or IgG; ScFv needs VH and VL, FAB needs

framework_regions.ch and .cl. The SDK accepts the schema's Portal-style enum

values. Add sequences through POST /sequences only while status is draft.

Lifecycle and updates

Wire status values are lowercase snake case:

draft -> waiting_for_confirmation -> quote_sent -> waiting_for_materials
      -> in_queue -> in_production -> data_analysis -> in_review -> done

canceled is also possible. results_status is independently none, partial,

or all. Inspect it before treating a result set as complete. Most experiment

PATCH fields are editable in draft or in_review; `webhoo

… (full content is in the download package)