adaptyv

Adaptyv Bio Foundry API

Adaptyv Bio は、タンパク質配列を実験データに変換するクラウドラボです。ユーザーは API または UI からアミノ酸配列を送信します。Adaptyv の自動化ラボがアッセイ（結合、熱安定性、発現、蛍光）を実施し、約 21 日で結果をお届けします。

公式ドキュメント： docs.adaptyvbio.com/api-reference · llms.txt インデックス · OpenAPI 仕様

クイックスタート

ベース URL： https://foundry-api-public.adaptyvbio.com/api/v1

認証： Authorization ヘッダーに Bearer トークンを指定します。トークンは foundry.adaptyvbio.com のサイドバーから取得できます。

コードを記述する際は、API キーを必ず環境変数 ADAPTYV_API_KEY または .env ファイルから読み込んでください。トークンをハードコードしないでください。まずプロジェクトのルートに .env ファイルがあるか確認し、存在する場合は python-dotenv のようなライブラリを使って読み込みます。

公式 API ドキュメント の curl の例では FOUNDRY_API_TOKEN を使用していますが、これは同じ Bearer トークンです。SDK との一貫性を保つため、Python と新しいシェルスクリプトでは ADAPTYV_API_KEY を使用してください。

export ADAPTYV_API_KEY="abs0_..."
curl https://foundry-api-public.adaptyvbio.com/api/v1/targets?limit=3 \
  -H "Authorization: Bearer $ADAPTYV_API_KEY"

GET /openapi.json を除くすべてのリクエストには認証が必要です。トークンは環境変数または .env ファイルに保存し、ソース管理にコミットしないでください。

Python SDK

バージョンに関する注意： adaptyv-sdk 0.1.0（ベータ版）はまだ PyPI で公開されていません。GitHub からインストールしてください。

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

pyproject.toml があるプロジェクトでは、次のようにします。

uv add "adaptyv-sdk @ git+https://github.com/adaptyvbio/adaptyv-sdk.git"

環境変数（シェルまたは .env ファイルで設定）：

ADAPTYV_API_KEY=your_api_key
ADAPTYV_API_URL=https://foundry-api-public.adaptyvbio.com/api/v1
ADAPTYV_ORGANIZATION_ID=your_org_id  # optional

@lab.experiment デコレーターと FoundryClient は、明示的に渡されない場合、環境変数から ADAPTYV_API_KEY と ADAPTYV_API_URL を読み込みます。

デコレーターパターン

from adaptyv import lab

@lab.experiment(target="PD-L1", experiment_type="screening", method="bli")
def design_binders():
    return {"design_a": "MVKVGVNG...", "design_b": "MKVLVAG..."}

result = design_binders()
print(f"Experiment: {result.experiment_url}")

クライアントパターン

import os
from adaptyv import FoundryClient

client = FoundryClient(
    api_key=os.environ["ADAPTYV_API_KEY"],
    base_url=os.environ.get(
        "ADAPTYV_API_URL",
        "https://foundry-api-public.adaptyvbio.com/api/v1",
    ),
)

# Browse targets
targets = client.targets.list(search="EGFR", selfservice_only=True)

# Estimate cost
estimate = client.experiments.cost_estimate({
    "experiment_spec": {
        "experiment_type": "screening",
        "method": "bli",
        "target_id": "target-uuid",
        "sequences": {"seq1": "EVQLVESGGGLVQ..."},
        "n_replicates": 3
    }
})

# Create and submit
exp = client.experiments.create({...})
client.experiments.submit(exp.experiment_id)

# Later: retrieve results
results = client.experiments.get_results(exp.experiment_id)

実験の種類

種類	メソッド	測定項目	ターゲットが必要
affinity	bli または spr	KD、kon、koff の動態	はい
screening	bli または spr	結合の有無	はい
thermostability	—	融解温度（Tm）	いいえ
expression	—	発現収量	いいえ
fluorescence	—	蛍光強度	いいえ

実験のライフサイクル

Draft → WaitingForConfirmation → QuoteSent → WaitingForMaterials → InQueue → InProduction → DataAnalysis → InReview → Done

ステータス	実行者	説明
Draft	あなた	編集可能で、費用の確約はありません
WaitingForConfirmation	Adaptyv	審査中で、見積もりを準備しています
QuoteSent	あなた	見積もりを確認して承認します
WaitingForMaterials	Adaptyv	遺伝子フラグメントとターゲットを発注しています
InQueue	Adaptyv	資材が到着し、ラボの順番待ちです
InProduction	Adaptyv	アッセイを実施中です
DataAnalysis	Adaptyv	生データを処理し、QC を実施しています
InReview	Adaptyv	最終検証中です
Done	あなた	結果を利用できます
Canceled	いずれか	実験はキャンセルされました

実験の results_status フィールドは、none、partial、all のいずれかを示します。

よくあるワークフロー

1. 結合スクリーニングを送信する（手順）

# 1. Find a target
targets = client.targets.list(search="EGFR", selfservice_only=True)
target_id = targets.items[0].id

# 2. Preview cost
estimate = client.experiments.cost_estimate({
    "experiment_spec": {
        "experiment_type": "screening",
        "method": "bli",
        "target_id": target_id,
        "sequences": {"seq1": "EVQLVESGGGLVQ...", "seq2": "MKVLVAG..."},
        "n_replicates": 3
    }
})

