API ReferenceKnowledge Bases

Knowledge Bases

Create and manage knowledge bases for retrieval-augmented generation (RAG). A knowledge base is a collection of documents that can be searched semantically and used as context for chat completions.

Endpoints

POST   https://api.tensoras.ai/v1/knowledge-bases
GET    https://api.tensoras.ai/v1/knowledge-bases
GET    https://api.tensoras.ai/v1/knowledge-bases/{kb_id}
PATCH  https://api.tensoras.ai/v1/knowledge-bases/{kb_id}
DELETE https://api.tensoras.ai/v1/knowledge-bases/{kb_id}

Authentication

Authorization: Bearer tns_your_key_here

Create Knowledge Base

Create a new knowledge base with the specified configuration.

Request

POST /v1/knowledge-bases
ParameterTypeRequiredDefaultDescription
namestringYes—A human-readable name for the knowledge base.
descriptionstringNo""A description of the knowledge base and its contents.
embedding_modelstringNo"bge-large-en-v1.5"The embedding model to use for vectorizing documents.
chunking_strategyobjectNoSee belowConfiguration for how documents are split into chunks.
chunking_strategy.typestringNo"recursive"The chunking algorithm. One of "recursive", "fixed_size", "semantic".
chunking_strategy.chunk_sizeintegerNo512The target size of each chunk in tokens.
chunking_strategy.chunk_overlapintegerNo64The number of overlapping tokens between consecutive chunks.
metadataobjectNo{}Optional key-value metadata to attach to the knowledge base.

Response Body

{
  "id": "kb_abc123",
  "object": "knowledge_base",
  "name": "Product Documentation",
  "description": "Internal product docs and user guides",
  "embedding_model": "bge-large-en-v1.5",
  "chunking_strategy": {
    "type": "recursive",
    "chunk_size": 512,
    "chunk_overlap": 64
  },
  "document_count": 0,
  "chunk_count": 0,
  "status": "active",
  "created_at": 1709123456,
  "updated_at": 1709123456,
  "metadata": {}
}
FieldTypeDescription
idstringThe unique knowledge base identifier.
objectstringAlways "knowledge_base".
namestringThe name of the knowledge base.
descriptionstringThe description of the knowledge base.
embedding_modelstringThe embedding model used for this knowledge base.
chunking_strategyobjectThe chunking configuration.
document_countintegerThe number of documents in the knowledge base.
chunk_countintegerThe total number of chunks across all documents.
statusstringThe status of the knowledge base. One of "active", "indexing", "error".
created_atintegerUnix timestamp of when the knowledge base was created.
updated_atintegerUnix timestamp of the last update.
metadataobjectUser-defined metadata.

List Knowledge Bases

Retrieve a list of all knowledge bases.

Request

GET /v1/knowledge-bases
ParameterTypeRequiredDescription
limitintegerNoMaximum number of results to return. Default: 20, max: 100.
afterstringNoA cursor for pagination. Returns knowledge bases created after this ID.

Response Body

{
  "object": "list",
  "data": [
    {
      "id": "kb_abc123",
      "object": "knowledge_base",
      "name": "Product Documentation",
      "description": "Internal product docs and user guides",
      "embedding_model": "bge-large-en-v1.5",
      "document_count": 42,
      "chunk_count": 1580,
      "status": "active",
      "created_at": 1709123456,
      "updated_at": 1709145056
    }
  ],
  "has_more": false
}

Get Knowledge Base

Retrieve details about a specific knowledge base.

Request

GET /v1/knowledge-bases/{kb_id}
ParameterTypeRequiredDescription
kb_idstringYesThe ID of the knowledge base to retrieve (path parameter).

Response Body

Returns a single knowledge base object (same schema as the create response).

Update Knowledge Base

Update the name, description, or metadata of an existing knowledge base.

Request

PATCH /v1/knowledge-bases/{kb_id}
ParameterTypeRequiredDescription
kb_idstringYesThe ID of the knowledge base to update (path parameter).
namestringNoUpdated name for the knowledge base.
descriptionstringNoUpdated description.
metadataobjectNoUpdated metadata. Merges with existing metadata.

Note: The embedding_model and chunking_strategy cannot be changed after creation, as this would require re-indexing all documents.

Response Body

Returns the updated knowledge base object.

Delete Knowledge Base

Delete a knowledge base and all its associated documents, chunks, and data sources.

Request

