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

# Create or continue a chat with an agent

POST https://{tenant_name}.benchling.com/api/v3/agents
Content-Type: application/json

Create or continue a chat with an agent

Reference: https://docs.benchling.com/docs/api/benchling-api/agent/create

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

### Body (application/json)

This endpoint expects an object.

- `input` (list of BaseCreateMessageBlockInput, required) — Ordered list of user message blocks.
- `chatId` (string, optional, nullable) — Existing chat ID to append to; omit to start a new chat.
- `connectors` (ConnectorsInput, optional) — Connector selection for this request. Omitting this field is equivalent to \{"mode": "none"}. Only available when "agent" and "sources" are omitted.
- `editingTarget` (EntryEditingTargetInput, optional) — Benchling object (e.g. entry) to edit via a new chat. Not allowed when "agent" or "chatId" are specified.
- `sources` (list of ChatSourceInput, optional) — Data sources the agent may use. Not available for benchling_ask_v1.
- `agent` (enum, optional, deprecated) — Deprecated agent identifier to use.
  - Allowed values: `benchling_deep_research_v1`, `benchling_ask_v1`

## Response

### 202

Task started

- `pollingUri` (string, optional)
- `taskId` (string, optional)

## Errors

### 400 Agent Create Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 402 Agent Create Request Payment Required Error

Payment Required

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Agent Create Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Agent Create Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Agent Create Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Agent Create Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### BaseCreateMessageBlockInput

- `type` (enum, required)
  - Allowed values: `file`, `text`
- `filename` (string, optional) — Name to display for the attached file.
- `mediaType` (string, optional) — Media (MIME) type of the attached file, e.g. `text/csv` or `application/pdf`.
- `source` (ScratchFileSourceInput, optional)
- `text` (string, optional)

### ConnectorsInput

- `mode` (enum, required) — "none" disables connectors and "all_connected" enables all active connectors for the current user. A future "explicit" mode with an "ids" field is planned but is not currently supported.
  - Allowed values: `none`, `all_connected`

### EntryEditingTargetInput

- `id` (string, required) — API ID of the notebook entry to edit.
- `type` (enum, required)
  - Allowed values: `entry`

### ChatSourceInput

- `type` (enum, required)
  - Allowed values: `mcp_server`, `public_data`
- `serverId` (string, optional) — API ID of the MCP server to enable (e.g. mcpconf_abc123).

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### ScratchFileSourceInput

- `scratchFileId` (string, required) — API ID of a scratch file whose `uploadStatus` is `SUCCEEDED` (e.g. scrfile_abc123).
- `type` (enum, required)
  - Allowed values: `scratch_file`

## Examples

### benchling_ask_v1

**Request**

```json
{
  "input": [
    {
      "type": "text",
      "text": "What is the most recently created entry?"
    }
  ]
}
```

**Response**

```json
{
  "pollingUri": "pollingUri",
  "taskId": "taskId"
}
```

**SDK Code**

```python benchling_ask_v1
import requests

url = "https://{tenant_name}.benchling.com/api/v3/agents"

payload = { "input": [
        {
            "type": "text",
            "text": "What is the most recently created entry?"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript benchling_ask_v1
const url = 'https://{tenant_name}.benchling.com/api/v3/agents';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"input":[{"type":"text","text":"What is the most recently created entry?"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

### benchling_deep_research_v1

**Request**

```json
{
  "input": [
    {
      "type": "text",
      "text": "What should I do next?"
    }
  ],
  "sources": [
    {
      "type": "public_data"
    }
  ]
}
```

**Response**

```json
{
  "pollingUri": "pollingUri",
  "taskId": "taskId"
}
```

**SDK Code**

```python benchling_deep_research_v1
import requests

url = "https://{tenant_name}.benchling.com/api/v3/agents"

payload = {
    "input": [
        {
            "type": "text",
            "text": "What should I do next?"
        }
    ],
    "sources": [{ "type": "public_data" }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript benchling_deep_research_v1
const url = 'https://{tenant_name}.benchling.com/api/v3/agents';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"input":[{"type":"text","text":"What should I do next?"}],"sources":[{"type":"public_data"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

### new_chat

**Request**

```json
{
  "input": [
    {
      "type": "text",
      "text": "What should I do next?"
    }
  ],
  "sources": [
    {
      "type": "public_data"
    }
  ]
}
```

**Response**

```json
{
  "pollingUri": "pollingUri",
  "taskId": "taskId"
}
```

**SDK Code**

```python new_chat
import requests

url = "https://{tenant_name}.benchling.com/api/v3/agents"

payload = {
    "input": [
        {
            "type": "text",
            "text": "What should I do next?"
        }
    ],
    "sources": [{ "type": "public_data" }]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript new_chat
const url = 'https://{tenant_name}.benchling.com/api/v3/agents';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"input":[{"type":"text","text":"What should I do next?"}],"sources":[{"type":"public_data"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```