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.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "all"
​
data
object
​
success
boolean
Whether the request succeeded.
​
data
object
const response = await ApiService.invoke("documents", "all", undefined, {
  limit: 50,
  offset: 0,
  filters: {
    searchTerm: "product",
    selectedPrivacy: "public",
    selectedType: "pdf_upload",
  },
});

​
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.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "get"
​
id
string
required
The document UUID or external document ID (el_doc_id).
​
data
object
​
success
boolean
Whether the request succeeded.
​
data
object
const response = await ApiService.invoke(
  "documents",
  "get",
  "770e8400-e29b-41d4-a716-446655440002"
);
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.

​
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.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "create"
​
data
object
required
curl -s -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "title": "Company FAQ",
    "content": "Q: What are your hours?\nA: Monday-Friday 9am-5pm.",
    "agentId": "genie-uuid"
  }'
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.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "create"
​
data
object
required
​
success
boolean
Whether the request succeeded.
​
data
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.)
const response = await ApiService.invoke("documents", "create", undefined, {
  action: "upload-website",
  data: {
    url: "https://example.com/documentation",
  },
});

​
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.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "update"
​
id
string
required
The document UUID to update.
​
data
object
required
​
success
boolean
Whether the request succeeded.
​
data
object
const response = await ApiService.invoke(
  "documents",
  "update",
  "770e8400-e29b-41d4-a716-446655440002",
  {
    mode: "data",
    name: "Updated Product Documentation",
    is_active: true,
    is_public: false,
    folder_id: "550e8400-e29b-41d4-a716-446655440000",
  }
);

​
Update document (content mode)

Replaces the document content in the voice agent system. The old external document is deleted and a new one is created. All dependent agents are automatically updated with the new content.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "update"
​
id
string
required
The document UUID to update.
​
data
object
required
​
success
boolean
Whether the request succeeded.
​
data
object
const response = await ApiService.invoke(
  "documents",
  "update",
  "770e8400-e29b-41d4-a716-446655440002",
  {
    mode: "content",
    content: "Updated document content with revised product information...",
    isOptimized: false,
  }
);
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.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "bulk-update"
​
data
object
required
​
success
boolean
​
message
string
Summary of updated documents.
​
updatedCount
number
Number of documents updated.
{
  "resource": "documents",
  "action": "bulk-update",
  "data": {
    "documentIds": ["doc-id-1", "doc-id-2", "doc-id-3"],
    "updates": {
      "is_active": true,
      "folder_id": "folder-uuid"
    }
  }
}

​
Delete document

Permanently deletes a document, removes it from storage and the voice agent system, and syncs the removal with all dependent agents.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "delete"
​
id
string
required
The document UUID to delete.
​
success
boolean
Whether the request succeeded.
​
data
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.
const response = await ApiService.invoke(
  "documents",
  "delete",
  "770e8400-e29b-41d4-a716-446655440002"
);

​
Attach documents to agent

Adds one or more documents to a genie’s knowledge base. Duplicate documents are automatically skipped.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "attach"
​
data
object
required
​
success
boolean
Whether the request succeeded.
​
message
string
Summary of attached documents.
​
attachedCount
number
Number of documents successfully attached.
const response = await ApiService.invoke("documents", "attach", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  documents: [
    { id: "doc-id-1", name: "Product FAQ", type: "file" },
    { id: "doc-id-2", name: "Pricing Guide", type: "url" },
  ],
});

​
Detach documents from agent

Removes specific documents from a genie’s knowledge base.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "detach"
​
data
object
required
​
success
boolean
Whether the request succeeded.
​
message
string
Summary of detached documents.
​
detachedCount
number
Number of documents successfully detached.
const response = await ApiService.invoke("documents", "detach", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  documentIds: ["doc-id-1", "doc-id-2"],
});

​
Replace agent knowledge base

Completely replaces a genie’s knowledge base with a new set of documents. Documents not in the new list are removed; new documents are added.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "replace"
​
data
object
required
​
success
boolean
Whether the request succeeded.
​
message
string
Summary of replaced documents.
​
replacedCount
number
Number of documents in the new knowledge base.
const response = await ApiService.invoke("documents", "replace", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  documents: [
    { id: "doc-id-1", name: "Product FAQ", type: "file" },
    { id: "doc-id-3", name: "Return Policy", type: "file" },
  ],
});

​
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.
​
resource
string
required
Must be "documents"
​
action
string
required
Must be "sync-with-agent"
​
data
object
​
success
boolean
Whether the request succeeded.
​
data
object
const response = await ApiService.invoke(
  "documents",
  "sync-with-agent",
  undefined,
  {
    oldDocId: "el-doc-abc123def456",
    newDocId: "el-doc-xyz789uvw012",
    preventDeletion: false,
  }
);

​
Error codes

CodeStatusDescription
UNAUTHORIZED401Missing or invalid authentication token
INVALID_TOKEN401Token validation failed
FORBIDDEN403User lacks required permissions
NOT_FOUND404Document not found
VALIDATION_ERROR400Invalid request parameters
INVALID_ACTION400Unknown action for the documents resource
INTERNAL_ERROR500Server-side error