Knowledge (RAG) API

The knowledge data plane ingests documents into a knowledge base (a Qdrant collection) and searches it. Create the knowledge base itself in the panel under Knowledge; these endpoints populate and query it by id.

See Knowledge bases (RAG) for concepts.

#Ingest a document

POST /v1/knowledge/{id}/documents

{ "title": "Returns policy", "source": "handbook", "content": "Items may be returned within 14 days…" }

The content is chunked, embedded (via the model router) and upserted into the vector store.

#Upload a file

POST /v1/knowledge/{id}/files — multipart upload of one file. Supported types: .md, .markdown, .mdx, .txt, .csv, .json, .log, .pdf, .docx (max 25 MB). Text is extracted server-side (BCL-only extractors) and ingested; Markdown has its own extractor that strips syntax and keeps the prose — see knowledge bases. To import a batch, call this once per file, or use the panel's multi-file picker which does exactly that and reports each file's result. The response carries chunks, the number of embedded chunks the document produced.

curl -X POST http://localhost:5300/v1/knowledge/KB_ID/files \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -F "file=@returns-policy.pdf"

#Ingest a URL

POST /v1/knowledge/{id}/url

{ "url": "https://intranet.example.com/policies/returns" }

Relay fetches the page, strips HTML to text, and ingests it.

#Search

POST /v1/knowledge/{id}/search — hybrid retrieval (dense vector + BM25 lexical, blended with MMR for diversity).

{ "query": "how long do I have to return something?", "topK": 4 }

{ "results": [
  { "title": "Returns policy", "text": "Items may be returned within 14 days…", "score": 0.82, "source": "handbook" }
] }

#Using it from an agent

Attach a knowledge base to an agent and Relay retrieves relevant chunks automatically, folding them into the system prompt with [S#] citation tags — no manual search call needed.