The complete
endpoint surface.

OpenAI-shaped curl

curl https://your-cluster.example.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b",
    "messages": [{"role":"user","content":"Hello."}],
    "stream": true
  }'

OpenAI Python SDK

from openai import OpenAI
client = OpenAI(
    base_url="https://your-cluster.example.com/v1",
    api_key="$API_KEY",
)
resp = client.chat.completions.create(
    model="llama-3.3-70b",
    messages=[{"role":"user","content":"Hello."}],
)
print(resp.choices[0].message.content)

Eldric-native agent invocation

curl -X POST https://your-cluster.example.com/api/v1/agent/chat \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Summarise the new contract attachments",
    "knowledge_base_id": "kb-contracts-2026"
  }'

Intelligent upload — analyse → preview → commit → poll

Customers drag a file in; the platform inspects it, suggests chunking and enrichment parameters, lets the user preview the chunks, then commits with the chosen params. Backed by four endpoints.

# 1. Analyse a file — get suggested params back
curl -X POST https://your-cluster.example.com/api/v1/upload/analyze \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./paper.pdf"
# → returns {content_type, language, estimated_chunks, suggested_strategy,
#            suggested_enrichment, extracted_keywords, ...}

# 2. Preview the chunks a given strategy would produce
curl -X POST https://your-cluster.example.com/api/v1/upload/preview-chunks \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./paper.pdf" \
  -F "strategy=semantic" -F "chunk_size=512" -F "overlap=50"
# → returns first 5–10 chunks for review

# 3. Commit the ingestion job with the chosen params
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": "...",  // from /analyze
    "tenant_id": "default",
    "namespace_id": "ai-papers",
    "strategy": "semantic",
    "chunk_size": 512,
    "overlap": 50,
    "enrichment": {"authors": true, "doi": true, "topic_tags": true}
  }'
# → returns {job_id, estimated_duration_seconds}

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

Per-namespace chunking config

Set the default chunking strategy at the knowledge-base level. Uploads into that namespace skip the suggestion dialog (or pre-fill it).

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 '{
    "chunk_size": 512,
    "chunk_overlap": 50,
    "strategy": "semantic"
  }'

Retention loop — accept / reject signal

Customer's thumbs-up on an assistant turn triggers the retention loop: cited sources auto-ingest into the knowledge base, the session feeds the dream cycle, and hot patterns become candidates for the next training corpus.

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"          // or "reject"
  }'

Router — classify a query

Returns the assigned intent class with a confidence score and the source of the decision (base classifier, overlay, or LLM-fallback). Useful for debugging routing and surfacing classification in admin dashboards.

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"]
#   }

Router — custom intent classes (per-tenant)

Pro+. Admin role + tenant boundary. Register your own intent classes ("PatientTriage", "ContractReview", "AnomalyTrend") alongside the 128 built-ins. The classifier consults the overlay when the base is below confidence threshold.

# UPSERT a class
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 the tenant's taxonomy
curl https://your-cluster.example.com/api/v1/router/custom-classes?tenant_id=law-firm-acme \
  -H "Authorization: Bearer $API_KEY"

# Remove one 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"

All endpoints above gate on the rag capability (Standard tier and above per the license catalogue). Writes additionally require the admin role inside the requesting tenant; reads are scoped to the tenant boundary at the gateway. The customer-facing how-to pages for the same surface live at using RAG, chunking strategies, RAG on demand and custom classification.