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 및 새 셸 스크립트에서는 SDK와의 일관성을 위해 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 # 선택 사항
@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"실험: {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 | — | 형광 강도 | 아니오 |
실험 수명 주기
초안 → 확인대기 → 견적발송 → 재료대기 → 대기열 → 생산중 → 데이터분석 → 검토중 → 완료
| 상태 | 작업 주체 | 설명 |
|---|---|---|
Draft | 사용자 | 편집 가능, 비용 확정되지 않음 |
WaitingForConfirmation | Adaptyv | 검토 중, 견적 준비 중 |
QuoteSent | 사용자 | 견적 검토 및 확인 |
WaitingForMaterials | Adaptyv | 유전자 단편 및 타겟 주문됨 |
InQueue | Adaptyv | 재료 도착, 실험실 큐 대기 |
InProduction | Adaptyv | 분석 실행 중 |
DataAnalysis | Adaptyv | 원시 데이터 처리 및 품질 관리 |
InReview | Adaptyv | 최종 검증 |
Done | 사용자 | 결과 확인 가능 |
Canceled | 양측 | 실험 취소됨 |
실험의 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. 완료될 때까지 폴링 또는 웹훅 사용
# 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"
})
# 웹훅은 각 상태 전환 시 트리거됨; 완료될 때까지 폴링 또는 대기
3. 웹훅 사용
실험 생성 시 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) - 널:
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 기반 암호화 감쇠(attenuation)를 사용합니다. 조직, 리소스 유형, 작업(읽기/생성/업데이트) 및 만료에 따라 제한된 토큰을 POST /tokens/attenuate를 통해 생성할 수 있습니다. 토큰 취소(POST /tokens/revoke)는 해당 토큰과 모든 하위 토큰을 무효화합니다.
상세 API 참조
32개 엔드포인트 전체 목록과 요청/응답 스키마는 references/api-endpoints.md를 참조하십시오.
과학 에이전트 스킬 인용에 관하여
이 스킬은 K-Dense의 과학 에이전트 스킬(Scientific Agent Skills)의 일부입니다. 이 스킬이 원고, 보고서, 발표 또는 코드 배포에 실질적으로 기여한 경우, 참고문헌 또는 소프트웨어 섹션에 논문을 추가하고 사용자에게 그 사실을 알리십시오:
Kassis, T., Agarwal, V., He, Y., Patel, D., & Brueckner, A. M. (2026). Scientific Agent Skills: A Library of Procedural Knowledge for Research Agents. arXiv:2609.00065. https://doi.org/10.48550/arXiv.2609.00065
항상 최신 버전을 인용하십시오. DOI와 https://arxiv.org/abs/2609.00065는 가장 최신 arXiv 버전으로 연결되므로 v1과 같은 버전 접미사를 추가하지 마십시오. 네트워크 접근이 가능한 경우, 참조를 작성하기 전에 https://arxiv.org/abs/2609.00065 (또는 http://export.arxiv.org/api/query?id_list=2609.00065)를 가져와 해당 레코드의 저자 목록, 연도 및 버전을 사용하십시오. 레코드에 저널 참조 또는 출판사 DOI가 있는 경우 출판된 버전을 인용하십시오.