Skip to main content
Docs menu: Knowledge bases

API reference

Knowledge bases

Create knowledge bases, upload documents and attach them to agents.

List knowledge bases

GET https://api.telvana.com/knowledge-bases

Retrieve a paginated list of knowledge bases in your workspace. Supports sorting and pagination.

Query parameters

Name Description
page integer Page number (default: 1) (default 1)
pageSize integer Number of items per page (default: 25) (default 25)
sortBy string Field to sort by (default: createdAt) (default createdAt)
sortOrder asc | desc Sort order (default desc)

Example request

curl "https://api.telvana.com/knowledge-bases" \
  -H "x-api-key: $TELVANA_API_KEY"

Response 200

Knowledge bases retrieved successfully. Errors use the format in Errors .

Example response

{
  "data": {
    "knowledgeBases": [
      {
        "id": "kb_abc123",
        "workspaceId": "ws_xyz789",
        "name": "Product Documentation",
        "description": "Documentation for all products",
        "createdAt": "2025-06-01T00:00:00.000Z",
        "updatedAt": "2025-06-15T00:00:00.000Z",
        "_count": {
          "documents": 12,
          "agents": 3
        }
      }
    ],
    "pageCount": 1,
    "pageIndex": 1,
    "pageSize": 25,
    "sortBy": "createdAt",
    "sortOrder": "desc"
  }
}

Create knowledge base

POST https://api.telvana.com/knowledge-bases

Create a new knowledge base. This also creates a corresponding vector collection for document embeddings.

Request body (application/json)

Name Description
name string required
description string required

Example request

curl -X POST "https://api.telvana.com/knowledge-bases" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Documentation",
    "description": "Documentation for all products and services"
  }'

Response 201

Knowledge base created successfully. Errors use the format in Errors .

Example response

{
  "data": {
    "id": "kb_abc123",
    "workspaceId": "ws_xyz789",
    "name": "Product Documentation",
    "description": "Documentation for all products and services",
    "createdAt": "2025-06-01T00:00:00.000Z",
    "updatedAt": "2025-06-01T00:00:00.000Z"
  },
  "message": "Knowledge base created successfully"
}

List knowledge bases for dropdown

GET https://api.telvana.com/knowledge-bases/workspace

Retrieve a lightweight list of knowledge bases in your workspace, suitable for dropdown/selection UI components. Returns only id, name, and description.

Example request

curl "https://api.telvana.com/knowledge-bases/workspace" \
  -H "x-api-key: $TELVANA_API_KEY"

Response 200

Knowledge bases retrieved successfully. Errors use the format in Errors .

Example response

{
  "data": [
    {
      "id": "kb_abc123",
      "name": "Product Documentation",
      "description": "Documentation for all products"
    },
    {
      "id": "kb_def456",
      "name": "FAQ",
      "description": "Frequently asked questions"
    }
  ]
}

Get knowledge base

GET https://api.telvana.com/knowledge-bases/{id}

Retrieve details of a specific knowledge base.

Path parameters

Name Description
id string required Knowledge base ID

Example request

curl "https://api.telvana.com/knowledge-bases/{id}" \
  -H "x-api-key: $TELVANA_API_KEY"

Response 200

Knowledge base retrieved successfully. Errors use the format in Errors .

Example response

{
  "data": {
    "id": "kb_abc123",
    "workspaceId": "ws_xyz789",
    "name": "Product Documentation",
    "description": "Documentation for all products",
    "createdAt": "2025-06-01T00:00:00.000Z",
    "updatedAt": "2025-06-15T00:00:00.000Z"
  }
}

Update knowledge base

PUT https://api.telvana.com/knowledge-bases/{id}

Update the name or description of a knowledge base.

Path parameters

Name Description
id string required Knowledge base ID

Request body (application/json)

Name Description
name string
description string

Example request

curl -X PUT "https://api.telvana.com/knowledge-bases/{id}" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Product Docs",
    "description": "Updated description for the product documentation"
  }'

Response 200

Knowledge base updated successfully. Errors use the format in Errors .

Example response

{
  "data": {
    "id": "kb_abc123",
    "name": "Updated Product Docs",
    "description": "Updated description for the product documentation"
  },
  "message": "Knowledge base updated successfully"
}

Delete knowledge base

DELETE https://api.telvana.com/knowledge-bases/{id}

Delete a knowledge base and all associated data including documents, text chunks, vector embeddings (Qdrant), and files (S3).

Path parameters

Name Description
id string required Knowledge base ID

Example request

curl -X DELETE "https://api.telvana.com/knowledge-bases/{id}" \
  -H "x-api-key: $TELVANA_API_KEY"

Response 200

Knowledge base deleted successfully. Errors use the format in Errors .

Example response

{
  "data": null,
  "message": "Knowledge base deleted successfully"
}

List documents

GET https://api.telvana.com/knowledge-bases/{id}/documents

Retrieve all documents in a knowledge base with chunk count information.

Path parameters

Name Description
id string required Knowledge base ID

Example request

curl "https://api.telvana.com/knowledge-bases/{id}/documents" \
  -H "x-api-key: $TELVANA_API_KEY"

