Skip to main content

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.

​
Integrator & Partner Guide

The Foundry API aims to make wetlab data requests as simple as a (somewhat slow) Modal call or DB query. We want all of our users to have access to this capability and their results data in all of their tools, and to make it easy for developers to build rich applications on top of our API, or enrich their existing apps with our lab capabilities.

​
How to integrate: BYOK flows only

The beauty of APIs vs. integrations is that they allow flexibility, for the providers, developers, and the users. To maintain this flexibility, and because wetlab work requires a tight feedback loop (see Service providers and reselling below), we require you to implement a Bring Your Own Key (BYOK) flow. This is a common pattern for AI model providers, where users choose which account(s) they want to link to your platform by pasting their scoped API keys. This means you must not “bundle” user orders under your own key — instead, the user should provide the token they received from the Foundry portal (or, if you are a partner who has onboarded them, the token you have minted for them).
Screenshot of a third-party settings page where the user pastes a scoped Adaptyv API key, illustrating the BYOK pattern.
Since the keys allow all the actions of their owner (modulo attenuation), for security purposes you must never store them as plain text. In descending order of priority and security, we recommend:
  1. Don’t store them at all — prompt the user for the key each session.
  2. Store them encrypted client-side.
  3. If you must persist them, store them encrypted server-side.
If you hold the keys for the users on your servers, we encourage you to attenuate tokens down to the minimal required permissions for the actions your integration performs.
You can send users to the Foundry token creation screen directly via https://foundry.adaptyvbio.com/request-token to streamline adding the token. To streamline even further, you can apply to our Partner Program.

​
Partner tokens

Screenshot of the Foundry portal showing the partner-token creation interface.
If you are accepted into our Partner Program, you gain the ability to create keys with the partner role. These keys allow you to call the partner-only routes — currently just one:
  • POST /api/v1/partners/mint-token — mint a user token for a customer.
    • With org.type: "new_org": bootstrap a new organization (when the customer’s email domain has no org on our platform yet) and create its first user.
    • With org.type: "existing_org": add a new user and mint their token inside an org you previously onboarded.
    • Users must be new — an existing email is rejected with 409. Tokens default to a 90-day expiry; pass expires_at to override.
Partner tokens should be kept safe and stored separately from your own API keys used for data access.
The mint-token action lets you create tokens for users that do not yet have any organization (as determined by their email domain) on our platform. You can also add users to organizations you have onboarded, or mint additional tokens for users that belong to those organizations. For customers you have not onboarded, you can request a token via https://foundry.adaptyvbio.com/request-token, which triggers a pre-filled version of our standard token creation flow. The user can then copy and paste the token into your platform as in any non-partner BYOK flow (see above).
Per the partner agreement, you may not use any of these tokens except on behalf of the user (for example, placing orders or accessing their data outside of providing them services). If you need service tokens for agents, you should attenuate existing user tokens appropriately.
For details on the partner-only API calls, fetch the OpenAPI spec while authenticating with your partner token: 
curl -H "Authorization: Bearer $PARTNER_TOKEN" \
  https://foundry-api-public.adaptyvbio.com/api/v1/openapi.json
The returned JSON will describe the partner-exclusive routes in more detail.

​
Service providers and reselling

We distinguish service providers and resellers based on who the end consumer of the data from our API is — both in terms of billing and in terms of who actually consumes the data. If you are running a campaign on behalf of a customer, and they never (want to) see the raw data but are only interested in the final IP, then you probably qualify as a service provider, especially if you have discretion over the budget of the campaign. If the customer retains day-to-day control over the budget (instead of, e.g., delegating you a lump sum) and/or wants to review the raw data themselves, then they are the actual data consumer and we would classify you as a reseller or distributor. For reselling and distribution, you must apply to the Partner Program and either manage your customers’ tokens for them or request that they give you access via their existing tokens. We need a direct relationship with the data consumer because, during an experiment, a lot can change. Due to the nature of biology, ordered sequences might not express, initial data might show that running more replicates to get exact KdK_d estimates is pointless, or additional runs might be required. We need to be able to communicate directly with the data users to sort these things out and to adjust the order and invoicing accordingly.
Even if you are a service provider under this definition, we strongly encourage applying to the Partner Program and provisioning keys for your customers. It makes it much easier for us to respond to any follow-up questions the customers might have, and it makes it easier for you to manage the blast radius of any integration you build.

​
Which bucket are you in?

​
Next steps

Foundry API

REST endpoints, authentication, and the experiment lifecycle.

MCP Server

Drive the same endpoints from Claude, Cursor, or any MCP-aware client.

Apply to the Partner Program

Mint tokens for your customers and unlock partner-only routes.

Foundry Portal

Create and manage API tokens, organizations, and users.