AI Agents API | Benchling Documentation

The Agents API lets you interact with Benchling AI from your own applications. You send a prompt, Benchling runs an agent against your tenant’s data, and you retrieve the response, including any generated files.

Private beta

This API is in private beta and requires access to both the V3 REST API beta and the Benchling AI preview. Contact your account team to request access.

Beta operations are reached on the unified /api/v3 base path with the EARLY-ACCESS: true header. Without both the header and the features enabled on your tenant, these endpoints return 404. See the V3 Stability Guidelines.

How the Agents API works

It follows the same asynchronous task pattern as the other V3 async endpoints:

Send a prompt to POST /api/v3/agents. The response is a taskId and a pollingUri.
Poll GET /api/v3/tasks/agents/{task_id} for the task status.
Read the agent’s response from the same task endpoint once the status is COMPLETED.

Step 1: Send a prompt

POST /api/v3/agents creates a new chat or continues an existing one. The only required field is input.

input: an ordered list of message blocks. A text block is {"type": "text", "text": "…"}. A file block attaches a scratch file whose upload has succeeded.
chatId: an existing chat to append to. Omit it to start a new chat.
sources: data sources the agent may draw on beyond your tenant. {"type": "public_data"} enables public data; {"type": "mcp_server", "serverId": "mcpconf_…"} enables a configured MCP server. Ask your account team to turn public data on for your tenant if you want it.
connectors: {"mode": "all_connected"} enables every connector active for the calling user; {"mode": "none"} disables them. Omitting the field is equivalent to "none". Only valid when agent and sources are both omitted.
editingTarget: a Benchling object for the agent to edit through a new chat, such as {"type": "entry", "id": "etr_…"}. Not allowed together with agent or chatId.

POST /api/v3/agents
EARLY-ACCESS: true

Do not set `agent`

The agent field is deprecated. Omitting it routes your prompt through the default unified agent, which is the supported path going forward. The legacy identifiers benchling_deep_research_v1 and benchling_ask_v1 still work but are on their way out, and several newer fields, connectors and editingTarget, are unavailable when agent is set.

Step 2: Poll for task status

GET the pollingUri to check progress. status is NOT_STARTED, ACTIVE, COMPLETED, or FAILED.

Endpoint

GET /api/v3/tasks/agents/{task_id}
EARLY-ACCESS: true

Step 3: Retrieve the agent’s response

The same endpoint returns the response once the status is COMPLETED.

GET /api/v3/tasks/agents/atsk_1234
EARLY-ACCESS: true

content holds the agent’s answer as one or more blocks of text/markdown. chatId identifies the chat, and passing it back as chatId on a later POST /api/v3/agents continues the same conversation.

artifacts lists any images the agent generated. It is omitted while the task is in progress, when the response produced no images, and for files that are unavailable because antivirus scanning has not cleared them.

Artifact download URLs expire in 60 seconds

Each downloadUrl is a presigned URL valid for at most 60 seconds after it is generated. Download the file immediately, or request the task status again to get a fresh URL. Do not store these URLs.

Viewing responses in Benchling

Responses also appear in the Benchling UI under Benchling AI > Chat History, which is useful for confirming that a prompt behaved as you expected while you are building.

Chat History is not yet available through the API. API access to it is planned, along with support for additional Benchling agents.

Pricing

For the duration the beta, the Agents API is free for any customer and user with access to Benchling AI. Pricing for Benchling’s agentic AI tools will be announced ahead of general availability.