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

# AI Agents API

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.

> **Warning**
>
> ### Private beta
>
> This API is in private beta and requires access to both the [V3 REST API](/docs/v3-api-overview) 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](/docs/stability-guidelines).

## How the Agents API works

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

1. Send a prompt to `POST /api/v3/agents`. The response is a `taskId` and a `pollingUri`.
2. Poll `GET /api/v3/tasks/agents/{task_id}` for the task status.
3. 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](/docs/bulk-import#step-2-upload-the-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`.

**`Endpoint`**

```text title="Endpoint"
POST /api/v3/agents
EARLY-ACCESS: true
```

**`Example Request`**

```json title="Example Request"
{
  "input": [
    { "type": "text", "text": "Write a summary of my recent entry: EXP24000012" }
  ],
  "sources": [
    { "type": "public_data" }
  ]
}
```

**`Example Response`**

```json title="Example Response"
{
  "taskId": "atsk_1234",
  "pollingUri": "https://{tenant_name}.benchling.com/api/v3/tasks/agents/atsk_1234"
}
```

**`curl`**

```bash title="curl"
curl -X POST "https://{tenant_name}.benchling.com/api/v3/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -H "EARLY-ACCESS: true" \
  -d '{
    "input": [
      { "type": "text", "text": "Write a summary of my recent entry: EXP24000012" }
    ],
    "sources": [
      { "type": "public_data" }
    ]
  }'
```

> **Note**
>
> ### 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`**

```text title="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`.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/tasks/agents/atsk_1234
EARLY-ACCESS: true
```

**`Example Response`**

```json title="Example Response"
{
  "taskId": "atsk_1234",
  "chatId": "chtsess_1234",
  "status": "COMPLETED",
  "content": [
    {
      "content_type": "text/markdown",
      "text": "\n# Summary of Entry EXP24000012\n..."
    }
  ],
  "artifacts": [
    {
      "type": "file",
      "id": "efl_1234",
      "filename": "result.png",
      "mediaType": "image/png",
      "downloadUrl": "https://example.s3.amazonaws.com/result.png?signature=..."
    }
  ]
}
```

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

> **Warning**
>
> ### 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.