API Reference

This page documents the key API endpoints across Nova’s services. All services also expose interactive Swagger docs at /docs on their respective ports.

Authentication

Nova supports two authentication methods:

Admin secret

Used for privileged operations (key management, service configuration, pod management). Pass via header:

X-Admin-Secret: your-admin-secret

API key

Used for standard operations (task submission, agent interaction, memory queries). Pass via header:

Authorization: Bearer sk-nova-...

or:

X-API-Key: sk-nova-...

When REQUIRE_AUTH=false (the default for development), API key authentication is bypassed.

---

Orchestrator (port 8000)

Agents

# List all agents
curl http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer sk-nova-..."

# Create an agent
curl -X POST http://localhost:8000/api/v1/agents \
  -H "Authorization: Bearer sk-nova-..." \
  -H "Content-Type: application/json" \
  -d '{"config": {"model": "claude-max/claude-sonnet-4-6"}}'

# Update agent config (admin)
curl -X PATCH http://localhost:8000/api/v1/agents/{agent_id}/config \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-max/claude-opus-4"}'

Tasks (interactive)

# Submit a task (synchronous)
curl -X POST http://localhost:8000/api/v1/tasks \
  -H "Authorization: Bearer sk-nova-..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "...",
    "messages": [{"role": "user", "content": "Explain the auth flow"}]
  }'

# Submit a task (SSE streaming)
curl -X POST http://localhost:8000/api/v1/tasks/stream \
  -H "Authorization: Bearer sk-nova-..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "...",
    "messages": [{"role": "user", "content": "Explain the auth flow"}]
  }'

Pipeline tasks (async queue)

# Submit to pipeline queue
curl -X POST http://localhost:8000/api/v1/pipeline/tasks \
  -H "Authorization: Bearer sk-nova-..." \
  -H "Content-Type: application/json" \
  -d '{"user_input": "Fix the login bug in auth.py"}'

# List recent tasks
curl "http://localhost:8000/api/v1/pipeline/tasks?status=running&limit=10" \
  -H "Authorization: Bearer sk-nova-..."

# Get task status
curl http://localhost:8000/api/v1/pipeline/tasks/{task_id} \
  -H "Authorization: Bearer sk-nova-..."

# Cancel a task
curl -X POST http://localhost:8000/api/v1/pipeline/tasks/{task_id}/cancel \
  -H "Authorization: Bearer sk-nova-..."

# Get guardrail findings
curl http://localhost:8000/api/v1/pipeline/tasks/{task_id}/findings \
  -H "Authorization: Bearer sk-nova-..."

# Get code review verdicts
curl http://localhost:8000/api/v1/pipeline/tasks/{task_id}/reviews \
  -H "Authorization: Bearer sk-nova-..."

# Get artifacts
curl http://localhost:8000/api/v1/pipeline/tasks/{task_id}/artifacts \
  -H "Authorization: Bearer sk-nova-..."

# Queue statistics
curl http://localhost:8000/api/v1/pipeline/queue-stats \
  -H "Authorization: Bearer sk-nova-..."

Chat (admin dashboard)

# Stream chat with the primary agent (admin only)
curl -X POST http://localhost:8000/api/v1/chat/stream \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello Nova"}],
    "model": "claude-max/claude-sonnet-4-6"
  }'

The response is an SSE stream. Each chunk is a data: line containing a text delta. The stream ends with data: [DONE]. The X-Session-Id response header can be passed back in subsequent requests to continue the conversation.

Pods

# List all pods
curl http://localhost:8000/api/v1/pods \
  -H "Authorization: Bearer sk-nova-..."

# Create a pod (admin)
curl -X POST http://localhost:8000/api/v1/pods \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research",
    "description": "Information gathering pod",
    "routing_keywords": ["research", "investigate"],
    "sandbox": "workspace"
  }'

# Add agent to pod (admin)
curl -X POST http://localhost:8000/api/v1/pods/{pod_id}/agents \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "researcher", "role": "task", "model": "claude-max/claude-sonnet-4-6"}'

API keys (admin)

# Create a key (raw key shown once in response)
curl -X POST http://localhost:8000/api/v1/keys \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "rate_limit_rpm": 60}'

# List keys
curl http://localhost:8000/api/v1/keys \
  -H "X-Admin-Secret: your-secret"

# Revoke a key
curl -X DELETE http://localhost:8000/api/v1/keys/{key_id} \
  -H "X-Admin-Secret: your-secret"

MCP servers

# List MCP servers
curl http://localhost:8000/api/v1/mcp-servers \
  -H "Authorization: Bearer sk-nova-..."

