Skip to main content

API Reference

The Chaos Cypher REST API is served through nginx at http://localhost/api/v1/ (HTTP) or https://localhost/api/v1/ (when TLS is enabled).

Base URL​

http://localhost/api/v1

All endpoints described in this reference are relative to the base URL above.

Authentication​

Chaos Cypher is single-user and local-first. Nginx terminates every request and gates /api/ behind an internal auth_request subrequest to /api/v1/auth/verify. Sessions are HMAC-signed cc_session cookies — no JWT, no bearer tokens, no user management.

On first run, /api/v1/auth/status reports {"setup_needed": true} and the UI shows a one-time setup form that creates the single operator credential. After setup, you log in with that username/password and the cookie is set automatically.

Setup (first run only)​

curl -X POST http://localhost/api/v1/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "s3cureP4ss!"}'

Login​

curl -X POST http://localhost/api/v1/auth/login \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "s3cureP4ss!"}'

Response 200 OK: empty body. The response sets an httpOnly cc_session cookie; pass -b cookies.txt on subsequent requests.

Authenticated requests​

curl http://localhost/api/v1/sources -b cookies.txt

Without the cookie, nginx returns 401 {"error": "authentication_required"} before the request ever reaches Cortex.

Logout​

curl -X POST http://localhost/api/v1/auth/logout -b cookies.txt

Status​

GET /api/v1/auth/status is public and returns {"setup_needed", "authenticated", "username"}. Used by the UI to decide between setup, login, and dashboard.

API keys​

For programmatic access (scripts, Model Context Protocol (MCP) clients), create an API key in Settings. Send it as Authorization: Bearer <key> on any /api/ request; nginx's auth_request accepts it as an alternative to the session cookie. API keys are stored hashed in /data/credentials.json.

Common Patterns​

Pagination​

List endpoints support pagination via query parameters:

ParameterDefaultDescription
page1Page number (1-indexed)
page_size50Records per page (max: 1000)

Example request:

curl "http://localhost:8080/api/v1/sources?page=3&page_size=10"

Example response (list endpoint with pagination metadata):

{
  "items": [
    { "id": "src_abc123", "name": "quarterly-report.pdf", "status": "committed" },
    { "id": "src_def456", "name": "meeting-notes.docx", "status": "indexed" }
  ],
  "total": 47,
  "page": 3,
  "page_size": 10
}
Queue task pagination

The queue task list endpoint uses offset instead of skip and returns a pagination object with additional fields:

{
  "tasks": [...],
  "total": 10,
  "total_in_queue": 3,
  "queues": null,
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 42,
    "total_in_queue": 3,
    "has_more": false
  }
}

Async Operations​

Long-running operations (source processing, exports, extractions) return HTTP 202 Accepted with a task ID:

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Poll the task status until it reaches a terminal state:

curl http://localhost:8080/api/v1/queue/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Task status response:

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "queue": "operations",
  "operation": "process_source",
  "status": "completed",
  "priority": "50",
  "created_at": "2026-03-09T14:30:00Z",
  "started_at": "2026-03-09T14:30:01Z",
  "completed_at": "2026-03-09T14:30:45Z",
  "attempts": "1",
  "metadata": "{\"source_id\": \"src_abc123\"}"
}

Task status values:

StatusDescription
queuedWaiting to be picked up by a worker
runningCurrently being processed
completedFinished successfully
failedProcessing failed (check task result for error details)
cancelledCancelled by user

Once a task is completed, retrieve its result:

curl http://localhost:8080/api/v1/queue/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/result
{
  "result": {
    "source_id": "src_abc123",
    "entities_extracted": 42,
    "relationships_extracted": 18
  }
}

Error Format​

Errors use two formats depending on how they originate.

Domain exceptions (raised by business logic) return a structured body with an error code, message, and optional details:

{
  "error": "NOT_FOUND",
  "message": "Source not found: src_abc123",
  "details": {
    "resource_type": "Source",
    "identifier": "src_abc123"
  }
}

HTTP exceptions (raised directly by endpoints) return a detail field:

{
  "detail": "Source not found"
}

Or for structured HTTP errors:

{
  "detail": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid data provided for source upload"
  }
}

Error Status Codes​

StatusMeaningExample
200SuccessGET request succeeded
201CreatedResource created successfully
202AcceptedAsync operation queued
400Bad requestInvalid input or business rule violation
401UnauthorizedMissing or invalid authentication token
403ForbiddenInsufficient permissions
404Not foundResource does not exist
409ConflictDuplicate resource (e.g., username already taken)
422Unprocessable entityOperation failed due to business logic constraints
429Too many requestsLLM provider rate limit exceeded
500Internal server errorUnexpected failure
503Service unavailableExternal service down (Valkey, LLM provider)

Error Examples​

400 Bad Request -- validation error:

{
  "error": "VALIDATION_ERROR",
  "message": "Workflow name is required",
  "details": {
    "field": "name"
  }
}

404 Not Found -- resource does not exist:

{
  "error": "NOT_FOUND",
  "message": "Workflow not found: wf_abc123",
  "details": {
    "resource_type": "Workflow",
    "identifier": "wf_abc123"
  }
}

409 Conflict -- duplicate resource:

{
  "error": "CONFLICT",
  "message": "Username already exists"
}

422 Unprocessable Entity -- business logic constraint:

{
  "error": "OPERATION_ERROR",
  "message": "Cannot delete workflow with active executions",
  "details": {
    "operation": "delete_workflow"
  }
}

500 Internal Server Error -- unexpected failure:

{
  "detail": {
    "code": "OPERATION_FAILED",
    "message": "An unexpected error occurred. Please contact support if this persists."
  }
}

API Sections​

SectionBase PathDescription
Health/healthSystem health monitoring and subsystem status
Auth/authUser registration, login, JWT tokens, and user management
Sources/sourcesDocument upload, processing, chunking, extraction, and tagging
Nodes/nodesKnowledge graph nodes (entities)
Edges/edgesKnowledge graph relationships
Graph/graphGraph queries and visualization data
Grounding/graph/groundingEntity grounding and linking
Search/searchFull-text and semantic search
Chat/chatsConversations and AI chat
Workflows/workflowsAutomation workflows and executions
Tools/toolsTool registry for workflow steps
Triggers/triggersEvent-based workflow triggers
Templates/templatesKnowledge graph node and edge schema templates
Lexicon/lexiconDomain vocabulary and term management
Quality/qualitySource and extraction quality scoring
Databases/databasesMulti-database management
Queue/queueTask queue management and monitoring
Exports/exportsData export operations
LLM/llmLLM provider configuration and model listing
Counts/countsAggregate counts across resources
Pause/sources, /system/processingPer-source and system-wide pause / resume controls
Settings/settingsApplication configuration
Backup/backupDatabase backup operations
Logs/logsContainer service logs (all-in-one deployment)
Diagnostics/diagnosticsDiagnostic bundle export for troubleshooting
Edition/editionEdition info, license status, and feature list