# 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 |
|-----------|------|:--------:|---------|-------------|
| `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

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

### curl — OAuth application

```bash
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 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`](/docs/openlines/config) 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 |
|------|------|----------------|
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `INVALID_API_KEY` | The key is not recognized — no such key exists on the platform |
| 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 a portal |
| 403 | `SESSION_APP_MISMATCH` | The Bearer session belongs to another application or portal |
| 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](/docs/errors).

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

## See also

- [AI agents](/docs/agents)
- [Open Channel configurations](/docs/openlines/config)
- [API errors](/docs/errors)