Skip to main content
The knowledge base stores documents that genies reference during conversations. Documents can be created from PDFs, websites, YouTube videos, or plain text. Each document is stored both in the HelpGenie database and in the voice agent system.
Standard users can only access their own documents. Admin users can access all documents and filter by owner when passing adminMode: true.

List all documents

Retrieves all documents with pagination, filtering, and role-based access control. Returns documents along with their dependent agents.
string
required
Must be "knowledge-base"
string
required
Must be "all"
object
boolean
Whether the request succeeded.
object

List documents

Retrieves a compact, paginated list of documents. Returns only essential fields — optimized for dropdowns, selects, and search results. For full document details including metadata and folder info, use the all action instead.
string
required
Must be "knowledge-base"
string
required
Must be "list"
object
boolean
Whether the request succeeded.
object

Get document

Retrieves a single document by its UUID or 20-character external document ID. Returns full details including metadata, folder info, and dependent agents.
string
required
Must be "knowledge-base"
string
required
Must be "get"
string
required
The document UUID or external document ID (el_doc_id).
object
boolean
Whether the request succeeded.
object
Non-admin users can only access their own documents or documents marked as public. Admin users with adminMode: true can access all documents and see owner information.

Get document content

Retrieves the plain-text content of a document. Uses a priority order: manual edits → optimised content → original parsed content.
string
required
Must be "knowledge-base"
string
required
Must be "get-content"
string
required
The document UUID or external document ID (el_doc_id). When several documents share an el_doc_id, your own copy is returned first, then your workspace owner’s. An ID that is neither a UUID nor a valid external document ID is rejected with VALIDATION_ERROR.
object
boolean
Whether the request succeeded.
object
Non-admin users can retrieve content for their own documents, their workspace owner’s documents (team members), and documents marked as public. Any other document returns NOT_FOUND. A 404 is also returned when no readable content is available yet — the document may still be processing.

Create document (text)

The simplest way to add a knowledge base document. Pass title and content directly — no file upload needed. If you omit the nested action field, create-notes is used by default.
string
required
Must be "knowledge-base"
string
required
Must be "create"
object
required
Ownership: if the caller is a team member, the document defaults to team ownership (owned by the team owner) rather than the caller’s personal account. Pass personal: true to keep it on the caller’s own account.
Documents are processed asynchronously. After creation, the document transitions through stages: pending_extraction → pending_optimization → completed.

Create document (advanced)

For content sources other than text, use the nested sub-action pattern. The create action delegates to the internal document upload pipeline.
string
required
Must be "knowledge-base"
string
required
Must be "create"
object
required
boolean
Whether the request succeeded.
object
The create action delegates to the internal document upload pipeline (doc-upload edge function). The nested data.action field determines which content source is used. Supported sub-actions:
  • upload-website — Extract content from a single URL
  • scrape-website — Crawl and parse website content
  • extract-youtube — Extract the transcript from a YouTube video URL
  • upload-pdf — Upload and process a PDF file
  • extract-document — Extract content from various document formats (DOCX, TXT, etc.)
Ownership: if the caller is a team member, the document defaults to team ownership (owned by the team owner) rather than the caller’s personal account. Pass personal: true to keep it on the caller’s own account.

Update document (data mode)

Updates document metadata fields without changing the content. Only the fields you provide are updated. Metadata is intelligently merged with existing values. If the document name changes and the document has been synced with the voice platform, the name is also updated there.
string
required
Must be "knowledge-base"
string
required
Must be "update"
string
required
The document UUID to update.
object
required
boolean
Whether the request succeeded.
object

Update document (content mode)

Replaces the document content. A new voice platform document is created with the updated content, and all dependent genies are automatically updated with the new external document ID (fire-and-forget sync). The new content is also saved to storage and a signed URL is returned.
string
required
Must be "knowledge-base"
string
required
Must be "update"
string
required
The document UUID to update.
object
required
boolean
Whether the request succeeded.
object
Content mode deletes the old external document and creates a new one. All genies that depend on this document are automatically updated with the new external document ID.

Bulk update documents

Updates multiple documents at once. Only metadata fields can be bulk-updated — document content cannot be changed via this action.
string
required
Must be "knowledge-base"
string
required
Must be "bulk-update"
object
required
boolean
Whether all documents were updated successfully.
string
Human-readable summary of the operation.
number
Number of documents actually updated.
string[]
The document IDs that were targeted by the update.
object
The update payload that was applied, containing only the fields that were provided.

Delete document