DELETE /v1/knowledge-bases/{kb_id}
ParameterTypeRequiredDescription
kb_idstringYesThe ID of the knowledge base to delete (path parameter).

Response Body

{
  "id": "kb_abc123",
  "object": "knowledge_base",
  "deleted": true
}

Examples

Create a Knowledge Base

curl

curl https://api.tensoras.ai/v1/knowledge-bases \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tns_your_key_here" \
  -d '{
    "name": "Product Documentation",
    "description": "Internal product docs and user guides",
    "embedding_model": "bge-large-en-v1.5",
    "chunking_strategy": {
      "type": "recursive",
      "chunk_size": 512,
      "chunk_overlap": 64
    }
  }'

Python

import requests
 
response = requests.post(
    "https://api.tensoras.ai/v1/knowledge-bases",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer tns_your_key_here",
    },
    json={
        "name": "Product Documentation",
        "description": "Internal product docs and user guides",
        "embedding_model": "bge-large-en-v1.5",
        "chunking_strategy": {
            "type": "recursive",
            "chunk_size": 512,
            "chunk_overlap": 64,
        },
    },
)
 
kb = response.json()
print(f"Knowledge Base ID: {kb['id']}")
print(f"Status: {kb['status']}")

Node.js

const response = await fetch("https://api.tensoras.ai/v1/knowledge-bases", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer tns_your_key_here",
  },
  body: JSON.stringify({
    name: "Product Documentation",
    description: "Internal product docs and user guides",
    embedding_model: "bge-large-en-v1.5",
    chunking_strategy: {
      type: "recursive",
      chunk_size: 512,
      chunk_overlap: 64,
    },
  }),
});
 
const kb = await response.json();
console.log(`Knowledge Base ID: ${kb.id}`);
console.log(`Status: ${kb.status}`);

List Knowledge Bases

curl

curl https://api.tensoras.ai/v1/knowledge-bases \
  -H "Authorization: Bearer tns_your_key_here"

Python

import requests
 
response = requests.get(
    "https://api.tensoras.ai/v1/knowledge-bases",
    headers={"Authorization": "Bearer tns_your_key_here"},
)
 
for kb in response.json()["data"]:
    print(f"{kb['id']}: {kb['name']} ({kb['document_count']} docs, {kb['chunk_count']} chunks)")

Node.js

const response = await fetch("https://api.tensoras.ai/v1/knowledge-bases", {
  headers: { Authorization: "Bearer tns_your_key_here" },
});
 
const { data } = await response.json();
for (const kb of data) {
  console.log(`${kb.id}: ${kb.name} (${kb.document_count} docs, ${kb.chunk_count} chunks)`);
}

Update a Knowledge Base

curl

curl -X PATCH https://api.tensoras.ai/v1/knowledge-bases/kb_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tns_your_key_here" \
  -d '{
    "name": "Product Docs v2",
    "description": "Updated product documentation and guides"
  }'

Python

import requests
 
response = requests.patch(
    "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer tns_your_key_here",
    },
    json={
        "name": "Product Docs v2",
        "description": "Updated product documentation and guides",
    },
)
 
kb = response.json()
print(f"Updated: {kb['name']}")

Node.js

const response = await fetch(
  "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123",
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer tns_your_key_here",
    },
    body: JSON.stringify({
      name: "Product Docs v2",
      description: "Updated product documentation and guides",
    }),
  }
);
 
const kb = await response.json();
console.log(`Updated: ${kb.name}`);

Delete a Knowledge Base

curl

curl -X DELETE https://api.tensoras.ai/v1/knowledge-bases/kb_abc123 \
  -H "Authorization: Bearer tns_your_key_here"

Python

import requests
 
response = requests.delete(
    "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123",
    headers={"Authorization": "Bearer tns_your_key_here"},
)
 
result = response.json()
print(f"Deleted: {result['deleted']}")

Node.js

const response = await fetch(
  "https://api.tensoras.ai/v1/knowledge-bases/kb_abc123",
  {
    method: "DELETE",
    headers: { Authorization: "Bearer tns_your_key_here" },
  }
);
 
const result = await response.json();
console.log(`Deleted: ${result.deleted}`);

Error Handling

{
  "error": {
    "message": "Knowledge base 'kb_abc123' not found",
    "type": "not_found_error",
    "param": "kb_id",
    "code": "knowledge_base_not_found"
  }
}
BatchesData Sources