Overview

What this reference explains

Knowledge Docs organizes reference content into libraries (knowledge bases), each holding one or more documents (knowledge articles). A published document can be assigned to one or more voice assistants so the assistant can search it during a call, and a document can be shared with specific teammates by email for read or read/write access.

This reference shows how the Knowledge Docs system works under the hood: every dashboard action goes through these endpoints, with exact fields, validation limits, storage columns and error responses.

Identifiers

Libraries, documents, and assignments are all identified by UUID primary keys ({knowledge_base}, {article}, and the assignment {id} used by DELETE /article-assign/{id}). The one exception is the assistant path segment on the assignment endpoints ({assistantId} on GET /assistant/{assistantId} and GET /assistant/{assistantId}/assignable-articles): it accepts either the assistant's numeric internal id or its public UUID (vapi_assistant_id) — digits-only values are looked up by internal id, anything else by vapi_assistant_id.

Response envelope

Knowledge Docs does not use the panel's {"success": true, ...} envelope. Responses are plain {"data": ...} for reads and most writes, {"message": "..."} for actions with no payload to return (delete, unassign, permission changes), and {"message": "...", "data": ...} where an action both confirms and returns the affected resource (sync, share invite, shared-document update). List endpoints that support pagination-free filtering also add a meta object alongside data (see the library list endpoint).

One owned library per user

A non–super-admin account owns at most one library, enforced by a unique index on knowledge_bases.owner_user_id. GET /knowledge-bases transparently provisions that library ("My Library") the first time a user without one loads the page — no explicit create step is required. Calling POST /knowledge-bases a second time as that user is rejected with 422. Super admins are exempt: they own no personal library and may create as many as they like (typically org-level libraries).

POST /knowledge-bases/ensure-default exists for the same purpose from the assistant editor: it resolves (or provisions) a usable library for a given assistant without the caller ever visiting the Knowledge Docs page first.

Publishing and search sync

A document's status is draft, published, or archived. Only a published document is eligible for assistant assignment (POST /article-assign rejects drafts and archived documents with 422) or for search-index sync. Whenever a create/update changes the title, content, or status of a document, the affected sync (index it if published, remove it if not) runs synchronously in the same request — there is no background queue wait, though large documents can take tens of seconds. sync_status tracks the outcome: pending until a sync has run, synced once it succeeds (or once removal from the index completes), error if it throws (with the exception message truncated into sync_error).

Sharing by email

A document's owner (or anyone who can edit it) shares access by typing a recipient's email — there is no picker of existing users. An email that already has an account in the same organization is attached immediately and notified; an unknown email receives a sign-up invite and is attached automatically the moment they register. Recipients get either read-only (can_view) or read/write (can_edit) access; a recipient can edit the document's title and content through shared-with-me but can never change its publish status.

Feature availability

This module is gated by the knowledge_docs feature. When disabled, every endpoint under this module returns 403 with {"message":"This feature is not enabled for your account. Please contact your administrator.","feature":"knowledge_docs"}.