API DocsKnowledge Bases

Knowledge Bases

Create knowledge bases via API, upload documents, and perform RAG search.

Knowledge Base API

Create fully managed RAG knowledge bases via API. We handle vectorization, embedding models, and reranking — you don't have to worry about anything.

Supported File Types

Upload various document types and YouTube videos to your knowledge base.

PDF

DOCX

PPTX

XLSX

TXT

CSV

HTML

JSON

PNG

JPG

YouTube

Limits

The following limits apply to knowledge bases.

Resource	Limit
File size	100 MB
Files per KB	30
KBs per user	∞
Tokens per KB	1,000,000

Credits

Only anonymized documents cost credits (1 word = 1 credit). Non-anonymized uploads and searches are free.

Quick Start

Get a RAG-ready knowledge base in four steps:

1Create a knowledge base

2Upload documents

3Wait for processing

4Search your knowledge base

Create

Create Knowledge Base

Create a new knowledge base to organize documents and make them searchable via RAG.

POST/api/v1/knowledge-bases

Parameters

Parameter	Type	Default	Description
`name`required	`string`	-	Name of the knowledge base
`description`	`string`	-	Optional description

Example

1curl -X POST https://app.anymize.ai/api/v1/knowledge-bases \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
3  -H #86efac">"Content-Type: application/json" \
4  -d '{
5    #86efac">"name": "Product Documentation",
6    #86efac">"description": "All product docs"
7  }'

Response

On success, returns the created knowledge base with its ID.

201Created

{
  "success": true,
  "knowledgeBase": {
    "id": "kb_abc123",
    "name": "Product Documentation",
    "description": "All product docs",
    "rag_status": "pending",
    "rag_progress": 0,
    "doc_count": 0,
    "created_at": "2025-01-15T10: 30: 00Z"
  }
}

List

List Knowledge Bases

Lists all knowledge bases you own or have access to.

GET/api/v1/knowledge-bases

Authentication

Use your API key in the Authorization header.

Note

Knowledge bases created via API are also available in the chat — and vice versa.

Response

Returns an array of all knowledge bases with status and statistics.

200OK

{
  "list": [
    {
      "id": "kb_abc123",
      "name": "Product Documentation",
      "description": "All product docs",
      "rag_status": "completed",
      "rag_progress": 100,
      "doc_count": 5,
      "chunk_count": 234,
      "total_tokens": 45200,
      "role": "owner",
      "created_at": "2025-01-15T10: 30: 00Z"
    }
  ],
  "total": 1
}

Response Fields

Each knowledge base includes the following fields.

Field	Type	Description
`id`	`string`	Unique knowledge base ID
`name`	`string`	Knowledge base name
`description`	`string`	Knowledge base description
`rag_status`	`string`	Processing status (pending, processing, completed, failed)
`rag_progress`	`number`	Progress percentage (0–100)
`doc_count`	`number`	Number of documents
`chunk_count`	`number`	Number of chunks created
`total_tokens`	`number`	Total number of tokens
`role`	`string`	Your role (owner, editor, viewer)
`created_at`	`string`	Creation timestamp

Example

1curl https://app.anymize.ai/api/v1/knowledge-bases \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY"

Details

Get Knowledge Base

Retrieve details of a knowledge base, including document list, chunk statistics, and health status.

GET/api/v1/knowledge-bases/{id}

Parameters

Parameter	Type	Default	Description
`id`required	`string`	-	Knowledge base ID

Response

Returns the knowledge base with documents and chunk statistics.

200OK

{
  "knowledgeBase": {
    "id": "kb_abc123",
    "name": "Product Documentation",
    "description": "All product docs",
    "summary": "Contains product guides, API references, and FAQ documents.",
    "rag_status": "completed",
    "health": "healthy",
    "documents": [
      {
        "id": "doc_xyz789",
        "name": "getting-started.pdf",
        "status": "processed",
        "chunk_count": 42,
        "token_count": 8500,
        "created_at": "2025-01-15T10: 35: 00Z"
      }
    ],
    "chunkStats": {
      "total_chunks": 234,
      "total_tokens": 45200,
      "avg_tokens_per_chunk": 193
    },
    "created_at": "2025-01-15T10: 30: 00Z",
    "updated_at": "2025-01-16T14: 20: 00Z"
  }
}

