Agent APIs
Overview
Manage workspace agents and their profile information. An agent is a user that can be assigned to a conversation. A system user can have only one agent.
An agent is created for a user automatically when the user is invited to the workspace and he accepts the invitation and accessed the portal. However that agent is created with default name, if you want to change the name you can do it in the portal. You can manage agents directly from the Agents page.
Agent properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The agent ID. |
userId | string | The user ID linked to the agent. |
name | string | The agent first name. |
surname | string | The agent surname. |
email | string | The agent email. |
avatar | string | The agent avatar URL. You can use Gravatar for the avatar. Or patch the agent with a custom avatar URL. |
createdAt | DateTime | The timestamp when the agent was created. |
List Agents API
List the agents in the workspace. Next are the available filters to list the agents.
This endpoint supports pagination. See Pagination for more information.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
conversationId | string | Filter agents by conversation ID. |
name | string | Filter agents by name. |
surname | string | Filter agents by surname. |
email | string | Filter agents by email. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery agents($input: AgentsInput!) {
agents(input: $input) {
nodes {
id
userId
name
surname
email
}
pageInfo {
hasNextPage
endCursor
count
}
}
}
input AgentsInput {
workspaceId: Int! # Workspace ID.
conversationId: String # Filter agents by conversation ID.
name: String # Filter agents by name.
surname: String # Filter agents by surname.
email: String # Filter agents by email.
}The query above returns JSON structured like this:
{
"data": {
"agents": {
"nodes": [
{
"id": "agent_123",
"userId": "user_123",
"name": "Sara",
"surname": "Ahmed",
"email": "[email protected]"
}
],
"pageInfo": {
"hasNextPage": false,
"endCursor": "2026-03-16T10:15:00.000Z",
"count": 1
}
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"agents","variables":{"input":{"workspaceId":12,"name":"Sara","surname":"Ahmed","email":"[email protected]"}},"query":"query agents($input: AgentsInput!) {\n agents(input: $input) {\n nodes {\n id\n userId\n name\n surname\n email\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'Create Agent API
Create an agent for a user.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
userId | string | Required. User ID of the agent. |
name | string | Required. The name of the agent. |
surname | string | The surname of the agent. |
email | string | Required. Agent email. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation createAgent($input: AgentCreateInput!) {
createAgent(input: $input) {
id
userId
name
surname
email
}
}
input AgentCreateInput {
workspaceId: Int! # Workspace ID.
userId: String! # User ID of the agent.
name: String! # Agent first name.
surname: String # Agent surname.
email: String! # Agent email.
}The mutation above returns JSON structured like this:
{
"data": {
"createAgent": {
"id": "agent_123",
"userId": "user_123",
"name": "Sara",
"surname": "Ahmed",
"email": "[email protected]"
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"createAgent","variables":{"input":{"workspaceId":12,"userId":"user_123","name":"Sara","surname":"Ahmed","email":"[email protected]"}},"query":"mutation createAgent($input: AgentCreateInput!) {\n createAgent(input: $input) {\n id\n userId\n name\n surname\n email\n }\n}"}'Create agent with API key
Creates an agent and an API key linked to that agent in a single atomic operation. The returned API key uses Agent+ scope (same as linking a key via genApiKey with agentId). The raw secret is only returned in this response.
To attach a key to an agent that already exists, use genApiKey with agentId instead — see Agent API keys. To do either from the portal, see API key agents.
| Field | Type | Description |
|---|---|---|
workspaceId | Int! | Target workspace. |
userId | String | Optional. Invited workspace user id. If omitted, a synthetic |
name | String! | Agent first name. |
surname | String | Agent surname. |
email | String | Optional. If omitted, stored as an empty string (API-key-only / non-login agents). |
apiKeyLabel | String | Optional. Defaults to "API key · {name}" (includes surname if provided) when omitted. |
mutation createAgentWithApiKey($input: AgentCreateWithApiKeyInput!) {
createAgentWithApiKey(input: $input) {
agent {
id
workspaceId
userId
name
surname
email
createdAt
}
apiKey {
workspaceId
id
key
label
agentId
createdAt
}
}
}
input AgentCreateWithApiKeyInput {
workspaceId: Int!
userId: String
name: String!
surname: String
email: String
apiKeyLabel: String
}Patch Agent API
Patch an agent’s name, surname, availability for automatic assignment and greeting message.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The ID. |
name | string | Required. The name. |
surname | string | Agent surname. |
assignable | boolean | Required. Whether automatic assignment can pick this agent. Send the current value to keep it. |
greetingMessage | string | Message sent to the client at the start of every new conversation assigned to this agent. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation patchAgent($input: AgentPatchInput!) {
patchAgent(input: $input) {
id
userId
name
surname
email
}
}
input AgentPatchInput {
workspaceId: Int! # Workspace ID.
id: ID! # Agent ID.
name: String! # Agent first name.
surname: String # Agent surname.
assignable: Boolean! # Whether automatic assignment can pick this agent.
greetingMessage: String # Greeting sent at the start of new conversations assigned to this agent.
}The mutation above returns JSON structured like this:
{
"data": {
"patchAgent": {
"id": "agent_123",
"userId": "user_123",
"name": "Sara",
"surname": "Ahmed",
"email": "[email protected]"
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"patchAgent","variables":{"input":{"workspaceId":12,"id":"agent_123","name":"Sara","surname":"Ahmed","assignable":true}},"query":"mutation patchAgent($input: AgentPatchInput!) {\n patchAgent(input: $input) {\n id\n userId\n name\n surname\n email\n }\n}"}'Get Agent API
Get one agent by ID. Deleted agents are not returned.
Access: Any role on the workspace (Owner, Admin, Manager, Agent+, Agent). Works with workspace API keys and agent API keys.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The agent ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery agent($input: AgentInput!) {
agent(input: $input) {
id
userId
name
surname
email
avatar
assignable
greetingMessage
createdAt
}
}
input AgentInput {
workspaceId: Int! # Workspace ID.
id: ID! # Agent ID.
}The query above returns JSON structured like this:
{
"data": {
"agent": {
"id": "agent_123",
"userId": "user_123",
"name": "Sara",
"surname": "Haddad",
"email": "[email protected]",
"avatar": null,
"assignable": true,
"greetingMessage": "Hi, this is Sara from the support team. How can I help?",
"createdAt": "2026-09-02T08:15:00.000Z"
}
}
}assignable is true unless it was turned off with the Patch Agent API. greetingMessage is null when no greeting is set.
| Error | Cause |
|---|---|
Target agent does not exist | No agent with this ID in the workspace, or the agent was deleted. |
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"agent","variables":{"input":{"workspaceId":12,"id":"agent_123"}},"query":"query agent($input: AgentInput!) {\n agent(input: $input) {\n id\n userId\n name\n surname\n email\n avatar\n assignable\n greetingMessage\n createdAt\n }\n}"}'Delete Agent API
Delete an agent. The agent is soft-deleted, and every API key linked to it is deleted in the same transaction.
Access: MANAGE_WORKSPACE (Owner, Admin). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The ID of the agent to delete. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation deleteAgent($input: AgentInput!) {
deleteAgent(input: $input) {
id
userId
name
surname
email
}
}
input AgentInput {
workspaceId: Int! # Workspace ID.
id: ID! # Agent ID.
}The mutation above returns JSON structured like this:
{
"data": {
"deleteAgent": {
"id": "agent_123",
"userId": "user_123",
"name": "Sara",
"surname": "Haddad",
"email": "[email protected]"
}
}
}What happens after deletion:
- Agent API keys linked to the agent stop working right away and no longer appear in the API key list. Workspace-wide keys are not affected.
- Conversations already assigned to the agent stay assigned to it. They are not unassigned or reassigned, so move them with
assignConvif needed. - Automatic assignment no longer picks the agent, and
assignConvto it fails withTarget agent does not exist. On channels that useAUTOassignment, new conversations of clients that had it as their default agent go to another agent. - The agent no longer appears in the List Agents API or the Get Agent API.
- The user’s role on the workspace is not changed by this call.
Deleting an agent that is already deleted succeeds again. An ID that does not exist in the workspace returns an error.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"deleteAgent","variables":{"input":{"workspaceId":12,"id":"agent_123"}},"query":"mutation deleteAgent($input: AgentInput!) {\n deleteAgent(input: $input) {\n id\n userId\n name\n surname\n email\n }\n}"}'