## Notification type dictionary

`GET /v1/notifications/schema`

Returns the directory of Bitrix24 account modules and the notification types they send. The operation takes no parameters.

## Parameters

The operation takes no parameters.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/notifications/schema" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/notifications/schema" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/schema', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
const labels = new Map(
  data.modules.flatMap((m) => m.list.map((t) => [`${m.moduleId}|${t.id}`, t.name])),
)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/notifications/schema', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Modules:', data.modules.length)
```

## Response fields

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | Always `true` on success |
| `data.modules` | array | Bitrix24 account modules that send notifications |
| `data.modules[].moduleId` | string | Module identifier. Matches the `notifyModule` of a notification in the [feed](./list.md) |
| `data.modules[].name` | string | Module name as the Bitrix24 account shows it |
| `data.modules[].list` | array | Notification types this module sends |
| `data.modules[].list[].id` | string | Type identifier. Matches the `notifyEvent` of a notification in the [feed](./list.md) |
| `data.modules[].list[].name` | string | Type name |

## Response example

HTTP 200:

```json
{
  "success": true,
  "data": {
    "modules": [
      {
        "moduleId": "crm",
        "name": "CRM",
        "list": [
          { "id": "crm_invoice_delivery", "name": "Invoice paid" },
          { "id": "crm_deal_stage", "name": "Deal stage changed" }
        ]
      },
      {
        "moduleId": "tasks",
        "name": "Tasks",
        "list": [
          { "id": "task_update", "name": "Task updated" }
        ]
      }
    ]
  }
}
```

## Error response example

403 — the key has no `im` scope:

```json
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 403 | `SCOPE_DENIED` | The key has no `im` scope |
| 401 | `TOKEN_MISSING` | The key has no tokens configured |
| 429 | `RATE_LIMITED` | The read budget for this directory is exhausted — up to 120 requests per minute per Bitrix24 account |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 returned a response that could not be read |
| 422 | `BITRIX_ERROR` | The method failed on the Bitrix24 side; the account's own code is in `b24Code` |

The full list of common API errors — [Errors](/docs/errors).

## Known specifics

- Bitrix24 hands the directory over as a map whose key repeats the `moduleId` inside the entry. This endpoint unwraps that map into the `modules` array, losing nothing. The element order is the one the account returned: it is not a sort contract, so do not rely on it.
- The contents depend on the account: the set of modules differs between accounts, and the list of types inside a module changes as Bitrix24 is updated. Cache the response, but re-read it when you meet an unfamiliar `notifyModule` or `notifyEvent` instead of treating the set as fixed.
- Module and type names arrive in the language of the account — they are data, not interface constants.
- The directory belongs to the account and does not depend on whose token made the call, unlike the [notification feed](./list.md).
- The rate is lower than the feed's: this is a dictionary that changes rarely, not a surface to poll.

## See also

- [Notification feed](./list.md)
- [Send notification](./send.md)
- [Mark as read](./read.md)
- [Errors](/docs/errors)