For AI agents: markdown of this page — /docs-content-en/agents/list.md documentation index — /llms.txt

List AI agents

GET /v1/agents

Returns non-deleted AI agents owned by the API-key owner on the current Bitrix24 account. The method reads local Vibecode data, so it requires no separate Bitrix24 scope.

The list owner is the Vibecode user who owns the key. For an OAuth application, X-Api-Key identifies that owner; the vibe_session_* user session in Authorization does not change the filter. Therefore, an OAuth application key without a Bearer session still returns the agents owned by the key's Vibecode owner rather than an empty list.

bitrixBotId is the numeric Bitrix24 bot user ID. Pass this value as welcomeBotId in an Open Channel configuration. The field is null until bot provisioning finishes.

Request parameters

Parameter Type Required Default Description
Parameterlimit Typeinteger Requiredno Default50 DescriptionPage size, from 1 to 200
Parameteroffset Typeinteger Requiredno Default0 DescriptionOffset from the start of the list

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/agents?limit=50&offset=0" \
  -H "X-Api-Key: $VIBE_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/agents?limit=50&offset=0" \
  -H "X-Api-Key: $VIBE_APP_KEY" \
  -H "Authorization: Bearer $VIBE_SESSION_TOKEN"

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/agents?limit=50&offset=0', {
  headers: { 'X-Api-Key': process.env.VIBE_API_KEY },
})
const { success, data } = await response.json()

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/agents?limit=50&offset=0', {
  headers: {
    'X-Api-Key': process.env.VIBE_APP_KEY,
    Authorization: `Bearer ${process.env.VIBE_SESSION_TOKEN}`,
  },
})
const { success, data } = await response.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typeobject DescriptionResult envelope
Fielddata.agents Typearray DescriptionAgents on the current page
Fielddata.agents[].id Typestring DescriptionVibecode agent ID
Fielddata.agents[].name Typestring DescriptionAgent name
Fielddata.agents[].status Typestring DescriptionCREATING, RUNNING, STOPPED, ERROR, or DELETED
Fielddata.agents[].kind Typestring DescriptionRuntime type: HERMES or OPENCLAW
Fielddata.agents[].bitrixBotId Typeinteger | null DescriptionBitrix24 bot user ID; the value for welcomeBotId
Fielddata.hasNextPage Typeboolean Descriptiontrue when more records follow this page

Request the next page with offset + limit. Deleted agents and agents belonging to another user or Bitrix24 account are not returned.

Response example

JSON 
{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "cmf123example",
        "name": "Customer support",
        "status": "RUNNING",
        "kind": "HERMES",
        "bitrixBotId": 417
      }
    ],
    "hasNextPage": false
  }
}

Bind to an Open Channel

Copy the selected agent's bitrixBotId to welcomeBotId when creating or updating an openline-configs record. The agentId field is not used for this. queue contains human operator user IDs and does not identify a Hermes agent.

Error response example

401 — an unknown API key was passed:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Errors

HTTP Code When it occurs
HTTP401 CodeMISSING_API_KEY When it occursThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY When it occursThe key is not recognized — no such key exists on the platform
HTTP401 CodeKEY_INACTIVE When it occursThe key is inactive or revoked
HTTP401 CodeKEY_EXPIRED When it occursThe key has expired
HTTP401 CodeWRONG_AUTH_SCHEME When it occursThe OAuth application key was incorrectly passed as a Bearer token
HTTP401 CodeINVALID_SESSION When it occursThe OAuth application Bearer session is unknown or expired
HTTP401 CodeTOKEN_EXPIRED When it occursThe expired user OAuth token could not be refreshed
HTTP401 CodeNO_PORTAL When it occursThe key is not bound to a portal
HTTP403 CodeSESSION_APP_MISMATCH When it occursThe Bearer session belongs to another application or portal
HTTP403 CodeMANAGEMENT_KEY_NO_ENTITY_ACCESS When it occursA management key was passed instead of an application key

For the complete list of shared API errors, see Errors.

Creating, updating, and deleting agents is only available in the Agents section. DELETE /v1/bots/:id deletes a standalone chat bot, not an AI agent.

See also