Knowledge bases

Knowledge bases are private, tenant-owned document repositories that power Axon's RAG (Retrieval-Augmented Generation) pipeline. Documents are chunked, embedded, and stored as vectors — entirely within your data residency region.

Create a knowledge base

bash

POST /v1/axon/knowledge-bases

Name	Type	Required	Description
name	string	Yes	Friendly name (e.g. "Security runbooks", "HR policies").
data_residency	string	Yes	au \| us \| eu \| uk \| sg. Cannot be changed after creation.
description	string	No	What this knowledge base contains.
embedding_model	string	No	Embedding model to use. Defaults to "axon-embed-1".
chunk_size	integer	No	Token count per chunk during indexing. Default 512.
chunk_overlap	integer	No	Token overlap between adjacent chunks. Default 64.

bash

curl -X POST https://api.hldgroup.org/v1/axon/knowledge-bases \
  -H "x-internal-secret: <key>" \
  -H "x-tenant-id: ten_01hxyz" \
  -H "x-user-id: usr_01hxyz" \
  -H "x-platform-role: tenant-system-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Security runbooks",
    "description": "Incident response playbooks, SOP docs, and security policies",
    "data_residency": "au",
    "chunk_size": 512,
    "chunk_overlap": 64
  }'

Upload a document

bash

POST /v1/axon/knowledge-bases/:id/documents

Name	Type	Required	Description
filename	string	Yes	File name with extension.
content	string	No	Raw text content (for inline uploads).
source_url	string	No	URL to fetch content from (alternative to content). Axon fetches and stores at indexing time.
mime_type	string	No	text/plain \| text/markdown \| application/pdf \| text/html \| text/csv \| application/json \| application/vnd.openxmlformats-officedocument.wordprocessingml.document. Defaults to text/plain.

bash

curl -X POST https://api.hldgroup.org/v1/axon/knowledge-bases/kb_01hxyz/documents \
  -H "x-internal-secret: <key>" \
  -H "x-tenant-id: ten_01hxyz" \
  -H "x-user-id: usr_01hxyz" \
  -H "x-platform-role: tenant-system-admin" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "ransomware-response-v3.md",
    "mime_type": "text/markdown",
    "content": "# Ransomware Incident Response\n\n## Immediate containment...\n"
  }'

Returns 202 Accepted with status indexing. Subscribe to the axon.document.indexed webhook or poll the documents list for status: "ready".

Document statuses

Name	Type	Required	Description
indexing	status	No	Document is being chunked and embedded. Not yet queryable.
ready	status	No	Document is fully indexed and available for RAG queries.
failed	status	No	Indexing failed (unsupported format, too large, etc.).

List documents

bash

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

Delete a knowledge base

bash

DELETE /v1/axon/knowledge-bases/:id

Permanently deletes the knowledge base and all its documents and vectors. This cannot be undone.

Warning:Document vectors are stored in an isolated, tenant-scoped vector namespace. No other tenant's documents are ever in the same search space as yours.

RAG queries Completions