Knowledge Base

The knowledge base lets you upload documents and web links that your agents can reference during conversations. When a caller asks a question, the agent searches its linked documents to provide accurate, grounded answers.

How it works

Upload Document ──> Link to Agent ──> Agent uses it in calls
       │                  │
   (file or URL)    (auto-synced)

Upload a file or add a web link to create a document
Link the document to one or more agents
The document is automatically synced to the agent’s knowledge base
During calls, the agent searches linked documents to answer questions

Supported file types

Type	MIME Type	Max Size
PDF	`application/pdf`	50 MB
Word (.docx)	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`	50 MB
Excel (.xlsx)	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`	50 MB
Excel Macro (.xlsm)	`application/vnd.ms-excel.sheet.macroEnabled.12`	50 MB
Plain text	`text/plain`	50 MB
Markdown	`text/markdown`	50 MB
PNG image	`image/png`	50 MB
JPEG image	`image/jpeg`	50 MB
GIF image	`image/gif`	50 MB
WebP image	`image/webp`	50 MB

Upload a file document

Uploading a file is a three-step process: get a presigned URL, upload the file, then confirm the upload.

Get a presigned upload URL

Call POST /documents/upload with the file metadata. This creates a document record in uploading status and returns a presigned upload URL.

curl -X POST https://api.vocobase.com/api/v2/documents/upload \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product FAQ.pdf",
    "file_size": 1048576,
    "mime_type": "application/pdf"
  }'

{
  "success": true,
  "data": {
    "document_id": "d1234567-abcd-1234-abcd-123456789012",
    "upload_url": "https://uploads.example.com/path?signature=...",
    "expires_in": 900
  }
}

The upload_url expires in 15 minutes (900 seconds). Upload your file before it expires.

Upload the file

Use the presigned URL to upload your file with a PUT request. Set the Content-Type header to match the mime_type you specified.

curl -X PUT "https://uploads.example.com/path?signature=..." \
  -H "Content-Type: application/pdf" \
  --data-binary @"Product FAQ.pdf"

This request goes directly to the presigned upload URL, not to the Vocobase API. Do not include the Authorization header.

Confirm the upload

After the file is uploaded, call POST /documents/{id}/confirm to finalize. Vocobase verifies the file exists and transitions the document status from uploading to ready.

curl -X POST https://api.vocobase.com/api/v2/documents/d1234567-abcd-1234-abcd-123456789012/confirm \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "id": "d1234567-abcd-1234-abcd-123456789012",
    "name": "Product FAQ.pdf",
    "type": "file",
    "mime_type": "application/pdf",
    "file_size": 1048576,
    "status": "ready",
    "created_at": "2026-03-15T10:30:00.000Z",
    "updated_at": "2026-03-15T10:30:05.000Z"
  }
}

The document is now ready and can be linked to agents.

Add a web link document

Web links are simpler — no upload step is needed. The document is immediately ready.

curl -X POST https://api.vocobase.com/api/v2/documents/web-link \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Blog",
    "url": "https://example.com/blog",
    "description": "Our latest blog posts and announcements"
  }'

{
  "success": true,
  "data": {
    "id": "d2345678-abcd-1234-abcd-123456789012",
    "name": "Company Blog",
    "type": "web_link",
    "url": "https://example.com/blog",
    "description": "Our latest blog posts and announcements",
    "status": "ready",
    "created_at": "2026-03-15T10:35:00.000Z",
    "updated_at": "2026-03-15T10:35:00.000Z"
  }
}

The URL content is fetched and stored as a text snapshot when you create the document. The agent uses this snapshot during conversations.

Add a paragraph document

Paragraphs let you add custom text content directly without uploading a file. This is useful for FAQs, product descriptions, or any text you want the agent to reference.

curl -X POST https://api.vocobase.com/api/v2/documents/paragraph \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Return Policy",
    "content": "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
    "description": "Company return policy summary"
  }'

{
  "success": true,
  "data": {
    "id": "d3456789-abcd-1234-abcd-123456789012",
    "name": "Return Policy",
    "type": "paragraph",
    "description": "Company return policy summary",
    "status": "ready",
    "created_at": "2026-03-15T10:40:00.000Z",
    "updated_at": "2026-03-15T10:40:00.000Z"
  }
}

Paragraph content is limited to 50,000 characters. For longer content, consider uploading a text or markdown file.

Link documents to an agent

Once your documents are in ready status, link them to an agent to add them to its knowledge base:

curl -X POST https://api.vocobase.com/api/v2/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": [
      "d1234567-abcd-1234-abcd-123456789012",
      "d2345678-abcd-1234-abcd-123456789012"
    ]
  }'

{
  "success": true,
  "data": {
    "linked": [
      { "document_id": "d1234567-abcd-1234-abcd-123456789012", "sync_status": "pending" },
      { "document_id": "d2345678-abcd-1234-abcd-123456789012", "sync_status": "pending" }
    ],
    "skipped": []
  }
}