Response 200

Documents retrieved successfully. Errors use the format in Errors .

Fields in data

Name Description
id string
knowledgeBaseId string
filename string
originalName string
fileType PDF | DOCX | TXT | MD | CSV | JSON
fileSize integer File size in bytes
status PENDING | PROCESSING | COMPLETED | FAILED
chunkCount integer | null
errorMessage string | null
createdAt string (date-time)
processedAt string (date-time) | null
_count object
_count.chunks integer

Example response

{
  "data": [
    {
      "id": "doc_abc123",
      "knowledgeBaseId": "kb_abc123",
      "filename": "a1b2c3d4-product-guide.pdf",
      "originalName": "product-guide.pdf",
      "fileType": "PDF",
      "fileSize": 2048576,
      "status": "COMPLETED",
      "chunkCount": 47,
      "errorMessage": null,
      "createdAt": "2025-06-01T00:00:00.000Z",
      "processedAt": "2025-06-01T00:01:30.000Z",
      "_count": {
        "chunks": 47
      }
    }
  ]
}

Upload document

POST https://api.telvana.com/knowledge-bases/{id}/documents

Upload a document to a knowledge base. The document is processed through a pipeline:

  1. Upload — File is stored in S3
  2. Parse — Text is extracted from the file (PDF, DOCX, TXT, MD, CSV, JSON supported)
  3. Chunk — Text is split into ~2200 character chunks with sentence-boundary overlap
  4. Embed — Each chunk is converted to a 3072-dimension vector using Google Gemini embeddings
  5. Index — Vectors are upserted into the Qdrant collection for semantic search

The endpoint returns the document record immediately after processing completes. If parsing or embedding fails, the document is marked as FAILED with an error message.

Supported file types: PDF, DOCX, TXT, MD, CSV, JSON

Maximum file size: 50 MB

Processing happens inside the request, so a large file can take a while to answer. A file with no extractable text, such as a scanned PDF without OCR, ends FAILED.

Path parameters

Name Description
id string required Knowledge base ID

Request body (multipart/form-data)

Name Description
file file required The document file to upload. Supported types: PDF, DOCX, TXT, MD, CSV, JSON. Max size: 50MB.

Example request

curl -X POST "https://api.telvana.com/knowledge-bases/{id}/documents" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -F "file=@./handbook.pdf"

Response 201

Document uploaded and processed successfully. Errors use the format in Errors .

Example response

{
  "data": {
    "id": "doc_abc123",
    "knowledgeBaseId": "kb_abc123",
    "filename": "a1b2c3d4-product-guide.pdf",
    "originalName": "product-guide.pdf",
    "fileType": "PDF",
    "fileSize": 2048576,
    "status": "COMPLETED",
    "chunkCount": 47,
    "processedAt": "2025-06-01T00:01:30.000Z"
  },
  "message": "Document uploaded successfully"
}

Delete document

DELETE https://api.telvana.com/knowledge-bases/documents/{documentId}

Delete a document from a knowledge base. This removes the document from the database, S3 storage, and deletes its vector embeddings from Qdrant.

Path parameters

Name Description
documentId string required Document ID

Example request

curl -X DELETE "https://api.telvana.com/knowledge-bases/documents/{documentId}" \
  -H "x-api-key: $TELVANA_API_KEY"

Response 200

Document deleted successfully. Errors use the format in Errors .

Example response

{
  "data": null,
  "message": "Document deleted successfully"
}

Get agent knowledge bases

GET https://api.telvana.com/agents/{agentId}/knowledge-bases

Retrieve the knowledge bases associated with an agent.

Path parameters

Name Description
agentId string required Agent ID

Example request

curl "https://api.telvana.com/agents/{agentId}/knowledge-bases" \
  -H "x-api-key: $TELVANA_API_KEY"

Response 200

Agent knowledge bases retrieved successfully. Errors use the format in Errors .

Example response

{
  "data": [
    {
      "id": "kb_abc123",
      "workspaceId": "ws_xyz789",
      "name": "Product Documentation",
      "description": "Documentation for all products",
      "createdAt": "2025-06-01T00:00:00.000Z",
      "updatedAt": "2025-06-15T00:00:00.000Z"
    }
  ]
}

Update agent knowledge bases

PUT https://api.telvana.com/agents/{agentId}/knowledge-bases

Replace the set of knowledge bases associated with an agent. Pass an array of knowledge base IDs — all previous associations are removed and replaced with the new set. Pass an empty array to remove all associations.

The list you send replaces the agent's whole set. Send every knowledge base the agent should keep, or an empty list to detach them all.

Path parameters

Name Description
agentId string required Agent ID

Request body (application/json)

Name Description
knowledgeBaseIds array of string required

Example request

curl -X PUT "https://api.telvana.com/agents/{agentId}/knowledge-bases" \
  -H "x-api-key: $TELVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgeBaseIds": [
      "kb_abc123",
      "kb_def456"
    ]
  }'

Response 200

Agent knowledge bases updated successfully. Errors use the format in Errors .

Example response

{
  "data": null,
  "message": "Agent knowledge bases updated successfully"
}