> ## 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. # Get target > Returns the catalog record for a single target by UUID. Retrieves target details including vendor name, catalog number, and `pricing` where self-service pricing is available. **Pricing:** Targets with `pricing` support instant cost estimation via `/experiments/cost-estimate`. Targets without this field require a custom quote — contact support for pricing on these targets. Returns 404 if the target doesn't exist. ## OpenAPI ````yaml https://devs.adaptyvbio.com/api/v1/openapi.json get /api/v1/targets/{target_id} 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/targets/{target_id}: get: tags: - targets summary: Get target description: >- Returns the catalog record for a single target by UUID. Retrieves target details including vendor name, catalog number, and `pricing` where self-service pricing is available. **Pricing:** Targets with `pricing` support instant cost estimation via `/experiments/cost-estimate`. Targets without this field require a custom quote — contact support for pricing on these targets. Returns 404 if the target doesn't exist. operationId: get_target_info parameters: - name: target_id in: path description: Unique identifier of the target to retrieve required: true schema: type: string format: uuid responses: '200': description: Target details retrieved content: application/json: schema: $ref: '#/components/schemas/TargetInfo' '400': description: Invalid target_id format (not a UUID) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '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' '404': description: Target not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: TargetInfo: type: object description: |- Target catalog entry. Used by both list and detail endpoints. The list endpoint returns this with `details` omitted (or populated when `?detailed=true`). The detail endpoint always populates `details`. required: - id - name - vendor_name - catalog_number - url properties: catalog_number: type: string description: Vendor's catalog/SKU number details: oneOf: - type: 'null' - $ref: '#/components/schemas/TargetDetails' description: >- Detailed target data. Populated on the detail endpoint and on the list endpoint when `?detailed=true` is passed. id: type: string format: uuid description: Unique identifier for the target from the catalog name: type: string description: Product name of the target antigen pricing: oneOf: - type: 'null' - $ref: '#/components/schemas/TargetPricing' description: >- Material pricing for this target, if self-service pricing is available. When absent, this target requires a custom quote. The `type` field discriminates the pricing model: - `per_sequence`: fixed cost per sequence - `per_broken_lot`: customer pays for the full vendor lot uniprot_id: type: - string - 'null' description: |- UniProt accession for the primary protein component. Present on ~82% of targets; viral/non-standard proteins lack this (they have `details.ncbi_id` instead). example: Q15116 url: type: string description: URL to view this target in the catalog web UI example: >- https://targets.adaptyvbio.com/protein/f3b2afd0-f70b-5191-a90a-ae1e0545c744 vendor_name: type: string description: Vendor/supplier name (e.g., "ACRO Biosystems") 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 TargetDetails: type: object description: |- Detailed target data populated on the detail endpoint and optionally on the list endpoint when `?detailed=true` is passed. properties: bioactivity: oneOf: - type: 'null' - $ref: '#/components/schemas/Bioactivity' description: >- Vendor bioactivity data availability. `None` means the vendor did not report bioactivity (distinct from all-false). description: type: - string - 'null' description: Vendor product description. expression_system: type: - string - 'null' description: Expression system used to produce the target (e.g., "HEK293"). example: HEK293 family: type: - string - 'null' description: Protein family classification (e.g., "Immunoglobulin superfamily"). example: Immunoglobulin superfamily gene_names: type: - array - 'null' items: type: string description: >- Gene names/symbols. First entry is canonical (e.g., ["PDCD1", "PD1"]). example: - PDCD1 - PD1 molecular_weight: type: - string - 'null' description: >- Raw molecular weight string from the vendor catalog (e.g., "23.1 kDa"). example: 23.1 kDa ncbi_id: type: - string - 'null' description: >- NCBI accession ID. Complementary to `uniprot_id` — mostly viral targets. example: NP_005009 organism: type: - string - 'null' description: Source organism (e.g., "Homo sapiens", "SARS-CoV-2"). example: Human purity: type: - number - 'null' format: double description: Purity percentage (0-100). Vendor-dependent, only ~20% of targets. example: 95 sequence: type: - string - 'null' description: Amino acid sequence of the target protein. sequence_length: type: - integer - 'null' format: int32 description: Amino acid count (avoids client-side counting of `sequence`). example: 288 structures: type: array items: $ref: '#/components/schemas/PdbEntry' description: |- PDB structures with download URLs. Each entry pairs a PDB ID with its RCSB download URL. example: - id: 5JDR url: https://files.rcsb.org/download/5JDR.pdb subcellular_locations: type: - array - 'null' items: type: string description: Known subcellular locations (e.g., ["Cell membrane", "Secreted"]). example: - Cell membrane synonyms: type: - array - 'null' items: type: string description: >- Alternative protein names (e.g., ["Programmed cell death protein 1", "CD279"]). tags: type: - array - 'null' items: type: string description: Purification/fusion tags on the product (e.g., ["His"], ["Fc"]). example: - His TargetPricing: oneOf: - type: object description: 'Per-sequence pricing: fixed cost per sequence.' required: - price_per_sequence_cents - type properties: price_per_sequence_cents: type: integer format: int64 description: Material cost per sequence in USD cents example: 500 type: type: string enum: - per_sequence - type: object description: >- Broken-lot pricing: customer pays for the full lot. Each tier represents a lot size and the number of sequences it can serve. The API consumer should select the smallest tier whose `num_sequences` is >= the experiment's sequence count. required: - lot_prices - type properties: lot_prices: type: array items: $ref: '#/components/schemas/LotPriceTier' description: Lot price tiers, sorted by num_sequences ascending type: type: string enum: - per_broken_lot description: >- Pricing information for a target's material costs. Determines how material costs are calculated for an experiment using this target. The variant reflects the pricing model configured in `foundry_api.product_prices`. Bioactivity: type: object description: |- Vendor bioactivity data availability for a target. Each boolean indicates whether the vendor provides binding data from that assay type. `None` for this field means the vendor did not report bioactivity for this product (distinct from all-false, which would mean tested but negative). required: - elisa - spr - bli properties: bli: type: boolean description: BLI (biolayer interferometry) data available from vendor elisa: type: boolean description: ELISA bioactivity data available from vendor spr: type: boolean description: SPR (surface plasmon resonance) data available from vendor PdbEntry: type: object description: A single PDB structure entry pairing an ID with its RCSB download URL. required: - id - url properties: id: type: string description: PDB ID from RCSB Protein Data Bank (e.g., "5JDR") example: 5JDR url: type: string description: Direct download URL for the PDB file example: https://files.rcsb.org/download/5JDR.pdb LotPriceTier: type: object description: >- A single lot-price tier within broken-lot pricing. Represents one vendor lot size, expressed in terms of how many sequences it can serve (derived from `max(1, floor(lot_size_ug / consumption_per_seq))`). required: - num_sequences - price_usdcent properties: num_sequences: type: integer format: int32 description: Maximum sequences this lot can serve example: 33 minimum: 0 price_usdcent: type: integer format: int64 description: Full lot price in USD cents example: 30000 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. ````