# 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

```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 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. 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](/docs/errors).

Create, mutate, and delete agents in the [agent control panel](/agents). `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)