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

# Working with Reactions

Beta: every reaction endpoint needs `EARLY-ACCESS: true`.

The Reactions API is **read and archive only**. You can list, fetch, and archive or restore reactions, but you can't create them or edit their chemistry through the API.

Reactions are created and edited inside Benchling, from a notebook entry's **stoichiometry table**. There's intentionally no create endpoint, and a reaction's `name`, `components`, and `folder` can't be changed through the API. Only its archive state can.

## Endpoints

| Operation                              | Endpoint                                    | Notes                                                                                                                  |
| -------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Get one                                | `GET /reaction/{reaction_id}`               |                                                                                                                        |
| List                                   | `GET /reaction/items`                       |                                                                                                                        |
| List a reaction's authors              | `GET /reaction/{reaction_id}/authors/items` |                                                                                                                        |
| Archive / restore one                  | `PATCH /reaction/{reaction_id}`             | Only `archived` and `archiveReason` are settable                                                                       |
| Archive / restore a handful (up to 25) | `PATCH /reaction:batch-update`              | All-or-nothing                                                                                                         |
| Archive / restore many                 | `PATCH /reaction:bulk-update`               | File-based and async, the same flow as [bulk molecule creation](/docs/working-with-molecules#using-the-bulk-endpoints) |

## What a reaction contains

A reaction links the notebook `entry` it came from and carries its stoichiometry as a list of `components`. Each component is a **Reactant**, **Product**, or **Standard**, and exposes:

* `role`: one of `REACTANT`, `PRODUCT`, `REAGENT`, `BYPRODUCT`, `SOLVENT`, or `CATALYST`.
* `linkedMolecule`: the [molecule](/docs/working-with-molecules) playing that role. A molecule linked to a reaction can't have its [structure edited](/docs/working-with-molecules#why-cant-i-change-a-molecules-structure).
* Stoichiometry: `molEquivalent`, `molPlan` / `molActual`, `amountPlan` / `amountActual` (with units), `purity`, `concentration`, and `calculationBase`.
* Products also carry `amountYield`; reactants also carry `isLimitingReactant`.

> **Warning**
>
> **Numeric stoichiometry values come back as strings.** High-precision fields like `molEquivalent`, `purity`, `concentration`, and `amountYield` are serialized as JSON strings (for example, `"1.5"`, not `1.5`). This preserves significant digits: a value like `6.00` keeps its trailing zeroes, which a JSON number cannot. Parse them as decimals, not floats, and don't rely on native JSON number handling.