Knowledge Bases

Knowledge bases let you upload documents that your AI voice flows can reference during live calls. When a caller asks a question, the system embeds their speech, retrieves the most relevant passages from your documents, and injects that context into the LLM — keeping responses accurate and grounded without sending the entire document on every turn.

How it works: At upload time, documents are parsed, split into ~400-word chunks, and embedded using Gemini text-embedding-004. At call time, the caller's speech is embedded and the top 4 most similar chunks (cosine similarity ≥ 0.5) are prepended to the LLM input.

Supported File Types

Format	Extension	Best for
PDF	`.pdf`	Product manuals, policy documents, reports
Word	`.docx`	Procedures, FAQs, scripts
Plain text	`.txt`	Simple reference content
Markdown	`.md`	Technical documentation
CSV	`.csv`	FAQs, product catalogs, Q&A pairs
PowerPoint	`.pptx`	Slide decks, presentations
HTML	`.html`, `.htm`	Web-exported pages

Maximum file size: 20 MB per upload.

The KnowledgeBase Object

{
  "id": "kb_abc123",
  "name": "Product FAQ",
  "description": "Covers pricing, features, and cancellation policy",
  "organizationId": 1,
  "createdAt": "2026-04-01T10:00:00.000Z",
  "updatedAt": "2026-04-01T10:00:00.000Z",
  "_count": {
    "documents": 3
  }
}

The KnowledgeBaseDocument Object

{
  "id": "doc_xyz789",
  "filename": "product-faq.pdf",
  "fileType": "pdf",
  "fileSize": 204800,
  "chunkCount": 42,
  "knowledgeBaseId": "kb_abc123",
  "createdAt": "2026-04-01T10:05:00.000Z"
}

Field	Description
`chunkCount`	Number of indexed chunks. `0` means indexing is still in progress.
`fileSize`	Size in bytes.
`fileType`	Detected type: `pdf`, `docx`, `txt`, `md`, `csv`, `pptx`, or `html`.

List Knowledge Bases

GET /v1/knowledge-bases

Returns all knowledge bases for your organization, ordered by most recently created.

Response:

[
  {
    "id": "kb_abc123",
    "name": "Product FAQ",
    "description": "Covers pricing, features, and cancellation policy",
    "organizationId": 1,
    "_count": { "documents": 3 },
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-01T10:00:00.000Z"
  }
]

Get a Knowledge Base

GET /v1/knowledge-bases/:id

Returns the knowledge base with its full document list.

Response:

{
  "id": "kb_abc123",
  "name": "Product FAQ",
  "description": "Covers pricing, features, and cancellation policy",
  "organizationId": 1,
  "documents": [
    {
      "id": "doc_xyz789",
      "filename": "product-faq.pdf",
      "fileType": "pdf",
      "fileSize": 204800,
      "chunkCount": 42,
      "createdAt": "2026-04-01T10:05:00.000Z"
    }
  ],
  "createdAt": "2026-04-01T10:00:00.000Z",
  "updatedAt": "2026-04-01T10:00:00.000Z"
}

Create a Knowledge Base

POST /v1/knowledge-bases

Request body:

{
  "name": "Product FAQ",
  "description": "Covers pricing, features, and cancellation policy"
}

Field	Type	Required	Description
`name`	string	Yes	Display name for the knowledge base
`description`	string	No	Optional description of the content

Response: The created KnowledgeBase object (HTTP 201).

Update a Knowledge Base

PATCH /v1/knowledge-bases/:id

Request body (all fields optional):

{
  "name": "Updated FAQ",
  "description": "Now covers returns and refunds too"
}

Response: The updated KnowledgeBase object.

Delete a Knowledge Base

DELETE /v1/knowledge-bases/:id

Deletes the knowledge base along with all its documents and indexed chunks. This cannot be undone.

⚠️

Any flows that reference this knowledge base will have their knowledgeBaseId set to null automatically. They will continue to work but without RAG context.

Response: HTTP 204 No Content.

Upload a Document

POST /v1/knowledge-bases/:id/documents
Content-Type: multipart/form-data

Upload a file to a knowledge base. The file is parsed and indexed asynchronously — the endpoint returns immediately while embedding runs in the background.

Form fields:

Field	Type	Description
`file`	file	The document to upload (max 20MB)

Example (cURL):

curl -X POST https://api.oliai.in/v1/knowledge-bases/kb_abc123/documents \
  -H "x-api-key: sk_live_your_key" \
  -F "file=@/path/to/product-faq.pdf"

Response:

{
  "id": "doc_xyz789",
  "filename": "product-faq.pdf",
  "fileType": "pdf",
  "fileSize": 204800,
  "chunkCount": 0,
  "knowledgeBaseId": "kb_abc123",
  "storageKey": "1/doc_xyz789.pdf",
  "createdAt": "2026-04-01T10:05:00.000Z"
}

chunkCount will be 0 immediately after upload. Poll GET /v1/knowledge-bases/:id to check when indexing is complete — chunkCount will update once all chunks are embedded.

Delete a Document

DELETE /v1/knowledge-bases/:id/documents/:docId

Removes the document and all its indexed chunks from the knowledge base.

Response: HTTP 204 No Content.

Attaching a Knowledge Base to a Flow

Set the knowledgeBaseId field when creating or updating a flow:

PATCH /v1/flows/:flowId

{
  "knowledgeBaseId": "kb_abc123"
}

To detach a knowledge base from a flow:

{
  "knowledgeBaseId": null
}

Once attached, every caller utterance on that flow will trigger a semantic search against the knowledge base. The top matching chunks are automatically prepended to the LLM context for that turn.

Error Responses

Status	Code	Description
400	`BAD_REQUEST`	Unsupported file type or file exceeds 20MB
404	`NOT_FOUND`	Knowledge base or document not found
403	`FORBIDDEN`	Knowledge base belongs to a different organization

Voice Flows Imports