Knowledge base

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

Show properties

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

object

Show properties

string

Filter by document name (case-insensitive).

string

Filter by visibility: "public" or "private".

string

Filter by document source type (for example "pdf_upload", "website", "youtube").

string

Filter by active status: "active" or "inactive".

string

Filter by processing status (for example "completed", "pending", "failed").

string

Filter by folder ID. Pass null for uncategorized documents.

string

Filter to documents attached to a specific genie. Pass "all" or omit to include all documents.

boolean

default:"false"

When true, only returns documents that have been synced to the knowledge base system (have an active external document ID).

string

Admin only. Filter by owner name (partial match).

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Document UUID.

string

Document name.

string

Source URL or storage URL.

boolean

Whether the document is active.

boolean

Whether the document is publicly visible.

string

External document identifier used by the voice platform.

string

Owner user ID.

string | null

Folder ID, or null if uncategorized.

object

Show properties

number

File size in bytes.

string

Document type (for example "pdf_upload").

number

Number of pages (PDFs only).

string

Source type.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

object | null

Folder details, if assigned.

object | null

Owner profile (admin mode only).

array

Genies that use this document.

Show item properties

string

Genie ID.

string

Genie name.

string

Genie category.

boolean

Whether the genie is active.

number

Total matching documents.

number

Number of matching documents that have been synced to the knowledge base system (i.e. have an active external document ID). Filters applied to the main query are also applied here.

number

Applied limit.

number

Applied offset.

const response = await ApiService.invoke("knowledge-base", "all", undefined, {
  limit: 50,
  offset: 0,
  filters: {
    searchTerm: "product",
    selectedPrivacy: "public",
    selectedSourceType: "pdf_upload",
  },
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "all",
    "data": {
      "limit": 50,
      "offset": 0,
      "filters": {
        "searchTerm": "product",
        "selectedPrivacy": "public",
        "selectedSourceType": "pdf_upload"
      }
    }
  }'

{
  "resource": "knowledge-base",
  "action": "all",
  "data": {
    "limit": 50,
    "offset": 0,
    "filters": {
      "searchTerm": "product",
      "selectedPrivacy": "public",
      "selectedSourceType": "pdf_upload"
    }
  }
}

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Product Documentation",
        "url": "https://storage.example.com/documents/product-docs.pdf",
        "is_active": true,
        "is_public": true,
        "el_doc_id": "el-doc-123",
        "user_id": "660e8400-e29b-41d4-a716-446655440001",
        "folder_id": null,
        "metadata": {
          "pdf_size": 2048576,
          "type": "pdf_upload",
          "total_pages": 45,
          "source": "pdf_upload"
        },
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z",
        "folder": null,
        "owner": null,
        "dependent_agents": [
          {
            "id": "880e8400-e29b-41d4-a716-446655440003",
            "name": "Customer Support",
            "category": "support",
            "is_active": true
          }
        ]
      }
    ],
    "count": 125,
    "inKBCount": 98,
    "limit": 50,
    "offset": 0
  }
}

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

Show properties

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

object

Show properties

string

Filter by document name (case-insensitive).

string

Filter by visibility: "public" or "private".

string

Filter by document type (for example "pdf_upload", "website").

string

Filter by folder ID. Pass null for uncategorized documents.

string

Filter to documents attached to a specific genie. Pass "all" or omit to include all documents.

string

Admin only. Filter by owner name (partial match).

boolean

default:"false"

Admin only. When true, includes owner profile in each item and allows userId filtering.

string

Admin only. Return documents owned by this user ID.

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Document UUID.

string

Document name.

string | null

External document identifier used by the voice platform, or null if not yet synced.

boolean

Whether the document is publicly visible.

string

ISO 8601 creation timestamp.

object | null

Owner profile — present only when adminMode is true.

number

Total matching documents.

number

Applied limit.

number

Applied offset.

