Skip to main content

API Reference

Zyrabit Platform exposes a hardened, evidence-bound REST API for local document ingestion, private inference, structured JSON extraction, and runtime diagnostics.

All endpoints are hosted under /v1 and enforce local Bearer token authentication.


Authentication​

All protected requests must include a valid service token in the Authorization header:

Authorization: Bearer <YOUR_API_TOKEN>

In the standard platform container distribution, this corresponds to the token set via API_KEY (or the dynamic runtime token provided to the web UI).


Core Endpoints​

1. Chat Completion (POST /v1/chat)​

Primary inference and RAG endpoint. Sanitizes PII before inference, searches local BM25/vector indexes, and formats evidence-bound responses.

Request Body (application/json):

{
"text": "What is our internal travel policy?",
"session_id": "optional-session-id",
"document_id": "optional-document-id",
"history": []
}
ParameterTypeRequiredDescription
textstringYesUser question or command.
session_idstringNoID for conversation session context and SQLite WAL persistence.
document_idstringNoScope query to a specific document index.
historyarrayNoPrevious turns in the conversation.

Success Response (200 OK):

{
"response": "According to the travel policy, all flights over 4 hours must be approved...",
"metadata": {
"decision": "hybrid-rag",
"sources": ["travel_policy.pdf"],
"rag_hits": 2,
"provider": "ollama",
"latency_seconds": 0.84,
"tps": 88.5
}
}

2. Document Ingestion (POST /v1/sources/import or POST /v1/ingest)​

Uploads and vectorizes documents (PDF, DOCX, TXT, MD, CSV, Audio) into the sovereign vault.

Request Body (multipart/form-data):

  • file: The binary document file to import.

Success Response (200 OK):

{
"status": "accepted",
"document_id": "doc_9f8e7d",
"job_id": "job_1a2b3c",
"filename": "travel_policy.pdf",
"message": "File accepted. Poll the job until it is indexed and ready for retrieval."
}

3. List Documents (GET /v1/documents)​

Lists all documents currently indexed in the sovereign vault.

Success Response (200 OK):

{
"documents": [
{
"id": "doc_9f8e7d",
"filename": "travel_policy.pdf",
"chunks": 18,
"created_at": "2026-09-14T10:00:00Z"
}
]
}

4. Structured Extraction (POST /v1/extract)​

Extracts schema-conforming JSON entities from unstructured text with automatic schema validation.

Request Body (application/json):

{
"text": "Invoice #10293 for ACME Corp, amount $4,500.00 USD dated 2026-09-12.",
"schema_definition": {
"type": "object",
"properties": {
"invoice_number": { "type": "string" },
"vendor": { "type": "string" },
"amount": { "type": "number" },
"currency": { "type": "string" }
},
"required": ["invoice_number", "vendor", "amount"]
}
}

Success Response (200 OK):

{
"data": {
"invoice_number": "10293",
"vendor": "ACME Corp",
"amount": 4500.0,
"currency": "USD"
},
"valid": true,
"errors": [],
"raw_response": "{\"invoice_number\": \"10293\", ...}",
"model": "qwen2.5:1.5b"
}

5. Health & Diagnostic Receipt (GET /v1/health)​

Returns an operational verification receipt of the platform, vector database, and local inference engine.

Success Response (200 OK):

{
"status": "OPERATIONAL",
"timestamp": "2026-09-20T18:00:00.000000",
"metadata": {
"project": "Zyrabit SLM",
"version": "2.4.4",
"uptime": "1:23:45",
"system": {
"cpu_usage": "12.5%",
"ram_usage": "45.2%",
"platform": "Darwin",
"arch": "arm64"
}
},
"infrastructure": [
{ "id": "core-api", "name": "Zyrabit Core API", "status": "ONLINE", "type": "Runtime" },
{ "id": "vector-db", "name": "ChromaDB Vector Index", "status": "ONLINE", "type": "Persistence", "metrics": { "documents": 5 } },
{ "id": "slm-engine", "name": "Ollama (qwen2.5:1.5b)", "status": "ONLINE", "type": "Inference" }
],
"capabilities": []
}

Error Codes​

HTTP StatusDetailDescription
400 Bad RequestInvalid payloadMissing required fields or unparseable input.
401 UnauthorizedNot authenticated: Bearer token requiredMissing or invalid API key in Authorization header.
404 Not FoundResource not foundThe requested document, job, or session does not exist.
422 UnprocessableValidation ErrorPydantic schema validation failure on request payload.
503 Service UnavailableInference provider is offlineThe local SLM engine (Ollama/vLLM/llama.cpp) is unreachable.