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

# REST API Reference

Use this page as the stable entry point to the reference material: the generated REST API docs, webhook schemas, and the supporting pages that explain authentication, delivery models, and API behavior. If you're building an event-driven workflow, branch from here into [Getting Started with EventBridge](/docs/events-getting-started) or [Getting Started with Webhooks](/docs/getting-started-with-webhooks).

> **Info**
>
> ### Where the generated reference lives
>
> Per-endpoint REST API documentation is generated from Benchling's OpenAPI spec and served on your tenant at `https://{tenant_name}.benchling.com/api/reference`. Use this page as the landing point for internal docs links, then pick the version and endpoint family you need.
>
> The V3 reference and its OpenAPI spec are also public and need no login: [V3 API reference](https://benchling.com/api/v3/reference) and [V3 OpenAPI specification](https://benchling.com/api/v3/openapi.yaml).

## Choose a version

| Version | When to use it                                                                                                                                                                                                          |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `v3`    | **Use this for new development.** Broader coverage than V2, plus batch writes, field selection, and typed filters. Served from `/api/v3`, with beta operations enabled per request via the `EARLY-ACCESS: true` header. |
| `v2`    | Use for the endpoints V3 does not cover yet, and for the Python SDK, which still targets V2. Fully supported and not being retired.                                                                                     |

Both versions accept the same token and can be called from the same integration. See [What's new in v3](/docs/v3-api-overview) for the V3 conventions, and [V3 Stability Guidelines](/docs/stability-guidelines) and [V2 Stability](/docs/stability) for what each version guarantees and what notice you get before a change.

> **Warning**
>
> ### The `v3-alpha` and `v3-beta` base paths are being retired
>
> If you have references to `/api/v3-alpha/` or `/api/v3-beta/`, migrate them to `/api/v3/`. The 90-day migration window that opened on June 15, 2026 closes in mid-September 2026.

## Common event-driven pattern

1. Receive a webhook or EventBridge delivery.
2. Identify the relevant resource ID from the payload.
3. Open the matching REST API version and endpoint family in the reference.
4. Fetch the current resource state before mutating data, syncing another system, or triggering follow-on work.

```bash
curl -u sk_YOUR_SECRET_KEY: \
  "https://your-tenant.benchling.com/api/v3/entry/etr_123456"
```

Step 4 matters because event payloads are point-in-time snapshots that can arrive late or out of order. See [Outdated event payloads](/docs/events-reference#eventbridge-payload-reference).

## Related docs

* [Authentication](/docs/authentication): how to authenticate the calls above
* [Getting Started with Webhooks](/docs/getting-started-with-webhooks)
* [Getting Started with EventBridge](/docs/events-getting-started)
* [Events Reference](/docs/events-reference)