API Reference
Complete reference for all LYDOS REST API endpoints. The server runs on port 8888 locally and lydos.ailydian.com in production.
Base URL
http://localhost:8888https://lydos.ailydian.comAuthentication
All API requests require an API key passed as a Bearer token in the Authorization header. Keys can be scoped to specific capabilities: agents, chat, memory, engines, or admin.
# Authenticate once with the CLI — issues a device-bound signed JWT.
# (Programmatic API-key issuance is on the roadmap; use the CLI login today.)
lydos login
# Every protected request carries the bearer token minted by 'lydos login':
curl -H "Authorization: Bearer $LYDOS_TOKEN" \
-H "Content-Type: application/json" \
https://lydos.ailydian.com/api/llm/chatCore Endpoints
The core endpoints provide health monitoring, system status, agent management, task execution, and LLM access. All are available from the root API prefix.
| Method | Path | Description |
|---|---|---|
| GET | /api/health | 29-module health check — returns score, module statuses, uptime, and provider availability |
| GET | /api/v1/status | Full system status: all module states, active task queue, engine catalogue, and LLM provider chain |
| GET | /api/v1/agents | List all 109 registered agents with capabilities, categories, and parameters |
| GET | /api/v1/agents/{id} | Get full details for a specific agent by ID |
| POST | /api/v1/agents/{type}/run | Execute an agent — returns a task ID for async polling |
| GET | /api/v1/tasks/{id} | Poll an async task's status, progress, and result |
| GET | /api/v1/tasks | List all tasks with optional status, agent, and date filters |
| POST | /api/llm/chat | Multi-provider LLM chat with automatic failover (Groq → Z.AI → NIM) |
| POST | /api/memory/store | Store a key/value pair in semantic memory with optional tags and TTL |
| GET | /api/memory/search | FTS5-powered semantic memory search — returns ranked results |
GET /api/health
/api/healthReturns a full 29-module health check with scores, module statuses, LLM provider availability, and server uptime.
{
"status": "operational",
"score": 97,
"uptime_seconds": 172800,
"version": "12.2.0-beta",
"modules": 29,
"agents_available": 109,
"engines_active": 247,
"latency_ms": 12,
"providers": {
"groq": { "status": "ok", "model": "llama-3.3-70b-versatile" },
"zai": { "status": "ok", "model": "glm-4.5-air" },
"nim": { "status": "ok", "model": "nemotron-super-49b-v1" },
"cloudbrain": { "status": "ok", "model": "qwen3-32b" }
},
"module_statuses": {
"kernel_loader": "healthy",
"agent_manager": "healthy",
"llm_router": "healthy",
"semantic_memory": "healthy",
"security_hardening":"healthy"
}
}POST /api/llm/chat
/api/llm/chatMulti-provider LLM chat with automatic 6-provider failover (Groq → Z.AI → Claude → Qwen3 → Mistral → NIM). Supports streaming via Server-Sent Events.
{
"messages": [
{ "role": "user", "content": "Explain multi-agent orchestration" }
],
"model": "llama-3.3-70b-versatile", // optional — uses primary if omitted
"max_tokens": 1024, // optional
"temperature": 0.7, // optional
"stream": false // optional — SSE if true
}{
"content": "Multi-agent orchestration is the coordination of...",
"model": "llama-3.3-70b-versatile",
"provider": "groq",
"tokens": { "prompt": 18, "completion": 256, "total": 274 },
"latency_ms": 1840,
"cost_usd": 0.000082
}POST /api/agents/{type}/run
/api/v1/agents/{type}/runExecute any registered agent by its type ID. Returns immediately with a task ID for async polling.
{
"task": "Scan the repository for top-10 security vulnerabilities",
"params": {
"path": "./src",
"depth": "comprehensive",
"output_format": "json"
},
"timeout_seconds": 120, // optional
"priority": "normal" // optional: low | normal | high
}{
"task_id": "task_01HR7X2NB8KM4...",
"agent": "lydos.sentinel",
"status": "pending",
"created_at": "2026-03-23T10:00:00Z",
"estimated_seconds": 45
}POST /api/memory/store
/api/memory/storePersist a key/value pair in the semantic memory store with optional tags and TTL.
{
"key": "project:auth-analysis",
"value": "JWT tokens expire in 24h, refresh tokens in 30d...",
"tags": ["auth", "jwt", "security"],
"ttl_seconds": 86400 // optional — null = persist forever
}{
"id": "mem_01HR...",
"key": "project:auth-analysis",
"stored_at": "2026-03-23T10:00:00Z",
"expires_at": "2026-03-24T10:00:00Z"
}Control Plane — Multi-Region Routing Logic (deployment topology Q4 2026 planned) & Governance
IPO-grade control surfaces aggregate the sovereign engines into two unified panels. /api/v1/governance covers Q229 multi-region routing logic (deployment topology pending Q4 2026; single-region today), failover-chain selection, region health sampling, and aggregate traffic — backed by Q229 + the in-process region heartbeat sampler. /api/v1/governance covers audit, approvals, financials, AI decisions, SOC 2 readiness, EU AI Act compliance, LSIA risks, and TUP deploy history. Approvals enforce role-diverse quorum (security + ops by default) with KSL signature gating on high/critical risk and an LSIA veto check at request time. Health endpoints are public; everything else requires super_admin or auditor role.
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/governance | Unified governance summary — approvals, audit chains, financials, decisions, compliance, risks, deploys |
Q-Engine Endpoints
Each Q-Series engine exposes its own set of endpoints under the /api/qN/ prefix. The table below lists representative endpoints across 25 key engines. See the full Q-Engine Catalog for all 247 engines and their complete endpoint surfaces.
| Method | Path | Description |
|---|---|---|
| GET | /api/q62/dashboard/agents | Real-time WebSocket agent monitoring — live logs, metrics, pause/kill/redirect controls |
| POST | /api/q155/sentinel/orchestrate | Sentinel Orchestrator — coordinate all 14 sentinel engines in priority swarm mode |
| POST | /api/q159/llm/chat | Universal LLM Gateway — litellm with circuit breaker, per-model budget, and retry |
Rate limiting
Rate limits apply per API key and vary by endpoint category. The Retry-After header is set on 429 responses.
| Endpoint category | Limit | Window |
|---|---|---|
| Health & Status | 600 req | per minute |
| Chat & LLM | 120 req | per minute |
| Agent execution | 60 tasks | per minute |
| Memory operations | 300 req | per minute |
| Q-Engine endpoints | 240 req | per minute |
Error handling
All errors return a JSON body with a detail field. Validation errors (422) include a structured array of field-level messages.
// Standard error response
{
"detail": "Agent 'lydos.sentinel' failed: invalid path './nonexistent'",
"error_code": "AGENT_EXECUTION_ERROR",
"task_id": "task_01HR7X2NB8KM4",
"timestamp": "2026-03-23T10:00:00Z"
}
// Validation error (422) response
{
"detail": [
{
"type": "missing",
"loc": ["body", "task"],
"msg": "Field required",
"input": {}
}
]
}| Status | Meaning | Description |
|---|---|---|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created (POST responses) |
| 400 | Bad Request | Invalid request body or missing required fields |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | Valid key but insufficient scope/role |
| 404 | Not Found | Agent, task, or resource ID not found |
| 422 | Unprocessable Entity | Pydantic validation error — see detail array |
| 429 | Too Many Requests | Rate limit exceeded — see Retry-After header |
| 500 | Internal Server Error | Unexpected engine failure — logged to observability |
| 503 | Service Unavailable | LLM provider unavailable — failover in progress |
OpenAPI specification
The full OpenAPI 3.1 specification is generated automatically by Q196 API Documentation engine and is available at the following endpoints on any running LYDOS server:
localhost:8888/docslocalhost:8888/redoclocalhost:8888/openapi.json