Permanently deletes a document, removes it from storage and the voice agent system, and syncs the removal with all dependent agents.
string
required
Must be "knowledge-base"
string
required
Must be "delete"
string
required
The document UUID to delete.
object
boolean
Whether the request succeeded.
object
This action is irreversible. The document, its storage file, and its external record will be permanently removed. All dependent genies will have the document removed from their knowledge base unless skipAgentSync is set to true.

Attach documents to agent

Adds one or more documents to a genie’s knowledge base. Documents the genie already has are skipped, including a document already linked to the genie whose el_doc_id has changed since it was re-synced.
string
required
Must be "knowledge-base"
string
required
Must be "attach"
object
required
boolean
Whether the request succeeded.
string
Summary of attached documents.
number
Number of documents successfully attached.
The id field in each document object is the el_doc_id — the 20-character external platform ID found on each document row. To get this value, first fetch documents via all or list and read the el_doc_id field. Duplicate documents (already attached) are automatically skipped.

Detach documents from agent

Removes specific documents from a genie’s knowledge base.
string
required
Must be "knowledge-base"
string
required
Must be "detach"
object
required
boolean
Whether the request succeeded.
string
Summary of detached documents.
number
Number of documents successfully detached.

Replace agent knowledge base

Atomically replaces a genie’s entire knowledge base with a new document set. Each document is validated before the update is applied. The genie’s voice platform configuration is updated with the new document list, agent_document relations are synced (old documents removed, new documents upserted), and connected clients are notified via a realtime broadcast.
string
required
Must be "knowledge-base"
string
required
Must be "replace"
object
required
boolean
Whether the request succeeded.
string
Summary of the replacement, including document count.
number
Number of documents in the new knowledge base.
Document IDs passed in the documents array are voice platform external IDs, not HelpGenie document UUIDs. All documents are validated against the platform before the replacement is applied — if no valid documents are found in a non-empty array, the request is rejected with a VALIDATION_ERROR.

Sync documents with agents

Synchronizes document changes across all dependent agents. Removes old external documents and adds updated ones to each agent’s knowledge base. Typically used internally after document content is updated or deleted.
string
required
Must be "knowledge-base"
string
required
Must be "sync-with-agents"
object
boolean
Whether the request succeeded.
object

Clone document

Creates an independent copy of an existing document. The stored files are duplicated under the new owner’s storage path and the copy is indexed separately for the voice system, so editing or deleting the clone never affects the original.
string
required
Must be "knowledge-base"
string
required
Must be "clone"
string
required
UUID of the document to clone.
object

Response

Returns 201 Created.
boolean
Whether the request succeeded.
object
Copying the stored files is best-effort — if an individual file cannot be copied the clone is still created, so a clone of a document that is still processing may hold less content than the original. The clone’s status is set to completed.

Consolidate documents

Merges multiple documents into a single new document. Optionally prunes the originals after consolidation. This delegates to the doc-upload edge function.
string
required
consolidate
object
required

Starts reading a genie’s knowledge documents for links and pictures worth offering to visitors. The request returns immediately with the number of documents queued; the scan itself runs in the background. Read the results with links once it has finished. Only processed, active documents attached to the genie are scanned (up to 150). By default, only documents that were never scanned, or whose content changed since their last scan, are queued.
string
required
Must be "knowledge-base"
string
required
Must be "scan-links"
object
required
boolean
Whether the request succeeded.
object
New documents are scanned automatically once they finish processing, so this action is mainly useful for documents added before link scanning was available, or to re-scan everything with force: true. Returns FORBIDDEN if you do not have access to the genie.

Returns the links and pictures found inside a genie’s knowledge documents by the link scan, along with the document each came from. Each address is listed once. This action is read-only — nothing is added to the genie’s Resources.
string
required
Must be "knowledge-base"
string
required
Must be "links"
object
required
boolean
Whether the request succeeded.
object
To offer a link to visitors, add it to the genie’s Resources with genies / update (info_links.links).

Documents outside workspace

Returns documents that are attached to one of the workspace’s genies but are owned by a different user. This surfaces documents that were added to a genie by an admin on behalf of the workspace — they would otherwise be invisible because documents are normally scoped to the owner’s account. Pagination is supported. Results are sorted newest-first. Only the current user’s workspace is searched — no additional parameters are required.
string
required
Must be "knowledge-base"
string
required
Must be "outside-workspace"
object
boolean
Whether the request succeeded.
object

Error codes

If the document processing service is briefly unavailable, the request is retried automatically before any error is returned. If it is still unavailable, you receive an INTERNAL_ERROR with the message “The knowledge base service is temporarily unavailable. Nothing was saved — please try again in a moment.” No changes are made in this case, so it is safe to retry the same request.