> ## 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. # Who am I > Identify yourself from your API token. Returns the organizations your token can access — with the organization you are currently acting as marked `active: true` — along with your user id, the permissions your token grants, and when the token expires. This is a safe, read-only call: it does not create or change anything. Use it to look up your organization's name and id (needed by other endpoints) or to check what your token is allowed to do. ## OpenAPI ````yaml https://foundry-api-public.adaptyvbio.com/api/v1/openapi.json get /api/v1/whoami 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://foundry-api-public.adaptyvbio.com` | ## Support - **Email**: support@adaptyvbio.com - **Documentation**: [docs.adaptyvbio.com](https://docs.adaptyvbio.com) version: 0.0.2 servers: - url: https://foundry-api-public.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/whoami: get: tags: - whoami summary: Who am I description: >- Identify yourself from your API token. Returns the organizations your token can access — with the organization you are currently acting as marked `active: true` — along with your user id, the permissions your token grants, and when the token expires. This is a safe, read-only call: it does not create or change anything. Use it to look up your organization's name and id (needed by other endpoints) or to check what your token is allowed to do. operationId: whoami responses: '200': description: Caller identity and access summary content: application/json: schema: $ref: '#/components/schemas/WhoAmIResponse' '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: WhoAmIResponse: type: object description: Identity and access summary for the calling token. required: - organizations - permissions properties: active_organization_id: type: - string - 'null' format: uuid description: >- Identifier of the organization the token is currently acting as. This is the organization flagged `active: true` in `organizations`. example: 019b8da3-4a91-16c6-fa94-619212bee6a6 organizations: type: array items: $ref: '#/components/schemas/WhoAmIOrganization' description: |- Every organization the token can access. For most tokens this is a single organization; exactly one entry is flagged `active`. permissions: type: array items: type: string description: >- The permissions this token grants, as `resource:action` strings (for example `experiment:create`). Use these to learn what the token can do before attempting an operation. example: - organization:read - experiment:read - experiment:create token_expires_at: type: - string - 'null' format: date-time description: |- When the token expires (ISO 8601 / RFC 3339, UTC). `null` for tokens without a recorded expiry. example: '2026-12-31T23:59:59Z' user_id: type: - string - 'null' format: uuid description: The authenticated user's unique identifier. example: 019b8da3-1111-2222-3333-444455556666 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 WhoAmIOrganization: type: object description: One organization the caller's token can access. required: - id - name - active properties: active: type: boolean description: >- `true` for the organization this token is currently acting as (the active context); `false` for the other organizations it can also access. example: true id: type: string format: uuid description: |- Unique identifier for the organization. Use this value as the `organization_id` in other API calls. example: 019b8da3-4a91-16c6-fa94-619212bee6a6 name: type: string description: Organization display name. example: Acme Biotech role: type: - string - 'null' description: |- The caller's role in this organization (e.g. `member`, `viewer`, `billing`). example: member 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. ````