const response = await ApiService.invoke("knowledge-base", "list", undefined, {
  limit: 50,
  offset: 0,
  filters: {
    searchTerm: "FAQ",
    agentId: "550e8400-e29b-41d4-a716-446655440000",
  },
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "knowledge-base",
    "action": "list",
    "data": {
      "limit": 50,
      "offset": 0,
      "filters": {
        "searchTerm": "FAQ"
      }
    }
  }'

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Product FAQ",
        "el_doc_id": "el-doc-123",
        "is_public": true,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "count": 1,
    "limit": 50,
    "offset": 0
  }
}

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

Show properties

boolean

default:"false"

Admin only. Include owner profile information.

boolean

Whether the request succeeded.

object

Show properties

object

Full document object including id, name, url, is_active, is_public, el_doc_id, user_id, folder_id, metadata, folder, owner, dependent_agents, created_at, and updated_at.

const response = await ApiService.invoke(
  "documents",
  "get",
  "770e8400-e29b-41d4-a716-446655440002"
);

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "get",
    "id": "770e8400-e29b-41d4-a716-446655440002"
  }'

{
  "resource": "knowledge-base",
  "action": "get",
  "id": "770e8400-e29b-41d4-a716-446655440002"
}

{
  "success": true,
  "data": {
    "document": {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Product Documentation",
      "url": "https://storage.example.com/documents/product-docs.pdf",
      "is_active": true,
      "is_public": true,
      "el_doc_id": "el-doc-123",
      "user_id": "660e8400-e29b-41d4-a716-446655440001",
      "folder_id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {
        "pdf_size": 2048576,
        "type": "pdf_upload",
        "total_pages": 45,
        "source": "pdf_upload"
      },
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-01-15T10:30:00.000Z",
      "folder": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Documentation",
        "color": "#FF5733",
        "icon": "folder",
        "position": 0
      },
      "owner": null,
      "dependent_agents": [
        {
          "id": "880e8400-e29b-41d4-a716-446655440003",
          "name": "Customer Support",
          "category": "support",
          "is_active": true
        }
      ]
    }
  }
}

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.

object

Show properties

boolean

default:"true"

When true (default), optimised content is tried before falling back to the original parsed content. Set to false to skip the optimised version and fetch the raw parsed content directly.

boolean

Whether the request succeeded.

object

Show properties

string

Document UUID.

string

Document name.

string

The document’s text content.

string

Which content version was returned: "edited" (manual override), "optimized" (processed version), or "parsed" (original extraction).

Non-admin users can only retrieve content for their own documents or documents marked as public. A 404 is returned when no readable content is available yet — the document may still be processing.

const response = await ApiService.invoke({
  resource: "knowledge-base",
  action: "get-content",
  id: "770e8400-e29b-41d4-a716-446655440002",
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "knowledge-base",
    "action": "get-content",
    "id": "770e8400-e29b-41d4-a716-446655440002"
  }'

{
  "success": true,
  "data": {
    "documentId": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Product Documentation",
    "content": "Welcome to Acme Products...\n\nThis guide covers installation, configuration, and troubleshooting.",
    "source": "optimized"
  }
}

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

Show properties

string

Document name. Defaults to "Notes {timestamp}".

string

required

Plain text content for the document.

string

Genie UUID. If provided, the document is automatically attached to this genie.

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"
  }'

{
  "resource": "knowledge-base",
  "action": "create",
  "data": {
    "title": "Company FAQ",
    "content": "Q: What are your hours?\nA: Monday-Friday 9am-5pm.",
    "agentId": "genie-uuid"
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "document": {
      "id": "doc-uuid",
      "name": "Company FAQ",
      "metadata": {
        "source": "notes",
        "status": "pending",
        "stage": "pending_extraction"
      }
    }
  }
}

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

Show properties

string

required

The upload sub-action. One of:

"upload-website" — Extract content from a URL
"scrape-website" — Scrape and parse website content
"extract-youtube" — Extract transcript from a YouTube video
"upload-pdf" — Upload and process a PDF file
"extract-document" — Extract content from various document formats

object

required

Sub-action-specific parameters. For upload-website, pass { "url": "https://..." }.

boolean

Whether the request succeeded.

object

Show properties

object

Show properties

string

New document ID.

string

External document ID used by the voice platform.

string

Extracted document name.

object

