API

Knowledge Store & Assistant API: ask your documents, get sources

Add your own documents, search them and ask questions with numbered sources, kept separate for every tenant.

What it does

The Knowledge API is a per-tenant store for documents that an AI model can read. Add text, or upload a text file, PDF or image. PDFs and images go through OCR so scanned pages become searchable.
Search finds the passages closest in meaning to a question. Ask goes one step further. It finds the best passages, hands them to the model and returns an answer with numbered sources, so a person can check where each claim came from.
Answers can draw on two scopes. The platform scope holds Takelan documentation, shared and read-only. The tenant scope holds your own documents. Your tenant comes from your token only, never from the request body, so one tenant cannot read another.
The same service powers the Assistant chat panel in the Takelan web app. Before the panel sends any page context, the browser removes tokens, keys, emails, IPs and ids, and shows you the exact payload first. Chat history stays in the browser session only. The server scrubs the context again and does not log it.
Know the limits. The Assistant and the ask route use the platform model and do not follow your tenant routing policy, so on_prem_only does not apply to them. They still count against your tenant AI budget. Uploads and questions are stored and processed on Takelan infrastructure.

See how it works

Documents in, answers with sources out

Documents become embeddings in a store scoped to your tenant. A question finds the closest passages, the model answers from them, and numbered sources let a person check each claim. The ask route uses the platform model and does not follow on_prem_only.

Example use cases

A help bot grounded in your runbooks

Upload your runbooks and policies. Ask "How do we onboard a new client?" and get an answer with numbered sources your team can click through.

Search scanned paperwork

Upload scanned PDFs and images. OCR turns them into text, and semantic search finds the right page even when the words differ.

Ask the platform docs in plain language

Developers ask about an endpoint and get an answer from the platform documents, with sources, instead of reading the whole reference.

Try it

Add a document

curl -X POST https://app.takelan.com/api/v1/knowledge/documents \
  -H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"title": "Client onboarding runbook", "text": "Step 1: create the tenant..."}'

title and text are required. url and source_id are optional; reusing a source_id replaces that document. Text documents are limited in size, so use the upload route for larger files.

Upload a PDF with OCR

curl -X POST https://app.takelan.com/api/v1/knowledge/documents/upload \
  -H "X-API-Key: $TAKELAN_API_KEY" \
  -F "file=@scan.pdf" -F "ocr=auto" -F "language=eng"

ocr can be auto, force or never. Re-uploading with the same source_id replaces the earlier version.

Ask a question

curl -X POST https://app.takelan.com/api/v1/knowledge/ask \
  -H "X-API-Key: $TAKELAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"question": "How do we onboard a new client?", "top_k": 6, "include_platform": true}'

The reply has an answer and a sources list. Each source has a number, a title, an optional URL and a scope of platform or tenant.

Endpoints

POST /api/v1/knowledge/documents Add or replace a text document in your tenant store.
POST /api/v1/knowledge/documents/upload Upload a text file, PDF or image. OCR is available for PDFs and images.
GET /api/v1/knowledge/documents List your documents.
DELETE /api/v1/knowledge/documents/{source_id} Delete one document.
POST /api/v1/knowledge/search Semantic search. Takes a query and top_k.
POST /api/v1/knowledge/ask Ask a question. Returns an answer plus numbered sources.
GET /api/v1/knowledge/stats Counts for your store.

MCP

The Utils MCP server at https://app.takelan.com/mcp/utils exposes search, ask and list as tools. Upload and platform-ingest routes are excluded from MCP. Adding or deleting documents is a write and needs the tenant writes switch. About MCP

Common questions

Can I build a chatbot over my own documents?

Yes. Add your documents with the Knowledge API, then call /api/v1/knowledge/ask. You get an answer with numbered sources. Each tenant has its own scope, so your documents are not mixed with another tenant.

What file types can I upload?

Text, Markdown, CSV, TSV and log files, plus PDFs and images. PDFs and images can use OCR, which you can set to auto, force or never.

How is my data kept separate from other tenants?

Your tenant comes from your token only. Any tenant id in a request body is ignored. Search only returns platform documents or documents from your own tenant.

Does the Assistant follow my on_prem_only policy?

No. The Assistant and the ask route use the platform model and do not apply the tenant routing policy. Use the AI Gateway API with on_prem_only when you need AI to stay on your own devices.

What does the Assistant send from my screen?

Only what you allow. The browser strips tokens, keys, emails, IPs and ids first and shows you a preview. The server scrubs it again, limits its size and does not log it.

Does it use my AI budget?

Yes. Questions count against your tenant AI budget, even when you have not registered any provider of your own.

Will it auto-import my support tickets?

Not today. Automatic ingest of tickets into the knowledge store is not built. Add documents through the API or the upload route.

All API families | Takelan AI | Pricing