# Register a server (admin)
curl -X POST http://localhost:8000/api/v1/mcp-servers \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "filesystem",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
    "enabled": true
  }'

# Reload/reconnect a server
curl -X POST http://localhost:8000/api/v1/mcp-servers/{id}/reload \
  -H "X-Admin-Secret: your-secret"

Health

curl http://localhost:8000/health/live    # Liveness
curl http://localhost:8000/health/ready   # Readiness (checks DB + Redis)

---

LLM Gateway (port 8001)

OpenAI-compatible endpoints

# Chat completion (non-streaming)
curl http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-max/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Chat completion (streaming)
curl http://localhost:8001/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-max/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

# List available models
curl http://localhost:8001/v1/models

Nova internal endpoints

# Non-streaming completion
curl -X POST http://localhost:8001/complete \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-max/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# SSE streaming completion
curl -X POST http://localhost:8001/stream \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-max/claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

# Generate embeddings
curl -X POST http://localhost:8001/embed \
  -H "Content-Type: application/json" \
  -d '{"text": "Some text to embed"}'

Health

curl http://localhost:8001/health/live
curl http://localhost:8001/health/ready

---

Memory Service (port 8002)

# Store a memory
curl -X POST http://localhost:8002/api/v1/memories \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Always use parameterized queries for SQL",
    "tier": "procedural",
    "agent_id": "optional-agent-id"
  }'

# Search memories (hybrid semantic + keyword)
curl -X POST http://localhost:8002/api/v1/memories/search \
  -H "Content-Type: application/json" \
  -d '{"query": "SQL injection prevention", "limit": 10}'

# Save a fact (upserts on project_id + category + key)
curl -X POST http://localhost:8002/api/v1/memories/facts \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The auth module uses bcrypt",
    "project_id": "nova",
    "category": "architecture",
    "key": "auth-hashing"
  }'

# Browse memories with pagination
curl "http://localhost:8002/api/v1/memories/browse?tier=semantic&limit=50&offset=0"

# Get a specific memory
curl http://localhost:8002/api/v1/memories/{memory_id}

# Delete a memory
curl -X DELETE http://localhost:8002/api/v1/memories/{memory_id}

# Build agent context
curl -X POST http://localhost:8002/api/v1/memories/{agent_id}/context \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication patterns", "max_tokens": 2000}'

Health

curl http://localhost:8002/health/live
curl http://localhost:8002/health/ready

---

Chat API (port 8080)

WebSocket

Connect to ws://localhost:8080/ws/chat for real-time streaming chat.

With authentication: ws://localhost:8080/ws/chat?token=sk-nova-...

Send a message:

{"type": "user", "content": "Hello Nova", "session_id": "optional"}

Receive messages:

{"type": "system", "session_id": "abc-123"}
{"type": "stream_chunk", "delta": "Hello"}
{"type": "stream_chunk", "delta": "! How"}
{"type": "stream_chunk", "delta": " can I help?"}
{"type": "stream_end"}

Health

curl http://localhost:8080/health/live
curl http://localhost:8080/health/ready

---

Recovery Service (port 8888)

# System status overview
curl http://localhost:8888/api/v1/recovery/status

# List service containers
curl http://localhost:8888/api/v1/recovery/services

# Restart a service (admin)
curl -X POST http://localhost:8888/api/v1/recovery/services/orchestrator/restart \
  -H "X-Admin-Secret: your-secret"

# Create a backup (admin)
curl -X POST http://localhost:8888/api/v1/recovery/backups \
  -H "X-Admin-Secret: your-secret"

# List backups
curl http://localhost:8888/api/v1/recovery/backups

# Restore from backup (admin)
curl -X POST http://localhost:8888/api/v1/recovery/backups/{filename}/restore \
  -H "X-Admin-Secret: your-secret"

# Read env vars (admin, secrets masked)
curl http://localhost:8888/api/v1/recovery/env \
  -H "X-Admin-Secret: your-secret"

# Update env vars (admin)
curl -X PATCH http://localhost:8888/api/v1/recovery/env \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"updates": {"DEFAULT_CHAT_MODEL": "claude-max/claude-sonnet-4-6"}}'

Health

curl http://localhost:8888/health/live
curl http://localhost:8888/health/ready

---

Response format

All services return raw JSON responses (no { data: ... } wrapper). Error responses use standard HTTP status codes with a detail field:

{"detail": "Agent not found"}

Streaming endpoints use Server-Sent Events (SSE) with JSON-encoded data lines:

data: {"delta": "Hello"}

data: {"delta": " world"}

data: [DONE]