Source metadata.

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("knowledge-base", "create", undefined, {
  action: "upload-website",
  data: {
    url: "https://example.com/documentation",
  },
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create",
    "data": {
      "action": "upload-website",
      "data": {
        "url": "https://example.com/documentation"
      }
    }
  }'

{
  "resource": "knowledge-base",
  "action": "create",
  "data": {
    "action": "upload-website",
    "data": {
      "url": "https://example.com/documentation"
    }
  }
}

{
  "success": true,
  "data": {
    "document": {
      "id": "doc-new-id",
      "el_doc_id": "el-doc-123",
      "name": "Extracted Document",
      "metadata": {
        "source": "website",
        "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. 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

Show properties

string

Use "data" to update metadata fields. Can be omitted — when no content field is present, data mode is inferred automatically.

string

New document name. If the document has been synced with the voice platform, it will be renamed there as well.

boolean

Active status.

boolean

Public visibility.

string | null

Folder ID for organization. Pass null to remove from any folder.

boolean

Personal document flag.

string

Admin only. Reassign document ownership to this user ID.

object

Custom metadata key-value pairs. Merged with existing metadata — not overwritten.

boolean

Whether the request succeeded.

object

Show properties

object

The updated document object with all current field values.

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",
  }
);

{
  "resource": "knowledge-base",
  "action": "update",
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "data": {
    "mode": "data",
    "name": "Updated Product Documentation",
    "is_active": true,
    "is_public": false,
    "folder_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "success": true,
  "data": {
    "document": {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "name": "Updated Product Documentation",
      "is_active": true,
      "is_public": false,
      "folder_id": "550e8400-e29b-41d4-a716-446655440000",
      "metadata": {
        "pdf_size": 2048576,
        "type": "pdf_upload",
        "total_pages": 45,
        "source": "pdf_upload"
      },
      "updated_at": "2024-01-15T11:00:00.000Z"
    }
  }
}

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

Show properties

string

Use "content" to replace document content. Can be omitted — when a content string is present, content mode is inferred automatically.

string

required

The new document content (non-empty string).

boolean

default:"true"

When true, content is stored with an _optimized suffix and the document metadata is flagged as optimized. When false, content is stored with an _edited suffix.

boolean

Whether the request succeeded.

object

Show properties

object

Updated document with the new el_doc_id and storage metadata.

string

Either "edited" or "optimized".

string

Path to the stored content file.

string

Signed URL for accessing the content (valid for 7 days).

const response = await ApiService.invoke(
  "documents",
  "update",
  "770e8400-e29b-41d4-a716-446655440002",
  {
    mode: "content",
    content: "Updated document content with revised product information...",
    isOptimized: false,
  }
);

{
  "resource": "knowledge-base",
  "action": "update",
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "data": {
    "mode": "content",
    "content": "Updated document content with revised product information...",
    "isOptimized": false
  }
}

{
  "success": true,
  "data": {
    "document": {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "el_doc_id": "el-doc-new-id",
      "name": "Product Documentation",
      "metadata": {
        "pdf_size": 2048576,
        "type": "pdf_upload",
        "source": "pdf_upload",
        "edited_url": "https://signed.url/documents/edited/product_documentation_edited.txt?expires=..."
      },
      "updated_at": "2024-01-15T11:30:00.000Z"
    },
    "contentType": "edited",
    "storagePath": "documents/edited/product_documentation_edited.txt",
    "signedUrl": "https://signed.url/documents/edited/product_documentation_edited.txt?expires=..."
  }
}

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

Show properties

string[]

required

Array of document UUIDs to update. Must contain at least one ID.

object

required

Fields to apply across all listed documents. At least one field is required. Only the fields you include are written — unspecified fields are left unchanged.

Show properties

boolean

Active status.

boolean

Public visibility.

boolean

Private visibility flag.

string | null

Folder assignment. Pass null to remove from any folder.

string | null

Associates the documents with a specific consumer genie. Pass null to clear the association.

string

Document processing status.

string

Source type override.

string

Admin only. Reassigns document ownership to this user ID.

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.

const response = await ApiService.invoke("knowledge-base", "bulk-update", undefined, {
  documentIds: ["doc-id-1", "doc-id-2", "doc-id-3"],
  updates: {
    is_active: true,
    folder_id: "folder-uuid",
  },
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "bulk-update",
    "data": {
      "documentIds": ["doc-id-1", "doc-id-2", "doc-id-3"],
      "updates": {
        "is_active": true,
        "folder_id": "folder-uuid"
      }
    }
  }'

{
  "resource": "knowledge-base",
  "action": "bulk-update",
  "data": {
    "documentIds": ["doc-id-1", "doc-id-2", "doc-id-3"],
    "updates": {
      "is_active": true,
      "folder_id": "folder-uuid"
    }
  }
}

{
  "success": true,
  "message": "Successfully updated 3 documents",
  "updatedCount": 3,
  "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.

string

required

Must be "knowledge-base"

string

required

Must be "delete"

string

required

The document UUID to delete.

object

Show properties

boolean

default:"false"

When true, skips the step that removes the document from dependent genies after deletion. Use this when you are managing agent knowledge base membership separately or when the document was never synced with any genie.

boolean

Whether the request succeeded.

object

Show properties

string

Confirmation message.

string

The ID of the deleted document.

array

Present only when partial errors occurred during cleanup (for example, storage deletion failed but the database record was removed). The deletion is still considered complete if the database record was removed.

Show item properties

string

Which cleanup step failed (e.g. "storage_deletion", "agent_sync_initiation").

string

Error detail.

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.

const response = await ApiService.invoke({
  resource: "knowledge-base",
  action: "delete",
  id: "770e8400-e29b-41d4-a716-446655440002",
  data: {
    skipAgentSync: false,
  },
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "knowledge-base",
    "action": "delete",
    "id": "770e8400-e29b-41d4-a716-446655440002"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Document deleted successfully",
    "documentId": "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.

string

required

Must be "knowledge-base"

string

required

Must be "attach"

object

required

Show properties

string

required

The genie ID to attach documents to.

array

required

Array of documents to attach.

Show item properties

string

required

Document ID.

string

required

Document name.

string

required

Document type (for example "file", "url").

boolean

Whether the request succeeded.

string

Summary of attached documents.

number

Number of documents successfully attached.

const response = await ApiService.invoke("knowledge-base", "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" },
  ],
});

{
  "resource": "knowledge-base",
  "action": "attach",
  "data": {
    "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" }
    ]
  }
}

{
  "success": true,
  "message": "Attached 2 documents",
  "attachedCount": 2
}

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

Show properties

string

required

The genie ID to detach documents from.

string[]

required

Array of document IDs to remove.

boolean

Whether the request succeeded.

string

Summary of detached documents.

number

Number of documents successfully detached.

const response = await ApiService.invoke("knowledge-base", "detach", undefined, {
  agentId: "550e8400-e29b-41d4-a716-446655440000",
  documentIds: ["doc-id-1", "doc-id-2"],
});

{
  "resource": "knowledge-base",
  "action": "detach",
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "documentIds": ["doc-id-1", "doc-id-2"]
  }
}

{
  "success": true,
  "message": "Detached 2 documents",
  "detachedCount": 2
}

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

Show properties

string

required

The genie ID whose knowledge base will be replaced.

array

required

The new complete set of documents. Pass an empty array to clear the knowledge base.

Show item properties

string

required

Document external ID (voice platform ID).

string

required

Document name.

string

required

Document type (for example "file", "url").

boolean

Whether the request succeeded.

string

Summary of the replacement, including document count.

number

Number of documents in the new knowledge base.

const response = await ApiService.invoke({
  resource: "knowledge-base",
  action: "replace",
  data: {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    documents: [
      { id: "el-doc-id-1", name: "Product FAQ", type: "file" },
      { id: "el-doc-id-3", name: "Return Policy", type: "file" },
    ],
  },
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "replace",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "documents": [
        { "id": "el-doc-id-1", "name": "Product FAQ", "type": "file" },
        { "id": "el-doc-id-3", "name": "Return Policy", "type": "file" }
      ]
    }
  }'

{
  "success": true,
  "message": "Replaced knowledge base with 2 documents",
  "replacedCount": 2
}

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

Show properties

string

External document ID to remove from agents.

string

External document ID to add to agents.

string[]

Specific document IDs to sync. If omitted, syncs all dependent documents.

boolean

default:"false"

When true, skip deletion of the old document from agents (non-destructive update).

boolean

Whether the request succeeded.

object

Show properties

array

Agents that were successfully updated.

Show item properties

string

Genie ID.

boolean

Whether the agent was updated.

array

Agents that failed to update.

number

Total number of dependent agents processed.

const response = await ApiService.invoke(
  "knowledge-base",
  "sync-with-agents",
  undefined,
  {
    oldDocId: "el-doc-abc123def456",
    newDocId: "el-doc-xyz789uvw012",
    preventDeletion: false,
  }
);

{
  "resource": "knowledge-base",
  "action": "sync-with-agents",
  "data": {
    "oldDocId": "el-doc-abc123def456",
    "newDocId": "el-doc-xyz789uvw012",
    "preventDeletion": false
  }
}

{
  "success": true,
  "data": {
    "synced_agents": [
      {
        "agent_id": "880e8400-e29b-41d4-a716-446655440003",
        "updated": true
      }
    ],
    "failed_agents": [],
    "total_agents": 1
  }
}

Clone document

Creates a copy of an existing document.

string

required

clone

string

required

UUID of the document to clone.

Response

Returns the newly created document object.

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

Show properties

string[]

required

Array of document UUIDs to consolidate.

string

Name for the consolidated document.

boolean

When true, deletes the source documents after consolidation.

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

Show properties

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

boolean

Whether the request succeeded.

object

Show properties

array

Full document objects. Same shape as the all action response items, including folder, owner, and dependent_agents.

number

Total matching documents.

number

Applied limit.

number

Applied offset.

const response = await ApiService.invoke("knowledge-base", "outside-workspace", undefined, {
  limit: 50,
  offset: 0,
});

curl -X POST https://api.helpgenie.ai/v1/knowledge-base \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "knowledge-base",
    "action": "outside-workspace",
    "data": {
      "limit": 50,
      "offset": 0
    }
  }'

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440099",
        "name": "Admin Uploaded Guide",
        "is_active": true,
        "is_public": false,
        "user_id": "admin-user-id",
        "folder": null,
        "owner": {
          "id": "admin-user-id",
          "full_name": "Admin User",
          "email": "admin@example.com"
        },
        "dependent_agents": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Support Genie",
            "is_active": true
          }
        ],
        "created_at": "2024-01-10T08:00:00.000Z",
        "updated_at": "2024-01-10T08:00:00.000Z"
      }
    ],
    "count": 1,
    "limit": 50,
    "offset": 0
  }
}

