For AI agents: markdown of this page — /docs-content-en/note/collections/create.md documentation index — /llms.txt

Create a knowledge base

POST /v1/note/collections

Creates a knowledge base — a container for documents in Bitrix24 Knowledge Base 2.0. The body is passed flat, without a fields wrapper.

Request fields (body)

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionKnowledge base name
Fieldposition Typeinteger Requiredno DescriptionPosition in the list. Sorted by descending value. Defaults to 0 — the knowledge base is placed at the top of the list

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/note/collections \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product documentation",
    "position": 100
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/note/collections \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product documentation",
    "position": 100
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/note/collections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Product documentation',
    position: 100,
  }),
})

const { success, data } = await res.json()
console.log('Knowledge base ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/note/collections', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Product documentation',
    position: 100,
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionObject holding the identifier of the created knowledge base
Fielddata.id Typenumber DescriptionIdentifier of the created knowledge base

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 42
  }
}

Error response example

400 — name not provided:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`name` is required and must be a non-empty string"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionname not provided, or position is not a non-negative integer
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo permission to create knowledge bases on the Bitrix24 portal
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable
HTTP403 CodeSCOPE_DENIED DescriptionThe key is missing the note scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key operates in read-only mode
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors — Errors.

See also