Adaptyv Bio Foundry API

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 侧边栏获取。

编写代码时，始终从环境变量 ADAPTYV_API_KEY 或从 .env 文件读取 API 密钥 — 永远不要硬编码令牌。首先检查项目根目录是否有 .env 文件；如果存在，使用 python-dotenv 等库加载它。

官方 API 文档 在 curl 示例中使用 FOUNDRY_API_TOKEN；这是同一个 bearer 令牌 — 在 Python 和新的 shell 脚本中优先使用 ADAPTYV_API_KEY 以保持与 SDK 的一致性。

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"

环境变量（在 shell 或 .env 文件中设置）：

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

@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",
    ),
)

# 浏览靶点
targets = client.targets.list(search="EGFR", selfservice_only=True)

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

# 创建并提交
exp = client.experiments.create({...})
client.experiments.submit(exp.experiment_id)

# 稍后：获取结果
results = client.experiments.get_results(exp.experiment_id)

实验类型

| 类型 | 方法 | 测量 | 需要靶点 |

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

| affinity | bli 或 spr | KD、kon、koff 动力学 | 是 |

| screening | bli 或 spr | 是/否 结合 | 是 |

| thermostability | — | 熔解温度 (Tm) | 否 |

| expression | — | 表达产量 | 否 |

| fluorescence | — | 荧光强度 | 否 |

实验生命周期

草稿 → 等待确认 → 报价已发送 → 等待材料 → 排队中 → 生产中 → 数据分析 → 审核中 → 完成

| 状态 | 行动方 | 描述 |

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

| 草稿 | 您 | 可编辑，无成本承诺 |

| 等待确认 | Adaptyv | 审核中，正在准备报价 |

| 报价已发送 | 您 | 审核并确认报价 |

| 等待材料 | Adaptyv | 已订购基因片段和靶点 |

| 排队中 | Adaptyv | 材料已到达，排队等待实验 |

| 生产中 | Adaptyv | 实验运行中 |

| 数据分析 | Adaptyv | 原始数据处理和质量控制 |

| 审核中 | Adaptyv | 最终验证 |

| 完成 | 您 | 结果可用 |

| 已取消 | 任意 | 实验已取消 |

实验上的 results_status 字段跟踪：none、partial 或 all。

常见工作流程

1. 提交结合筛选（分步）

# 1. 查找靶点
targets = client.targets.list(search="EGFR", selfservice_only=True)
target_id = targets.items[0].id

# 2. 预览成本
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. 创建实验（开始为草稿）
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. 提交审核
client.experiments.submit(exp.experiment_id)

# 5. 轮询或使用 Webhook 直到完成
# 6. 获取结果
results = client.experiments.get_results(exp.experiment_id)

2. 自动化流水线（跳过草稿 + 自动接受报价）

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 在每个状态转换时触发；轮询或等待完成

3. 使用 Webhook

创建实验时传递 webhook_url。Adaptyv 在每个状态转换时向该 URL 发送 POST 请求，包含实验 ID、之前的状态和新状态。

序列

• 简单格式：{"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（不区分大小写，存储为大写）
• 序列只能在 草稿 状态的实验中添加到实验

过滤、排序和分页

所有列表端点支持分页（limit 1-100，默认 50；offset）、搜索（名称字段上的自由文本）和排序。

过滤 通过 filter 查询参数使用 s-expression 语法：

• 比较：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)
• 空值：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": "人类可读的描述",
  "request_id": "req_019462a4-b1c2-7def-8901-23456789abcd"
}

request_id 也在 x-request-id 响应头中 — 联系支持时请包含它。

令牌管理

令牌使用基于 Biscuit 的加密衰减。您可以通过 POST /tokens/attenuate 创建受限制的作用域令牌，按组织、资源类型、操作（读/创建/更新）和到期时间进行作用域划分。撤销令牌（POST /tokens/revoke）会撤销它及其所有衍生令牌。

详细 API 参考

要获取所有 32 个端点及其请求/响应模式的完整列表，请阅读 references/api-endpoints.md。