Error codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication token
`INVALID_TOKEN`	401	Token validation failed
`FORBIDDEN`	403	User lacks required permissions
`NOT_FOUND`	404	Document not found
`VALIDATION_ERROR`	400	Invalid request parameters
`INVALID_ACTION`	400	Unknown action for the documents resource
`INTERNAL_ERROR`	500	Server-side error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List all documents

List documents

Get document

Get document content

Create document (text)

Create document (advanced)

Update document (data mode)

Update document (content mode)

Bulk update documents

Delete document

Attach documents to agent

Detach documents from agent

Replace agent knowledge base

Sync documents with agents

Clone document

Response

Consolidate documents

Documents outside workspace

Error codes

​List all documents

​List documents

​Get document

​Get document content

​Create document (text)

​Create document (advanced)

​Update document (data mode)

​Update document (content mode)

​Bulk update documents

​Delete document

​Attach documents to agent

​Detach documents from agent

​Replace agent knowledge base

​Sync documents with agents

​Clone document

​Response

​Consolidate documents

​Documents outside workspace

​Error codes

List all documents

List documents

Get document

Get document content

Create document (text)

Create document (advanced)

Update document (data mode)

Update document (content mode)

Bulk update documents

Delete document

Attach documents to agent

Detach documents from agent

Replace agent knowledge base

Sync documents with agents

Clone document

Response

Consolidate documents

Documents outside workspace

Error codes