Example

1curl https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123 \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY"

Update Knowledge Base

Update the name or description of a knowledge base.

PATCH/api/v1/knowledge-bases/{id}

Parameters

Parameter	Type	Default	Description
`id`required	`string`	-	Knowledge base ID
`name`	`string`	-	New name
`description`	`string`	-	New description

Response

200OK

{
  "knowledgeBase": {
    "id": "kb_abc123",
    "name": "Updated Documentation",
    "description": "Revised product docs",
    "rag_status": "completed",
    "updated_at": "2025-01-17T09: 15: 00Z"
  }
}

Example

1curl -X PATCH https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123 \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
3  -H #86efac">"Content-Type: application/json" \
4  -d '{
5    #86efac">"name": "Updated Documentation",
6    #86efac">"description": "Revised product docs"
7  }'

Delete Knowledge Base

Delete a knowledge base and all associated embeddings. Only the owner can delete.

DELETE/api/v1/knowledge-bases/{id}

Warning

Deleting removes all embeddings and chunks. The original documents are preserved.

Parameters

Parameter	Type	Default	Description
`id`required	`string`	-	Knowledge base ID

Response

200OK

{
  "success": true
}

Example

1curl -X DELETE https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123 \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY"

Upload Documents

Upload files or YouTube videos to a knowledge base. Supports multipart/form-data for files and application/json for YouTube URLs.

POST/api/v1/knowledge-bases/:id/upload

Upload Modes

The endpoint supports two modes: file upload (multipart/form-data) and YouTube URL (application/json).

Supported File Types

PDF, DOCX, PPTX, XLSX, TXT, MD, CSV, HTML, JSON, PNG, JPG, and other image formats.

File Upload Parameters

Send the file as multipart/form-data with the following fields.

Parameter	Type	Default	Description
`file`required	`File`	-	The file to upload (max 100 MB)
`with_anonymization`	`string`	`"false"`	Anonymize the document before adding to the KB. Costs credits.
`auto_process`	`string`	`"true"`	Automatically start RAG processing when all documents are ready.

Credits

Anonymized uploads cost credits (1 word = 1 credit). Non-anonymized uploads are free.

File Upload Example

1curl -X POST https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123/upload \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
3  -F #86efac">"file=@product-guide.pdf" \
4  -F #86efac">"with_anonymization=false" \
5  -F #86efac">"auto_process=true"

File Upload Response

Returns the job ID and status. Use the status endpoint to check progress.

201Created

{
  "job_id": "job_abc123",
  "status": "pending",
  "filename": "product-guide.pdf",
  "with_anonymization": false,
  "message": "File uploaded to knowledge base"
}

YouTube URL Parameters

Send the YouTube URL as a JSON body.

Parameter	Type	Default	Description
`youtube_url`required	`string`	-	Full YouTube URL (youtube.com/watch?v=..., youtu.be/...)
`auto_process`	`boolean`	`true`	Automatically start RAG processing

Tip

YouTube transcripts are automatically extracted. Processing may take a moment for longer videos.

YouTube Upload Example

1curl -X POST https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123/upload \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
3  -H #86efac">"Content-Type: application/json" \
4  -d '{
5    #86efac">"youtube_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
6    #86efac">"auto_process": true
7  }'

YouTube Upload Response

Returns the job ID, video title, and status.

201Created

{
  "job_id": "job_def456",
  "status": "completed",
  "title": "Product Overview Video",
  "message": "YouTube video added to knowledge base"
}

Manage Documents

List Documents

Lists all documents in a knowledge base with chunk counts and anonymization status.

GET/api/v1/knowledge-bases/:id/documents

Response

Returns an array of documents with metadata.

200OK

