# 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 called `collection` in paths (`/v1/note/collections`) is called a knowledge base in the Bitrix24 interface. Path identifiers stay on `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: creating knowledge bases is available to portal employees, changing and deleting to users with the knowledge-base management right, editing a document to users with the edit right. The Bitrix24 account administrator has full access. When rights are insufficient, the API returns `403 BITRIX_ACCESS_DENIED`.

A read-only key gets `403 WRITE_BLOCKED_READONLY_KEY` on any method that changes data. Reading — listing and getting a knowledge base, the document tree, getting and searching documents, file metadata — is available to any key.

`OAuth` applications add the `Authorization: Bearer USER_SESSION_TOKEN` header together with `X-Api-Key` on 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`:

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

## Full example

A document with a picture. An attachment is added in two steps. Upload saves the file and links it to the document but does not insert it into the content. To make the attachment visible, get the ready-to-insert `assetMarkdown` fragment and add it to the document 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 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. Ready-to-insert attachment fragment
MD=$(curl -s "$BASE/note/documents/$DID/files/$FID" \
  -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.assetMarkdown')

# 4. 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/: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/: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 right for the operation on the knowledge base or document |
| 404 | `ENTITY_NOT_FOUND` | The knowledge base, document, or file does not exist, was deleted, or was archived |
| 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)