The response tells you which documents were newly linked and which were skipped (already linked). Indexing starts for each newly linked document.

You can link up to 20 documents per request
Each agent supports up to 100 linked documents total
Duplicate links are silently skipped (the operation is idempotent)

Sync statuses

After linking a document to an agent, it goes through a sync process. You can check the sync status by listing the agent’s documents.

Status	Description
`pending`	Document is queued for indexing. This is the initial state after linking.
`synced`	Document has been successfully indexed into the agent’s knowledge base. The agent can now use it during conversations.
`failed`	Indexing failed. Check the document content and try unlinking and re-linking.

An agent cannot use a document during calls until its sync status is synced. Allow a few seconds after linking for the sync to complete.

List and manage documents

List all documents

curl -X GET "https://api.vocobase.com/api/v2/documents?limit=10&offset=0" \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "d1234567-abcd-1234-abcd-123456789012",
        "name": "Product FAQ.pdf",
        "type": "file",
        "status": "ready",
        "agent_count": 2,
        "created_at": "2026-03-15T10:30:00.000Z"
      },
      {
        "id": "d2345678-abcd-1234-abcd-123456789012",
        "name": "Company Blog",
        "type": "web_link",
        "status": "ready",
        "agent_count": 1,
        "created_at": "2026-03-15T10:35:00.000Z"
      }
    ],
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}

Get a single document

Fetching a single document also returns a download URL (for files) and the list of linked agents with their sync statuses:

curl -X GET https://api.vocobase.com/api/v2/documents/d1234567-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "id": "d1234567-abcd-1234-abcd-123456789012",
    "name": "Product FAQ.pdf",
    "type": "file",
    "status": "ready",
    "download_url": "https://downloads.example.com/path?signature=...",
    "agents": [
      { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Sales Assistant", "sync_status": "synced" },
      { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Support Bot", "sync_status": "pending" }
    ]
  }
}

List an agent’s linked documents

curl -X GET https://api.vocobase.com/api/v2/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

Update a document

You can rename a document or update its description:

curl -X PUT https://api.vocobase.com/api/v2/documents/d1234567-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product FAQ v2.pdf",
    "description": "Updated product FAQ for Q1 2026"
  }'

Unlink and delete documents

Unlink a document from an agent

Unlinking removes the document from the agent’s knowledge base but does not delete the document itself. You can re-link it later.

curl -X DELETE https://api.vocobase.com/api/v2/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/d1234567-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "message": "Document unlinked from agent"
  }
}

Delete a document permanently

Deleting a document removes the stored file if applicable, unlinks it from all agents, and deletes the record. This action is irreversible.

curl -X DELETE https://api.vocobase.com/api/v2/documents/d1234567-abcd-1234-abcd-123456789012 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "message": "Document deleted successfully"
  }
}

Deleting a document permanently removes it from all agents’ knowledge bases. This action cannot be undone.

API reference

Method	Endpoint	Description
`POST`	`/documents/upload`	Get a presigned upload URL
`POST`	`/documents/{id}/confirm`	Confirm file upload
`POST`	`/documents/web-link`	Add a web link document
`POST`	`/documents/paragraph`	Add a paragraph (text) document
`GET`	`/documents`	List all documents
`GET`	`/documents/{id}`	Get document with download URL
`PUT`	`/documents/{id}`	Update name/description
`DELETE`	`/documents/{id}`	Delete permanently
`GET`	`/agent/{id}/documents`	List agent’s linked documents
`POST`	`/agent/{id}/documents`	Link documents to agent
`DELETE`	`/agent/{agentId}/documents/{documentId}`	Unlink from agent

Getting Started

Guides

Partner Onboarding

API Reference

Webhooks

Telephony

Knowledge Base

Knowledge Base

How it works

Supported file types

Upload a file document

Add a web link document

Add a paragraph document

Link documents to an agent

Sync statuses

List and manage documents

List all documents

Get a single document

List an agent’s linked documents

Update a document

Unlink and delete documents

Unlink a document from an agent

Delete a document permanently

API reference

Next steps

Create an Agent

Webhook Payloads

​Knowledge Base

​How it works

​Supported file types

​Upload a file document

​Add a web link document

​Add a paragraph document

​Link documents to an agent

​Sync statuses

​List and manage documents

​List all documents

​Get a single document

​List an agent’s linked documents

​Update a document

​Unlink and delete documents

​Unlink a document from an agent

​Delete a document permanently

​API reference

​Next steps

Create an Agent

Webhook Payloads

Knowledge Base

How it works

Supported file types

Upload a file document

Add a web link document

Add a paragraph document

Link documents to an agent

Sync statuses

List and manage documents

List all documents

Get a single document

List an agent’s linked documents

Update a document

Unlink and delete documents

Unlink a document from an agent

Delete a document permanently

API reference

Next steps