> 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 the Salt & Solvate Library

Beta: every salt and solvent endpoint needs `EARLY-ACCESS: true`.

The library holds the salt and solvent **counterparts** that Forms reference (see the [concept model](/docs/introduction-to-chemistry#concept-model)). It's a tenant-wide, admin-managed catalog: you populate it once, and Forms then point at its entries by structure.

> **Warning**
>
> **The app shows one merged "Salt & Solvate" library; the API exposes two separate resources.** In the Benchling app the library is a single flat list with no salt-vs-solvate distinction. On the API, salts and solvents are **distinct resources**: `/salt` (IDs `slt_...`) and `/solvent` (IDs `slvt_...`), each with its own endpoints. Note that the API noun is `solvent`, while the product term is **"Solvate"**.

## Endpoints

Salts and solvents mirror each other exactly. Swap `salt`/`slt_` for `solvent`/`slvt_`:

| Operation                  | Salt endpoint             | Solvent endpoint              |
| -------------------------- | ------------------------- | ----------------------------- |
| Create one                 | `POST /salt`              | `POST /solvent`               |
| Get one                    | `GET /salt/{salt_id}`     | `GET /solvent/{solvent_id}`   |
| List                       | `GET /salt/items`         | `GET /solvent/items`          |
| Update / archive           | `PATCH /salt/{salt_id}`   | `PATCH /solvent/{solvent_id}` |
| Create a handful (up to 4) | `POST /salt:batch-create` | `POST /solvent:batch-create`  |
| Create many (async)        | `POST /salt:bulk-create`  | `POST /solvent:bulk-create`   |

`:batch-update` and `:bulk-update` also exist for both. The bulk endpoints follow the same file-based flow as [bulk molecule creation](/docs/working-with-molecules#using-the-bulk-endpoints).

## Fields

A salt or solvent is a small object: a name, a structure, and an optional code.

| Field    | Notes                                                                                                                                   |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | Required. Unique (case-insensitive) **within its own library**. A solvent may reuse a salt's name.                                      |
| `smiles` | Required. SMILES of the **neutral form**; the canonical SMILES and molecular formula are derived from it. **Immutable after creation.** |
| `code`   | Optional short identifier (for example, `"HCl"`). Unique (case-insensitive) **across all salts *and* solvents** in the tenant.          |

A minimal create body is just `{ "name": "Hydrochloride", "smiles": "Cl", "code": "HCl" }`, sent with the standard auth and the `EARLY-ACCESS: true` header (see [Getting started](/docs/introduction-to-chemistry#getting-started)).

Update is limited to `name`, `code`, and archive state. The structure can't change. To "edit" a structure, archive the entry and create a new one.

## Limits and rules

* **Tenant admin permissions** are required to create or update entries.
* The **combined** salt and solvent library is capped at **2000 non-archived entries**, and each structure is limited to **50 atoms**.
* Within a library, each **structure may appear only once**. A solvent may reuse a salt's structure, and vice versa.
* **Archived entries still reserve their name and structure.** If a match is archived, unarchive it; you can't recreate it.