{
  "documents": [
    {
      "id": "job_abc123",
      "filename": "product-guide.pdf",
      "status": "completed",
      "is_anonymized": false,
      "chunk_count": 45,
      "added_at": "2025-01-15T10: 30: 00Z"
    }
  ],
  "total": 1
}

Document Fields

Each document includes the following fields.

Field	Type	Description
`id`	`string`	Unique document ID
`filename`	`string`	Document filename
`status`	`string`	Processing status (pending, completed, failed)
`is_anonymized`	`boolean`	Whether the document was anonymized
`chunk_count`	`number`	Number of chunks created
`added_at`	`string`	Timestamp when added to the KB

Example

1curl https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123/documents \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY"

Remove Documents

Remove documents from a knowledge base and delete their embeddings.

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

Parameters

Parameter	Type	Default	Description
`jobIds`required	`string[]`	-	Array of document IDs to remove

Warning

Removed documents lose their embeddings and chunks in this knowledge base.

Example

1curl -X DELETE https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123/documents \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
3  -H #86efac">"Content-Type: application/json" \
4  -d '{
5    #86efac">"jobIds": ["job_abc123", "job_def456"]
6  }'

Response

Returns the number of removed and remaining documents.

200OK

{
  "success": true,
  "removed": 1,
  "remaining": 4
}

Processing

Start Processing

Start RAG processing for a knowledge base. Creates chunks, embeddings, and the hierarchy.

POST/api/v1/knowledge-bases/:id/process

Parameters

Parameter	Type	Default	Description
`buildHierarchy`	`boolean`	`true`	Build multi-level chunk hierarchy (Level 1/2/3)
`generateSummary`	`boolean`	`true`	Generate an AI-powered summary of the KB

Response

Returns the processing status. Use GET to check progress.

202Processing Started

{
  "success": true,
  "status": "processing",
  "message": "Processing started. Use GET to poll status."
}

Note

Processing runs asynchronously. Use the GET endpoint to check progress. Status values: pending, processing, completed, failed.

Example

1curl -X POST https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123/process \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
3  -H #86efac">"Content-Type: application/json" \
4  -d '{
5    #86efac">"buildHierarchy": true,
6    #86efac">"generateSummary": true
7  }'

Check Processing Status

Retrieve the current processing status of a knowledge base.

GET/api/v1/knowledge-bases/:id/process

Response

Returns progress, token counts, and chunk statistics.

200Processing Status

{
  "status": "completed",
  "progress": 100,
  "total_docs": 5,
  "processed_docs": 5,
  "total_tokens": 45200,
  "chunk_count": 234,
  "has_summary": true,
  "error": null
}

Example

1curl https://app.anymize.ai/api/v1/knowledge-bases/kb_abc123/process \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY"

Tip

Add ?force=true to reprocess a KB even if it has already been completed.

Search

Search Knowledge Base

Perform a semantic search with vector search, reranking, and hierarchical enrichment.

POST/api/v1/rag/search

Parameters

Parameter	Type	Default	Description
`knowledgeBaseId`required	`string`	-	ID of the knowledge base to search
`query`required	`string`	-	Search query in natural language
`topK`	`number`	`5`	Number of results (default: 5)
`useHierarchy`	`boolean`	`true`	Hierarchical chunk enrichment for more context
`useReranking`	`boolean`	`true`	Voyage reranker for better relevance

Prerequisite

The knowledge base must have status 'completed' before it can be searched. Returns 422 if not ready.

Response

Returns search results with relevance scores, source citations, and timing statistics.

200Search Results

{
  "query": "How does the product authentication work?",
  "results": [
    {
      "content": "Authentication is handled via OAuth 2.0...",
      "relevance_score": 0.92,
      "metadata": {
        "source_file": "auth-guide.pdf",
        "document_title": "Authentication Guide",
        "page": 3
      }
    }
  ],
  "total": 3,
  "stats": {
    "vector_search_time_ms": 45,
    "reranking_time_ms": 120,
    "total_time_ms": 180
  }
}

Example

