Accept or reject an assistant turn #

Customer's thumbs-up on a chat response triggers auto-ingest of cited sources into the appropriate knowledge base, feeds the dream cycle, and seeds the next ENRN training corpus. Thumbs-down marks the answer low-quality.

curl -X POST https://your-cluster.example.com/api/v1/chat/feedback \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "message_id": "msg-456",
    "verdict": "accept"
  }'

Inspect a file, return suggested params #

Reads the first few KB, detects content type / language / structure, returns suggested chunking + enrichment defaults. No data persisted yet.

curl -X POST https://your-cluster.example.com/api/v1/upload/analyze \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./paper.pdf"
# → {file_id, content_type, language, estimated_chunks,
#    suggested_strategy, suggested_chunk_size, suggested_overlap,
#    suggested_enrichment, extracted_keywords, topic_tags}

Preview what a strategy would produce #

Returns the first 5–10 chunks the chosen strategy would produce, without persisting. Lets the operator adjust before commit.

curl -X POST https://your-cluster.example.com/api/v1/upload/preview-chunks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id":"...","strategy":"semantic","chunk_size":512,"overlap":50}'

Fire the ingestion job #

Persists the file, runs chunking + embedding + enrichment per the chosen params, returns a job id for polling.

curl -X POST https://your-cluster.example.com/api/v1/upload/commit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "...",
    "tenant_id": "default",
    "namespace_id": "ai-papers",
    "strategy": "semantic",
    "chunk_size": 512,
    "overlap": 50,
    "enrichment": {"authors": true, "doi": true, "topic_tags": true}
  }'
# → 202 {job_id, estimated_duration_seconds}

Poll an ingest job #

curl https://your-cluster.example.com/api/v1/upload/jobs/<job_id> \
  -H "Authorization: Bearer $API_KEY"
# → {status, chunks_done, chunks_total, embedding_done, error}

Set chunking strategy for a knowledge base #

Uploads into this namespace skip the suggestion dialog (or pre-fill it with these values).

curl -X POST https://your-cluster.example.com/api/v1/vector/namespaces/<tenant>/<ns>/config \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"strategy":"semantic","chunk_size":512,"chunk_overlap":50}'

Delete multiple documents #

Returns counts of deleted and per-document failure reasons.

curl -X POST https://your-cluster.example.com/api/v1/vector/namespaces/<tenant>/<ns>/bulk-delete \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"doc_ids":["doc-1","doc-2","doc-3"]}'

Re-embed every document #

Used after changing the embedding model or chunking strategy. Background job; poll with the returned job_id.

curl -X POST https://your-cluster.example.com/api/v1/vector/namespaces/<tenant>/<ns>/reindex \
  -H "Authorization: Bearer $API_KEY"
# → 202 {job_id, documents}

View pending ingest jobs #

curl https://your-cluster.example.com/api/v1/vector/ingest-queue \
  -H "Authorization: Bearer $API_KEY"
# → {pending: [{job_id, tenant_id, namespace_id, status}, ...]}

Identify chunks needing re-embed #

Used by the model-upgrade detector. Returns the count and per-namespace breakdown.

curl https://your-cluster.example.com/api/v1/vector/stale-chunks \
  -H "Authorization: Bearer $API_KEY"
# → {count: 12345, by_namespace: {...}}

Preview chunks for an already-stored document #

curl -X POST https://your-cluster.example.com/api/v1/vector/chunk-preview \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"default","namespace_id":"ai-papers","doc_id":"doc-123"}'

Classify a query into an intent class #

Three-tier resolution: base classifier → tenant overlay → LLM fallback when confidence is below threshold. Returns the assigned class with confidence and the source of the decision.

curl -X POST https://your-cluster.example.com/api/v1/router/classify \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"summarise the indemnification clause in contract X"}'

# → {
#     "class": "ContractReview",
#     "confidence": 0.91,
#     "source": "overlay",
#     "fallback_chain": ["base", "overlay"]
#   }

UPSERT a custom intent class #

Add your own intent classes ("PatientTriage", "ContractReview", "AnomalyTrend") alongside the 128 built-ins. Trains an overlay classifier from the labelled examples.

curl -X POST https://your-cluster.example.com/api/v1/router/custom-classes \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "law-firm-acme",
    "class_name": "ContractReview",
    "description": "queries about clause review, redlines, indemnification",
    "examples": ["summarise the indemnification clause in...", "what'\''s the term length on..."]
  }'

List a tenant's custom classes #

curl "https://your-cluster.example.com/api/v1/router/custom-classes?tenant_id=law-firm-acme" \
  -H "Authorization: Bearer $API_KEY"

Remove a custom class #

curl -X DELETE "https://your-cluster.example.com/api/v1/router/custom-classes?tenant_id=law-firm-acme&class_name=ContractReview" \
  -H "Authorization: Bearer $API_KEY"

List audit events #

Hash-chained log of every AI-assisted decision and admin-side mutation. Tamper-evident: events cannot be retroactively edited.

curl "https://your-cluster.example.com/api/v1/audit/events?since=2026-05-01T00:00:00Z&tenant_id=hospital-cardiology" \
  -H "Authorization: Bearer $API_KEY"

Get one event with hash-chain context #

Returns the event detail including prev_hash and this_hash so compliance can verify the chain.

curl https://your-cluster.example.com/api/v1/audit/events/evt-abc123 \
  -H "Authorization: Bearer $API_KEY"

Export a signed JSON slice for auditors #

Returns a signed JSON document (Ed25519 over the events array) the customer hands to their compliance auditor.

curl -X POST https://your-cluster.example.com/api/v1/audit/export \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"since":"2026-01-01T00:00:00Z","until":"2026-12-31T23:59:59Z","tenant_id":"hospital-cardiology"}'

Trust a bundle signing key #

curl -X POST https://your-cluster.example.com/api/v1/bundle/trust \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key_id":"acme-research","public_key":"<base64-ed25519>","label":"Acme research group"}'

Revoke trust #

curl -X DELETE https://your-cluster.example.com/api/v1/bundle/trust/acme-research \
  -H "Authorization: Bearer $API_KEY"

Pull and convert a HuggingFace model #

Pulls a HuggingFace model into local storage and converts to GGUF for native inference or llama.cpp consumption. Long-running; returns a job id.

curl -X POST https://your-cluster.example.com/api/v1/models/convert \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hf_repo": "meta-llama/Llama-3.2-3B-Instruct",
    "quantization": "Q4_K_M"
  }'