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 account. The method reads local Vibecode data, so it requires no separate Bitrix24 scope.

The list owner is the Vibe 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 Vibe 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
limit integer no 50 Page size, from 1 to 200
offset integer no 0 Offset 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
success boolean true when the request succeeds
data object Result envelope
data.agents array Agents on the current page
data.agents[].id string Vibecode agent ID
data.agents[].name string Agent name
data.agents[].status string CREATING, RUNNING, STOPPED, ERROR, or DELETED
data.agents[].kind string Runtime type: HERMES or OPENCLAW
data.agents[].bitrixBotId integer | null Bitrix24 bot user ID; the value for welcomeBotId
data.hasNextPage boolean true when more records follow this page

Request the next page with offset + limit. Deleted agents and agents belonging to another user or 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. Do not use agentId 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
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY The key was not found
401 KEY_INACTIVE The key is inactive or revoked
401 KEY_EXPIRED The key has expired
401 WRONG_AUTH_SCHEME The OAuth application key was incorrectly passed as a Bearer token
401 INVALID_SESSION The OAuth application Bearer session is unknown or expired
401 TOKEN_EXPIRED The expired user OAuth token could not be refreshed
401 NO_PORTAL The key is not bound to an account
403 SESSION_APP_MISMATCH The Bearer session belongs to another application or account
403 MANAGEMENT_KEY_NO_ENTITY_ACCESS A management key was passed instead of an application key

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

Create, mutate, and delete agents in the agent control panel. DELETE /v1/bots/:id deletes a standalone chat bot, not an AI agent.

See also