# База знаний 2.0

Программный доступ к Базе знаний 2.0 Битрикс24: базы знаний, документы с содержимым в Markdown и вложения к ним.

**Скоуп:** `note` | **Базовый URL:** `https://vibecode.bitrix24.tech/v1` | **Авторизация:** `X-Api-Key`

> **Терминология.** Сущность, которая в путях называется `collection` (`/v1/note/collections`), в интерфейсе Битрикс24 называется базой знаний. Идентификаторы путей остаются на `collection`.

## Разделы документации

- [Базы знаний](/docs/note/collections) — создать, список, получить, переименовать, архивировать, удалить, дерево документов
- [Документы](/docs/note/documents) — создать, получить, обновить, архивировать, удалить, полнотекстовый поиск
- [Файлы](/docs/note/files) — загрузить вложение и получить готовый фрагмент для вставки в документ

## Доступ

Требуется скоуп `note`. Дополнительно действует контроль доступа Базы знаний: создание баз знаний доступно сотрудникам портала, изменение и удаление — пользователям с правом управления базой знаний, редактирование документа — пользователям с правом редактирования. Администратор портала имеет полный доступ. При нехватке прав API возвращает `403 BITRIX_ACCESS_DENIED`.

Ключ в режиме «только чтение» получает `403 WRITE_BLOCKED_READONLY_KEY` на любом методе, изменяющем данные. Чтение — список и получение базы знаний, дерево документов, получение и поиск документов, метаданные файла — доступно любому ключу.

`OAuth`-приложения добавляют заголовок `Authorization: Bearer USER_SESSION_TOKEN` вместе с `X-Api-Key` к каждому вызову.

## Быстрый старт

Список доступных баз знаний:

```bash
curl https://vibecode.bitrix24.tech/v1/note/collections \
  -H "X-Api-Key: YOUR_API_KEY"
```

Ответ содержит массив баз знаний в `data` и курсор следующей страницы в `meta.nextCursor`:

```json
{
  "success": true,
  "data": [
    { "id": 9, "name": "Документация продукта", "position": 100, "policyLevel": "none" }
  ],
  "meta": { "nextCursor": null }
}
```

## Полный пример

Документ с картинкой. Вложение добавляется в два шага. Загрузка сохраняет файл и привязывает его к документу, но не вставляет в содержимое. Чтобы вложение стало видимым, получите готовый фрагмент `assetMarkdown` и добавьте его в Markdown документа.

```bash
BASE='https://vibecode.bitrix24.tech/v1'

# 1. Документ (пустой) → запоминаем id
DID=$(curl -s -X POST "$BASE/note/documents" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"collectionId": 42, "title": "Архитектура"}' | jq -r '.data.id')

# 2. Файл (Base64) → запоминаем fileId
FID=$(curl -s -X POST "$BASE/note/documents/$DID/files" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"fileName\": \"arch.png\", \"fileContent\": \"$(base64 -w0 arch.png)\"}" | jq -r '.data.id')

# 3. Готовый фрагмент вложения
MD=$(curl -s "$BASE/note/documents/$DID/files/$FID" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.assetMarkdown')

# 4. Вставляем фрагмент в содержимое документа
curl -s -X PATCH "$BASE/note/documents/$DID" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"markdown\": \"# Архитектура\n\n$MD\", \"overwrite\": true}"
```

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|----------|
| POST | [`/v1/note/collections`](/docs/note/collections/create) | note.collection.add | Создать базу знаний |
| GET | [`/v1/note/collections`](/docs/note/collections/list) | note.collection.list | Список баз знаний |
| GET | [`/v1/note/collections/:id`](/docs/note/collections/get) | note.collection.get | Получить базу знаний |
| PATCH | [`/v1/note/collections/:id`](/docs/note/collections/update) | note.collection.update | Переименовать базу знаний |
| POST | [`/v1/note/collections/:id/archive`](/docs/note/collections/archive) | note.collection.archive | Архивировать базу знаний |
| DELETE | [`/v1/note/collections/:id`](/docs/note/collections/delete) | note.collection.delete | Удалить базу знаний |
| GET | [`/v1/note/collections/:collectionId/documents`](/docs/note/collections/tree) | note.document.tree.list | Дерево документов базы знаний |
| POST | [`/v1/note/documents`](/docs/note/documents/create) | note.document.add | Создать документ |
| GET | [`/v1/note/documents/:id`](/docs/note/documents/get) | note.document.get | Получить документ |
| PATCH | [`/v1/note/documents/:id`](/docs/note/documents/update) | note.document.update | Обновить документ |
| POST | [`/v1/note/documents/:id/archive`](/docs/note/documents/archive) | note.document.archive | Архивировать документ |
| DELETE | [`/v1/note/documents/:id`](/docs/note/documents/delete) | note.document.delete | Удалить документ |
| GET | [`/v1/note/documents/search`](/docs/note/documents/search) | note.document.search.list | Поиск документов |
| POST | [`/v1/note/documents/search`](/docs/note/documents/search) | note.document.search.list | Поиск документов POST-запросом — алиас канонической GET-формы |
| POST | [`/v1/note/documents/:documentId/files`](/docs/note/files/upload) | note.file.add | Загрузить файл |
| GET | [`/v1/note/documents/:documentId/files/:id`](/docs/note/files/get) | note.file.get | Получить метаданные файла |

## Коды ошибок

| HTTP | Код | Когда |
|------|-----|-------|
| 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `note` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме «только чтение» вызвал метод записи |
| 403 | `BITRIX_ACCESS_DENIED` | Нет права на операцию с базой знаний или документом |
| 404 | `ENTITY_NOT_FOUND` | База знаний, документ или файл не существуют, удалены или архивированы |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 недоступен |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Смотрите также

- [Базы знаний](/docs/note/collections)
- [Документы](/docs/note/documents)
- [Файлы](/docs/note/files)