> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Introduction to Chemistry

The Chemistry endpoints are part of the [V3 REST API](/docs/v3-api-overview). This page covers what's available, how stable each piece is, and how the pieces fit together. The rest of this section covers each area in depth.

| Area                                                                                                | Status                                  | Header needed        |
| --------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------- |
| [Molecules](/docs/working-with-molecules) & [Molecule Schemas](/docs/working-with-molecule-schemas) | **GA (stable)**                         | None                 |
| [Salt & Solvate Library](/docs/working-with-the-salt-and-solvate-library)                           | **Beta**                                | `EARLY-ACCESS: true` |
| Attaching salt/solvate counterparts on create                                                       | **GA** (with salt-form feature enabled) | None                 |
| Auto-creating the parent Compound (`:bulk-create-molecules-with-parent`)                            | **Beta**                                | `EARLY-ACCESS: true` |
| [Reactions](/docs/working-with-reactions) (read & archive)                                          | **Beta**                                | `EARLY-ACCESS: true` |

Beta endpoints are live on the same `/api/v3` surface but are still evolving. Expect possible changes, and don't build critical automation on them without checking in with us first. See the [V3 Stability Guidelines](/docs/stability-guidelines).

## Getting started

Everything you need before your first request:

* **Base URL:** `https://{tenant_name}.benchling.com` (replace `{tenant_name}` with your tenant name).
* **Auth:** HTTP Basic with your API key as the username and an empty password: `-u "$API_KEY:"`. OAuth client credentials also work; see [Authentication](/docs/authentication).
* **Beta access:** add the header `EARLY-ACCESS: true` on any beta endpoint (see the table above). GA endpoints need no header.
* **Tenant must have the feature enabled.** These are turned on by Benchling, not through the API. If a call returns a `400` or `404` saying the feature isn't available, ask your Benchling representative to enable **Molecules**, **salt & solvate forms**, or **stoichiometry / reactions** as applicable.

## Concept model

Everything in this section is a **Molecule**: a chemical structure. What a Molecule *does* in salt-form modeling depends on its **schema**. A Molecule schema can implement one of two schema interfaces that give the Molecule a role:

* **Compound**: a Molecule whose schema implements the Compound interface. This is the salt-free base structure. One Compound can be the parent of many Forms.
* **Form**: a Molecule whose schema implements the Form interface. This is the base structure together with one or more salt/solvent counterparts, each at a given ratio. Each Form links up to its Compound.

A Molecule whose schema implements neither interface is just a structure, with no salt-form behavior.

A **counterpart** is a salt or solvent, an entry in the [Salt & Solvate Library](/docs/working-with-the-salt-and-solvate-library). A Form references one or more counterparts and specifies a **ratio** for each (a fraction, such as `2/1` for a disodium salt) describing how much of that counterpart the form contains.

```
        Compound
     (salt-free base)
            ▲
            │ parent link
            │
          Form  ·······references·······▶  Salt & Solvate Library
   (base + counterparts)                    (salt / solvent counterparts)

   the Form sets a ratio for each counterpart it references (e.g. 2/1 = disodium)
```

The Form holds the links: a **parent link** up to its Compound, and a reference to each salt/solvent counterpart it contains.

> **Info**
>
> **Molecule Lots aren't part of this API yet.** A Molecule Lot is a physical sample of a molecule, carrying data like purity and concentration. It's a real chemistry object, but it isn't exposed as a dedicated object on the Chemistry V3 API at any stability level, so it's out of scope for this section. (Under the hood it's modeled as a generic custom entity.)