Skip to navigation
Chemistry

Introduction to Chemistry

Create and register molecules, manage the Salt & Solvate Library, and read reactions through the V3 REST API.

The Chemistry endpoints are part of the V3 REST API. 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.

AreaStatusHeader needed
Molecules & Molecule SchemasGA (stable)None
Salt & Solvate LibraryBetaEARLY-ACCESS: true
Attaching salt/solvate counterparts on createGA (with salt-form feature enabled)None
Auto-creating the parent Compound (:bulk-create-molecules-with-parent)BetaEARLY-ACCESS: true
Reactions (read & archive)BetaEARLY-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.

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.
  • 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. 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.

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.)