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.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 theall action instead.
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.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.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.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. Passtitle and content directly — no file upload needed. If you omit the nested action field, create-notes is used by default.
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. Thecreate action delegates to the internal document upload pipeline.
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 URLscrape-website— Crawl and parse website contentextract-youtube— Extract the transcript from a YouTube video URLupload-pdf— Upload and process a PDF fileextract-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.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.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.Delete document
Permanently deletes a document, removes it from storage and the voice agent system, and syncs the removal with all dependent agents.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 whoseel_doc_id has changed since it was re-synced.
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.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.
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.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.Response
Returns201 Created.
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 thedoc-upload edge function.
Scan documents for links
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 withlinks 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.
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.List links found in documents
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.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.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.
