# Knowledge Base 2.0

Programmatic access to Bitrix24 Knowledge Base 2.0: knowledge bases, documents with Markdown content, and their attachments.

**Scope:** `note` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

> **Terminology.** The entity named `collection` in paths (`/v1/note/collections`) is called a knowledge base in the Bitrix24 interface. Path identifiers remain `collection`.

## Documentation sections

- [Knowledge bases](/docs/note/collections) — create, list, get, rename, archive, delete, document tree
- [Documents](/docs/note/documents) — create, get, update, archive, delete, full-text search
- [Files](/docs/note/files) — upload an attachment and get a ready-to-insert fragment for the document

## Access

The `note` scope is required. Knowledge Base access control also applies: any employee of the Bitrix24 account can create knowledge bases; changing and deleting a knowledge base requires permission to manage it; editing a document requires permission to edit it. The Bitrix24 account administrator has full access. Without sufficient permissions, the API returns `403 BITRIX_ACCESS_DENIED`.

A read-only key gets `403 WRITE_BLOCKED_READONLY_KEY` on any method that changes data. Read operations — listing and getting knowledge bases, the document tree, getting and searching documents, and file metadata — are available to any key.

`OAuth` applications add the `Authorization: Bearer USER_SESSION_TOKEN` header along with `X-Api-Key` to every call.

## Quick start

List available knowledge bases:

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

The response contains an array of knowledge bases in `data` and the next-page cursor in `meta.nextCursor`. Only the main fields are shown. The full list is in [Knowledge bases list](/docs/note/collections/list):

```json
{
  "success": true,
  "data": [
    { "id": 9, "name": "Product documentation", "position": 100, "policyLevel": "private" }
  ],
  "meta": { "nextCursor": null }
}
```

## Full example

A document with an image. An attachment is added in two steps. Uploading saves the file, links it to the document, and returns the ready-to-insert `assetMarkdown` fragment, but does not insert it into the content. To make the attachment visible, add the fragment to the document's Markdown.

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

# 1. Document (empty) → remember the 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": "Architecture"}' | jq -r '.data.id')

# 2. File (Base64) → remember the ready-to-insert attachment fragment
MD=$(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.assetMarkdown')

# 3. Insert the fragment into the document content
curl -s -X PATCH "$BASE/note/documents/$DID" \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d "{\"markdown\": \"# Architecture\n\n$MD\", \"overwrite\": true}"
```

## Endpoint reference

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|----------|
| POST | [`/v1/note/collections`](/docs/note/collections/create) | note.collection.add | Create a knowledge base |
| GET | [`/v1/note/collections`](/docs/note/collections/list) | note.collection.list | List knowledge bases |
| GET | [`/v1/note/collections/:id`](/docs/note/collections/get) | note.collection.get | Get a knowledge base |
| PATCH | [`/v1/note/collections/:id`](/docs/note/collections/update) | note.collection.update | Rename a knowledge base |
| POST | [`/v1/note/collections/:id/archive`](/docs/note/collections/archive) | note.collection.archive | Archive a knowledge base |
| DELETE | [`/v1/note/collections/:id`](/docs/note/collections/delete) | note.collection.delete | Delete a knowledge base |
| GET | [`/v1/note/collections/:collectionId/documents`](/docs/note/collections/tree) | note.document.tree.list | Knowledge base document tree |
| POST | [`/v1/note/documents`](/docs/note/documents/create) | note.document.add | Create a document |
| GET | [`/v1/note/documents`](/docs/note/documents/list) | note.document.list | List documents with continuation |
| GET | [`/v1/note/documents/:id`](/docs/note/documents/get) | note.document.get | Get a document |
| PATCH | [`/v1/note/documents/:id`](/docs/note/documents/update) | note.document.update | Update a document |
| POST | [`/v1/note/documents/:id/archive`](/docs/note/documents/archive) | note.document.archive | Archive a document |
| DELETE | [`/v1/note/documents/:id`](/docs/note/documents/delete) | note.document.delete | Delete a document |
| GET | [`/v1/note/documents/search`](/docs/note/documents/search) | note.document.search.list | Search documents |
| POST | [`/v1/note/documents/search`](/docs/note/documents/search) | note.document.search.list | Search documents via POST — an alias of the canonical GET form |
| POST | [`/v1/note/documents/:documentId/files`](/docs/note/files/upload) | note.file.add | Upload a file |
| GET | [`/v1/note/documents/:documentId/files/:id`](/docs/note/files/get) | note.file.get | Get file metadata |

## Error codes

| HTTP | Code | When |
|------|-----|-------|
| 403 | `SCOPE_DENIED` | The key lacks the `note` scope |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | A read-only key called a write method |
| 403 | `BITRIX_ACCESS_DENIED` | No permission for the operation on the knowledge base or document, or the knowledge base is archived and you are trying to rename it |
| 404 | `ENTITY_NOT_FOUND` | The object does not exist or the knowledge base is deleted. For write methods on a document — also when the document is archived or in the trash. Reading archived knowledge bases and documents, as well as documents in the trash, works: the state is visible in `isArchived` and `isTrashed` |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable |

Full list of general API errors — [Errors](/docs/errors).

## See also

- [Knowledge bases](/docs/note/collections)
- [Documents](/docs/note/documents)
- [Files](/docs/note/files)