adaptyv

Files (2)

• SKILL.md
• api-endpoints.md · references/

SKILL.md (first lines)

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

```bash
# 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+):

```bash
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

```python
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`:

```python
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

From K-Dense-AI/scientific-agent-skills, MIT.

More from K-Dense-AI/scientific-agent-skills