> ## Documentation Index > Fetch the complete documentation index at: https://docs.adaptyvbio.com/llms.txt > Use this file to discover all available pages before exploring further. # List results > Lists completed analysis results, sorted by creation date (newest first). Results appear when an experiment's `results_status` field reaches `Partial` or `All`. Paginate with `limit` (default 50) and `offset`; the response includes `total` for page calculation. Each result includes its full `summary` (kinetics for BLI, readouts for thermostability) and `metadata`, matching the detail endpoint shape. Supports filtering on result fields; invalid filter fields return 400. ## OpenAPI ````yaml https://devs.adaptyvbio.com/api/v1/openapi.json get /api/v1/results openapi: 3.1.0 info: title: Adaptyv Foundry API description: > The Foundry API enables programmatic access to Adaptyv Bio's protein characterization services. ## Getting Started 1. **Obtain an API token** from the [Adaptyv Portal](https://foundry.adaptyvbio.com) or by contacting Adaptyv directly 2. **Authenticate requests** using Bearer token in the Authorization header 3. **Create experiments** to submit protein sequences for characterization 4. **Monitor status** via webhooks or polling the experiment detail endpoint ## Authentication All requests require a Bearer token: ``` Authorization: Bearer ``` Tokens can be attenuated (restricted) to specific organizations or capabilities via the `/tokens` endpoint. ## Pagination List endpoints support offset-based pagination: | Parameter | Description | Default | |-----------|-------------|---------| | `limit` | Maximum items per page | 50 | | `offset` | Number of items to skip | 0 | ## Filtering Most list endpoints support filtering via query parameters using comparison operators: - `equ(field)=value` — equals - `geq(field)=value` — greater than or equal - `gtr(field)=value` — greater than - `leq(field)=value` — less than or equal - `lss(field)=value` — less than Example: `GET /experiments?geq(created_at)=2025-01-01&status=draft` ## Environments | Environment | Base URL | |-------------|----------| | Production | `https://devs.adaptyvbio.com` | ## Support - **Email**: support@adaptyvbio.com - **Documentation**: [docs.adaptyvbio.com](https://docs.adaptyvbio.com) version: 0.0.2 servers: - url: https://devs.adaptyvbio.com/ description: Production API (Public) security: - adaptyv_biscuits_v0: [] tags: - name: experiments description: > Experiments are the core resource for submitting protein sequences to Adaptyv's characterization services. ## Lifecycle Experiments progress through these stages: 1. **Draft** — Initial state for designing your experiment 2. **In Review** — Submitted for validation and quote generation 3. **Quote Sent** — Adaptyv has sent a pricing quote 4. **Waiting for Confirmation** — Quote ready, awaiting acceptance 5. **In Queue** — Confirmed and queued for lab scheduling 6. **Waiting for Materials** — Confirmed, waiting for samples 7. **In Production** — Lab work in progress 8. **Data Analysis** — Characterization complete, processing results 9. **Done** — Results available for download **Canceled** is a terminal state reachable from Draft, In Review, Waiting for Confirmation, or In Queue. ## Experiment Types | Type | Description | Target Required | |------|-------------|-----------------| | `screening` | High-throughput binding assessment | Yes | | `affinity` | Kinetic characterization (KD, kon, koff) | Yes | | `thermostability` | Thermal stability measurement (Tm) | No | | `expression` | Expression yield assessment | No | | `fluorescence` | Fluorescence-based characterization | No | ## Typical Workflow ``` POST /experiments # Create experiment POST /experiments/cost-estimate # Preview pricing POST /experiments/{id}/submit # Submit for review GET /experiments/{id}/quote # Retrieve quote when ready POST /experiments/{id}/quote/confirm # Accept quote GET /experiments/{id} # Monitor progress GET /results?experiment_id={id} # Retrieve results when done ``` ## Related Resources - [Results](#tag/results) — Characterization data from completed experiments - [Sequences](#tag/sequences) — Individual sequences within experiments - [Targets](#tag/targets) — Target proteins for binding experiments - name: feedback description: >- Use this endpoint to give us feedback, report bugs that are not already caught by our observability or request features (or have your agents do it). - name: info description: >- Programmatic discovery and health probes. Anonymous-eligible liveness and database connectivity probes; admin-only assay-type catalog (internal builds). - name: quotes description: >- Stripe quote lifecycle: list, retrieve, confirm, and reject quotes for experiment pricing. - name: results description: > Results contain the characterization data from completed experiments. ## Result Availability Results appear when an experiment reaches the **Done** status. Some experiment types provide partial results during **Data Analysis**. ## Result Types by Experiment | Experiment Type | Result Data | |-----------------|-------------| | Affinity | KD, kon, koff, sensorgrams | | Screening | Binding yes/no, response units | | Thermostability | Tm values, melting curves | | Expression | Yield measurements | ## Downloading Results Use the result `id` to fetch detailed data. Result downloads may include: - Raw sensorgram data - Fitted kinetic parameters - Quality metrics - Summary reports ## Related Resources - [Experiments](#tag/experiments) — Parent resource that produces results - name: sequences description: > Sequences provide read-only access to protein sequences submitted across experiments. ## Sequence Format Sequences are amino acid strings in standard single-letter IUPAC format (e.g., `MKTLLLTLLV...`). ## Sequence Properties | Field | Description | |-------|-------------| | `aa_string` | The amino acid sequence | | `name` | Optional human-readable identifier | | `control` | Whether this is a control sequence | | `metadata` | Structural annotations (tag location, antibody type) | ## Querying Sequences Filter sequences by experiment or other criteria: ``` GET /sequences?experiment_id={id} GET /sequences?name=mAb-001 ``` ## Related Resources - [Experiments](#tag/experiments) — Parent resource containing sequences - name: targets description: > Targets represent the molecules your samples will be tested against in binding experiments (affinity and screening). ## Target Catalog Adaptyv maintains a catalog of pre-validated target proteins with established pricing. Use `selfservice_only=true` to filter for targets with immediate pricing availability. ## Self-Service vs Custom Targets | Category | Description | Pricing | |----------|-------------|---------| | Self-service | Pre-validated catalog targets | Instant quote via cost estimate | | Custom | User-supplied or special request | Requires manual quote | ## Usage 1. Browse targets with `GET /targets?selfservice_only=true` 2. Use the target's `id` when creating an experiment 3. For custom targets, provide a `requested_target` object in the experiment request ## Related Resources - [Experiments](#tag/experiments) — Create experiments using targets - [Cost Estimate](#operation/cost_estimate) — Preview pricing for self-service targets - name: tokens description: > Create restricted versions of your API token for delegation to team members or automated systems. ## Token Attenuation Attenuation **reduces** the permissions of your token—it cannot grant additional access. Attenuated tokens inherit a subset of the parent token's capabilities. ## Restriction Types | Restriction | Effect | |-------------|--------| | Organization | Limit access to specific organizations | | Resource | Limit to specific resource types (experiments, results) | | Action | Limit to specific actions (read, create, update) | | Expiry | Set a shorter expiration time | ## Security Best Practices - Create narrowly-scoped tokens for automated systems - Use short expiration times for temporary access - Revoke tokens promptly when no longer needed - name: updates description: >- Real-time feed of experiment status changes, progress notifications, and operational alerts. Supports cursor-based pagination for efficient polling. - name: whoami description: >- Identify yourself: the organizations your token can access (with the active one marked), your user id, the permissions your token grants, and its expiry. paths: /api/v1/results: get: tags: - results summary: List results description: >- Lists completed analysis results, sorted by creation date (newest first). Results appear when an experiment's `results_status` field reaches `Partial` or `All`. Paginate with `limit` (default 50) and `offset`; the response includes `total` for page calculation. Each result includes its full `summary` (kinetics for BLI, readouts for thermostability) and `metadata`, matching the detail endpoint shape. Supports filtering on result fields; invalid filter fields return 400. operationId: list_results parameters: - name: limit in: query description: Maximum number of items to return (1-100, default 50). required: false schema: type: integer format: int64 - name: offset in: query description: Number of items to skip (default 0). required: false schema: type: integer format: int64 - name: filter in: query description: >- Filter expression in s-expression syntax. **Comparison:** `eq(field,value)`, `neq(field,value)`, `gt(field,value)`, `lt(field,value)`, `gte(field,value)`, `lte(field,value)`, `contains(field,substring)` **Range/set:** `between(field,lo,hi)`, `in(field,v1,v2,...)` **Logical:** `and(expr1,expr2,...)`, `or(expr1,expr2,...)`, `not(expr)` **Null checks:** `is_null(field)`, `is_not_null(field)` **JSONB access:** `at(field,key)` — e.g. `eq(at(metadata,score),42)` **Cast functions:** `float(expr)`, `int(expr)`, `text(expr)`, `timestamp(expr)`, `date(expr)` Example: `and(gte(created_at,2026-01-01),eq(status,draft))` required: false schema: type: string - name: search in: query description: Free-text search term applied to searchable columns. required: false schema: type: string - name: sort in: query description: >- Sort expression. Supports multi-column sort (comma-separated, up to 8), JSONB path access, and type casts. Three accepted surface forms produce the same ordering: - **Canonical** — `desc(field)` / `asc(field)`; also wraps casts and `at(...)` JSONB path access. Example: `asc(date(at(metadata,start_date)))`. - **Prefix short form** — `-field` (descending), `+field` or bare `field` (ascending). GitHub / Stripe / Jira convention. Bare field only; no casts. - **Suffix short form** — `field:asc` / `field:desc`. Also bare field. Examples: `-created_at`, `-created_at,+name`, `created_at:desc`, `desc(created_at),asc(name)`, `asc(at(metadata,score))`. required: false schema: type: string responses: '200': description: Result list content: application/json: schema: type: object description: >- Paginated list response with offset-based navigation metadata. All list endpoints return this shape. Use `offset` and `limit` query parameters to page through results; `total` reports how many items match the query across all pages. required: - items - total - count - offset properties: count: type: integer format: int64 description: Number of items in this response. items: type: array items: type: object description: >- A completed experiment result: its summarized measurements and a link to the raw data. required: - id - title - experiment_id - result_type - created_at - summary - metadata properties: created_at: type: string format: date-time description: When this result was generated (ISO 8601). data_package_url: type: - string - 'null' description: >- Download URL for the raw data package, the same one available in the Foundry portal. Omitted when no package is available. experiment_id: type: string format: uuid description: Identifier of the experiment this result belongs to. id: type: string format: uuid description: Identifier for this result. metadata: type: object description: Additional metadata beyond the summary. result_type: type: string description: >- Assay type for this result (e.g. "affinity", "thermostability"). summary: type: array items: $ref: '#/components/schemas/ResultSummary' description: Per-readout measurements, each tagged by assay type. title: type: string description: Human-readable title for this result. description: The page of results. offset: type: integer format: int64 description: >- Offset used for this page (mirrors the `offset` query parameter). total: type: integer format: int64 description: >- Total number of items matching the query (across all pages). '401': description: Invalid or missing authentication token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: ResultSummary: oneOf: - allOf: - $ref: '#/components/schemas/AffinityResult' description: Binding kinetics from an affinity assay. - type: object required: - result_type properties: result_type: type: string enum: - affinity description: Binding kinetics from an affinity assay. - allOf: - $ref: '#/components/schemas/ThermostabilityResult' description: Melting-temperature readout from a nanoDSF assay. - type: object required: - result_type properties: result_type: type: string enum: - thermostability description: Melting-temperature readout from a nanoDSF assay. description: |- A result readout, tagged by assay type. The `result_type` field selects the variant: `affinity` for binding kinetics, `thermostability` for melting-temperature readouts. ErrorResponse: type: object description: >- Error response body returned by all endpoints on 4xx/5xx failures. Every error response contains a human-readable message and the request ID for support correlation. The `request_id` is also returned in the `x-request-id` response header. required: - error - request_id properties: error: type: string description: Human-readable error description. example: experiment not found request_id: type: string description: >- Request identifier for support correlation (also in `x-request-id` header). example: req_019462a4-b1c2-7def-8901-23456789abcd AffinityResult: type: object description: |- Aggregated binding results for a single antibody–antigen pair. Reports mean kinetics (KD, kon, koff) across the replicates alongside an overall binding call and the individual per-replicate measurements. required: - sequence - kd_units - binding_strength - positive_control - performance - replicates properties: binding: type: - string - 'null' description: >- Overall binding outcome, rolled up from the replicates ("true", "false", "unknown", "in_progress"). binding_model: type: - array - 'null' items: type: string description: >- The selected binding model(s), e.g. `["standard"]`, `["bivalent_analyte"]`, `["conformational"]`. Populated only for results carrying the v1 payload. example: - standard binding_strength: type: string description: |- Overall binding call, rolled up from the replicates (e.g. "strong", "medium", "weak", "none", "unknown"). concentration_display: type: - string - 'null' description: >- Expression concentration for display, in nM (e.g. "12.3", "<5.0", ">100"). concentration_value: type: - number - 'null' format: double description: >- Expression concentration as a number, in nM, when a point estimate is available. expression: type: - string - 'null' description: Expression level for the construct (e.g. "high", "medium", "low"). fit_quality: type: - string - 'null' description: Overall fit quality, one of "good" / "medium" / "poor". example: good kd_app: oneOf: - type: 'null' - $ref: '#/components/schemas/KineticInterval' description: >- Apparent KD (M), comparable across binding models, with its 95% CI. kd_log_std: type: - number - 'null' format: double description: Log-scale standard deviation of KD across the replicates. kd_mean: type: - number - 'null' format: double description: |- Mean equilibrium dissociation constant (M), averaged across the strong-binding replicates. kd_units: type: string description: Unit for the KD values; always molar (M). koff_1to1: oneOf: - type: 'null' - $ref: '#/components/schemas/KineticInterval' description: >- Dissociation rate (s⁻¹) from the 1:1 (standard) model, with its 95% CI. koff_log_std: type: - number - 'null' format: double description: Log-scale standard deviation of koff across the replicates. koff_mean: type: - number - 'null' format: double description: Mean dissociation rate constant (s⁻¹) across the replicates. kon_1to1: oneOf: - type: 'null' - $ref: '#/components/schemas/KineticInterval' description: >- Association rate (M⁻¹s⁻¹) from the 1:1 (standard) model, with its 95% CI. kon_log_std: type: - number - 'null' format: double description: Log-scale standard deviation of kon across the replicates. kon_mean: type: - number - 'null' format: double description: Mean association rate constant (M⁻¹s⁻¹) across the replicates. method: type: - array - 'null' items: type: string description: >- Distinct fitting models used across the replicates (e.g. ["1:1", "2:1"]). performance: type: object description: >- How this result compares to each of the experiment's positive controls, keyed by control name. Each value is "better", "worse", or null when the comparison is indeterminate. additionalProperties: type: - string - 'null' propertyNames: type: string example: Positive Control: better place: type: - integer - 'null' format: int64 description: Rank of this result within its experiment. positive_control: type: boolean description: Whether this result is a positive control. replicates: type: array items: $ref: '#/components/schemas/AffinityReplicate' description: The individual replicate measurements behind these aggregates. rmse_max_signal_pct: type: - number - 'null' format: double description: >- RMSE divided by the maximum measured signal, expressed as a percentage. example: 1.2 sequence: $ref: '#/components/schemas/SequenceEntry' description: The antibody sequence that was evaluated. target: oneOf: - type: 'null' - $ref: '#/components/schemas/TargetReference' description: >- The experiment's resolved target — display name plus, for catalog targets, the `target_catalog_id` to fetch full details via `GET /targets/{target_catalog_id}`. Absent when the experiment records no target (e.g. a custom target with no catalog match). ThermostabilityResult: type: object description: >- A thermostability readout for a single sample, measured by nanoDSF. `tm` is the melting temperature derived from the 350nm/330nm fluorescence ratio; `onset_pts_for_ratio` and `inflection_pts_for_ratio` give the onset and inflection temperatures of each unfolding transition. required: - sequence_id - onset_pts_for_ratio - inflection_pts_for_ratio properties: bli_result_id: type: - string - 'null' format: uuid description: >- Identifier of the binding result for the same sample, when the experiment also ran a binding assay. inflection_pts_for_ratio: type: array items: type: number format: double description: >- Inflection temperature (°C) of each unfolding transition, from the ratio curve. initial_330nm: type: - number - 'null' format: double description: Initial raw fluorescence at 330nm. onset_pts_for_ratio: type: array items: type: number format: double description: >- Onset temperature (°C) of each unfolding transition, from the ratio curve. sequence: type: - string - 'null' description: Protein sequence for this readout. sequence_id: type: string format: uuid description: Identifier for this readout. sequence_name: type: - string - 'null' description: Sample or construct name for this readout. tm: type: - number - 'null' format: double description: Melting temperature (°C), from the 350nm/330nm fluorescence ratio. KineticInterval: type: object description: >- A kinetic point estimate together with its 95% confidence interval. `ci_low` / `ci_high` are absent when the fit did not yield finite bounds. required: - value properties: ci_high: type: - number - 'null' format: double description: Upper bound of the 95% confidence interval. ci_low: type: - number - 'null' format: double description: Lower bound of the 95% confidence interval. value: type: number format: double description: Point estimate. AffinityReplicate: type: object description: >- One replicate of a binding-kinetics measurement for an antibody–antigen pair. An affinity result aggregates one or more replicates; each carries its own fitted kinetics and the model used to fit them. required: - replicate properties: binding: type: - string - 'null' description: |- Categorical binding outcome for this replicate ("true", "false", "unknown", "in_progress"). binding_strength: type: - string - 'null' description: >- Qualitative binding call for this replicate (e.g. "strong", "medium", "weak", "none", "in_progress"). confidence: type: - string - 'null' description: >- Confidence grade for the fit. Omitted when the binding call is unknown. expression: type: - string - 'null' description: |- Expression level for the construct in this replicate (e.g. "high", "medium", "low"). fit_quality: type: - string - 'null' description: Overall fit quality, one of "good" / "medium" / "poor". example: good kd: type: - number - 'null' format: double description: Equilibrium dissociation constant (M). Omitted when not measurable. kd_app: oneOf: - type: 'null' - $ref: '#/components/schemas/KineticInterval' description: >- Apparent KD (M), comparable across binding models, with its 95% CI. koff: type: - number - 'null' format: double description: Dissociation rate constant (s⁻¹). Omitted when not measurable. koff_1to1: oneOf: - type: 'null' - $ref: '#/components/schemas/KineticInterval' description: >- Dissociation rate (s⁻¹) from the 1:1 (standard) model, with its 95% CI. koff_method: type: - string - 'null' description: Fitting model used for the koff fit (e.g. "1:1", "2:1"). kon: type: - number - 'null' format: double description: Association rate constant (M⁻¹s⁻¹). Omitted when not measurable. kon_1to1: oneOf: - type: 'null' - $ref: '#/components/schemas/KineticInterval' description: >- Association rate (M⁻¹s⁻¹) from the 1:1 (standard) model, with its 95% CI. kon_method: type: - string - 'null' description: Fitting model used for the kon fit (e.g. "1:1", "2:1"). method: type: - string - 'null' description: Fitting model used for this replicate (e.g. "1:1", "2:1"). replicate: type: integer format: int64 description: Replicate number, starting at 1. rmse_max_signal_pct: type: - number - 'null' format: double description: >- RMSE divided by the maximum measured signal, expressed as a percentage. example: 1.2 SequenceEntry: type: object description: >- Represents a biological sequence to be tested in an experiment. Each sequence represents an antibody or protein to be tested in the experiment. # Example ```json { "name": "mAb1", "aa_string": "EVQLVESGGGLVQPGGSLRLSCAASGFTFS...", "control": false } ``` required: - aa_string properties: aa_string: $ref: '#/components/schemas/AAString' description: >- Protein/peptide sequence in standard single-letter amino acid format. Valid characters: A,C,D,E,F,G,H,I,K,L,M,N,P,Q,R,S,T,V,W,Y and colon for multichain. control: type: boolean description: Whether the sequence should be treated as a control well metadata: description: Arbitrary metadata supplied by the customer (tag locations, notes) name: type: - string - 'null' description: Optional name for the sequence (e.g., "mAb1", "scFv-001") example: mAb1 TargetReference: type: object description: >- A resolved reference to an experiment's target, as shown in the Foundry Portal. This is the single shape every API response uses to name a target: the experiment spec, result readouts, cost-estimate line items, and the internal minimum-sequence admin config all embed it instead of a bare id string. `name` is always present. `target_catalog_id` is present when the target is a catalog product — fetch its full details from `GET /targets/{target_catalog_id}`; its absence indicates a custom target. `sequence` and `supplier_url` are included when available. required: - name properties: name: type: string description: The target's display name, as shown in the Foundry Portal. example: Human PD-L1 sequence: type: - string - 'null' description: The target's amino-acid sequence, when available. supplier_url: type: - string - 'null' description: Link to the target's vendor product page, when available. target_catalog_id: type: - string - 'null' format: uuid description: >- Identifier of the matching catalog product, when the target is in the catalog; absent for custom targets. Resolve full details via `GET /targets/{target_catalog_id}`. example: 019a03da-b87f-7e15-8b02-cef171c9871d AAString: type: string description: >- A validated amino acid sequence string. Contains only the 20 natural amino acids (single-letter codes: A, C, D, E, F, G, H, I, K, L, M, N, P, Q, R, S, T, V, W, Y) and colons for multichain notation. Input is case-insensitive; stored uppercase. Multichain sequences use colon separators (e.g., `MVLS:EVQL` for a two-chain construct). Invalid characters or empty strings are rejected. example: EVQLVESGGGLVQPGGSLRLSCAAS securitySchemes: adaptyv_biscuits_v0: type: http scheme: bearer bearerFormat: Adaptyv Biscuits v0 description: >- Biscuit-based bearer token. Obtain tokens from the Adaptyv Portal or via the `/tokens` endpoint. Tokens encode organization membership and role-based capabilities; the API verifies the token's cryptographic signature and authorization claims before processing requests. Use `/tokens/attenuate` to create restricted tokens for delegation. ````