# 3. Create experiment (starts as Draft)
exp = client.experiments.create({
    "name": "EGFR binder screen batch 1",
    "experiment_spec": {
        "experiment_type": "screening",
        "method": "bli",
        "target_id": target_id,
        "sequences": {"seq1": "EVQLVESGGGLVQ...", "seq2": "MKVLVAG..."},
        "n_replicates": 3
    }
})

# 4. Submit for review
client.experiments.submit(exp.experiment_id)

# 5. Poll or use webhooks until Done
# 6. Retrieve results
results = client.experiments.get_results(exp.experiment_id)

2. 自動パイプライン（Draft を省略し、見積もりを自動承認）

exp = client.experiments.create({
    "name": "Auto pipeline run",
    "experiment_spec": {...},
    "skip_draft": True,
    "auto_accept_quote": True,
    "webhook_url": "https://my-server.com/webhook"
})
# Webhook fires on each status transition; poll or wait for Done

3. Webhook を使用する

実験の作成時に webhook_url を渡します。Adaptyv はステータスが遷移するたびに、その URL に実験 ID、変更前のステータス、新しいステータスを含む POST リクエストを送信します。

配列

• シンプルな形式：{"seq1": "EVQLVESGGGLVQPGGSLRLSCAAS"}
• 詳細形式：{"seq1": {"aa_string": "EVQLVESGGGLVQ...", "control": false, "metadata": {"type": "scfv"}}}
• マルチチェーン：コロン区切りを使用します — "MVLS:EVQL"
• 有効なアミノ酸：A、C、D、E、F、G、H、I、K、L、M、N、P、Q、R、S、T、V、W、Y（大文字・小文字を区別せず、保存時は大文字）
• 配列を追加できるのは、Draft ステータスの実験のみです

フィルタリング、ソート、ページネーション

すべてのリストエンドポイントは、ページネーション（limit は1～100、デフォルトは50、offset）、検索（名前フィールドのフリーテキスト検索）、ソートに対応しています。

フィルタリングでは、filter クエリパラメーターを使ってS式構文を指定します。

• 比較：eq(field,value)、neq、gt、gte、lt、lte、contains(field,substring)
• 範囲／集合：between(field,lo,hi)、in(field,v1,v2,...)
• 論理：and(expr1,expr2,...)、or(...)、not(expr)
• Null：is_null(field)、is_not_null(field)
• JSONB：at(field,key) — 例：eq(at(metadata,score),42)
• キャスト：float()、int()、text()、timestamp()、date()

ソートでは、asc(field) または desc(field) を使い、カンマで区切って指定します（最大8件）。

sort=desc(created_at),asc(name)

例： filter=and(gte(created_at,2026-01-01),eq(status,done))

エラー処理

すべてのエラーは次の形式で返されます。

{
  "error": "Human-readable description",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

request_id は x-request-id レスポンスヘッダーにも含まれています。サポートに問い合わせる際は、この値を含めてください。

トークン管理

トークンでは、Biscuitベースの暗号学的な権限縮小を使用します。POST /tokens/attenuate を使うと、組織、リソースタイプ、アクション（read/create/update）、有効期限を指定して、制限付きトークンを作成できます。トークンを失効させる（POST /tokens/revoke）と、そのトークンとすべての子孫トークンが失効します。

APIリファレンスの詳細

リクエスト／レスポンスのスキーマを含む32個すべてのエンドポイントの一覧については、references/api-endpoints.md を参照してください。

エージェントの作業手順

1. 環境を確認します。 ツールキットのバージョンと入力形式（SMILES、SDF、PDB、CIF）を確認し、計算前に分子をサニタイズします。
2. 入力を明確にします。 データまたはユーザーから形式、識別子、パラメーターを確認します。結果を変える値については、推測せずに質問してください。
3. まず小規模な処理を実行します。 少数の分子または1つのターゲットを先に処理し、出力を確認します。
4. 上記の手順とリファレンスを使用して、タスク全体を実行します。
5. 結果を検証します。 構造の無効性、単位の一貫性、予測モデルの適用範囲を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の点を明記します。

このような場合	対応方法
分子の解析またはサニタイズに失敗する	理由を報告してスキップします。構造を黙って破棄したり変更したりしてはいけません。
これらの手順に記載された関数、フラグ、エンドポイントがインストール済みバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して対応し、ユーザーに伝えます。APIをでっち上げてはいけません。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計を捏造してはいけません。実行または検証できない場合は、その旨を明確に伝えます。
• 計算による予測は仮説であり、実験結果ではありません。そのように明記してください。
• ここに記載されたバージョン固有の情報は古くなっている可能性があります。インストール済みバージョンの公式ドキュメントと照合してください。
• 費用が発生する操作、共有GPUまたはクラウドクォータを消費する操作、個人データまたは患者データに触れる操作、取り消せない操作を行う前に、必ず確認してください。

関連するスキル

• tamarind：Tamarind Bioプラットフォーム上のオープンソース分子設計および構造生物学ツールのコレクションに、REST APIまたはMCPサーバー経由でアクセスします。…
• ginkgo-cloud-lab：自律型ラボ実行のためのウェブベースのインターフェース、Ginkgo Bioworks Cloud Lab（cloud.ginkgo.bio）でプロトコルを送信、管理します。…
• esm：EvolutionaryScale／Biohubの esm Python SDKを扱います。ESM3による生成タンパク質設計（配列、構造、機能のトラック、chain-of-tho…）