1curl -X POST https://app.anymize.ai/api/v1/rag/search \
2  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
3  -H #86efac">"Content-Type: application/json" \
4  -d '{
5    #86efac">"knowledgeBaseId": "kb_abc123",
6    #86efac">"query": "How does authentication work?",
7    #86efac">"topK": 5,
8    #86efac">"useHierarchy": true,
9    #86efac">"useReranking": true
10  }'

MCP Server

Plug your knowledge bases straight into MCP-capable clients (Claude, Cursor, Windsurf, custom agents): the hosted MCP server exposes exactly the retrieval pipeline the anymize chat uses — vector search, reranking, extended context and citation metadata. Transport is MCP Streamable HTTP; every request is answered with a single JSON response.

POST/api/mcp

Authentication

The MCP server accepts API keys only (Authorization: Bearer) — no session cookies. Create your key in the app under Settings → API.

Client setup

1{
2  "mcpServers": {
3    "anymize-knowledge": {
4      "url": "https://app.anymize.ai/api/mcp",
5      "headers": {
6        "Authorization": "Bearer YOUR_API_KEY"
7      }
8    }
9  }
10}

Try it directly with cURL

The endpoint speaks JSON-RPC 2.0 — you can try it without an MCP client, straight from cURL. Every request is a POST with your API key in the Authorization header.

1# 1) Handshake (optional bei stateless Clients)
2curl -X POST https://app.anymize.ai/api/mcp \
3  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
4  -H #86efac">"Content-Type: application/json" \
5  -d #86efac">'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
6
7# 2) Tools auflisten
8curl -X POST https://app.anymize.ai/api/mcp \
9  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
10  -H #86efac">"Content-Type: application/json" \
11  -d #86efac">'{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
12
13# 3) Wissensdatenbanken auflisten
14curl -X POST https://app.anymize.ai/api/mcp \
15  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
16  -H #86efac">"Content-Type: application/json" \
17  -d #86efac">'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_knowledge_bases","arguments":{}}}'
18
19# 4) Suchen (alle bereiten Datenbanken)
20curl -X POST https://app.anymize.ai/api/mcp \
21  -H #86efac">"Authorization: Bearer YOUR_API_KEY" \
22  -H #86efac">"Content-Type: application/json" \
23  -d #86efac">'{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"search_knowledge_base","arguments":{"query":"Wie funktioniert die Authentifizierung?","top_k":5}}}'

Available tools

The server exposes three tools. Typical flow: list_knowledge_bases first, then search_knowledge_base.

Parameter	Type	Default	Description
`list_knowledge_bases`	`tool`	-	Lists every knowledge base your API key can access (own + shared), with processing status.
`get_knowledge_base`	`tool`	-	Loads one knowledge base with its document list (filenames + status).
`search_knowledge_base`	`tool`	-	Semantic search — parameters: query (required), knowledge_base_id (optional, defaults to all ready knowledge bases), top_k (1-20, default 5). Returns scored passages with citation_id.

Citations

Every passage carries citation_id (document UUID), source (filename), chunk_index and score — the same citation metadata as the chat. The citation_instruction in the result tells the model how to cite correctly (always via citation_id, never via filename).

200search_knowledge_base

{
  "status": "success",
  "query": "How does authentication work?",
  "results": [
    {
      "index": 1,
      "content": "Authentication is handled via OAuth 2.0...",
      "score": 0.92,
      "source": "auth-guide.pdf",
      "chunk_index": 3,
      "citation_id": "550e8400-e29b-41d4-a716-446655440000",
      "knowledge_base_id": "kb_abc123"
    }
  ],
  "total": 1,
  "searched_knowledge_bases": 2,
  "citation_instruction": "Use metadata.citation_id (UUID) for chunk_source_id …"
}

Security

API-key auth only (Bearer). Session cookies are deliberately not accepted — the endpoint cannot be attacked via CSRF.
Every tool enforces the same access rights as the REST API: only knowledge bases you own or that are actively shared with you. Searching additionally requires status 'completed'.
The same rate limits apply as for the knowledge-base REST endpoints.