Skip to Content

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

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The agent ID.

userIdstring

The user ID linked to the agent.

namestring

The agent first name.

surnamestring

The agent surname.

emailstring

The agent email.

avatarstring

The agent avatar URL. You can use Gravatar for the avatar. Or patch the agent with a custom avatar URL.

createdAtDateTime

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

conversationIdstring

Filter agents by conversation ID.

namestring

Filter agents by name.

surnamestring

Filter agents by surname.

emailstring

Filter agents by email.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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 } } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

userIdstring

Required. User ID of the agent.

namestring

Required. The name of the agent.

surnamestring

The surname of the agent.

emailstring

Required. Agent email.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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]" } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

FieldTypeDescription
workspaceIdInt!

Target workspace.

userIdString

Optional. Invited workspace user id. If omitted, a synthetic api:… id is stored for API-key-only agents. If the email is provided and the user is invited to the workspace, the agent will be linked to the invited user automatically after accessing the workspace.

nameString!

Agent first name.

surnameString

Agent surname.

emailString

Optional. If omitted, stored as an empty string (API-key-only / non-login agents).

apiKeyLabelString

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The ID.

namestring

Required. The name.

surnamestring

Agent surname.

assignableboolean

Required. Whether automatic assignment can pick this agent. Send the current value to keep it.

greetingMessagestring

Message sent to the client at the start of every new conversation assigned to this agent. null clears it; leaving it out keeps the current value.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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]" } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The agent ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query 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.

ErrorCause
Target agent does not existNo agent with this ID in the workspace, or the agent was deleted.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The ID of the agent to delete.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation 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 assignConv if needed.
  • Automatic assignment no longer picks the agent, and assignConv to it fails with Target agent does not exist. On channels that use AUTO assignment, 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.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

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}"}'