API Reference

Layerr exposes a comprehensive HTTP API with 135 routes across 8 categories. All routes flow through the central server (server.ts) and are protected by gateway middleware unless otherwise noted.

Response Format

All API responses follow a consistent envelope:

{
  "data": { ... },
  "meta": {
    "requestId": "uuid",
    "timestamp": "2026-01-15T10:30:00Z",
    "workspaceId": "workspace-slug"
  }
}

Error responses include:

{
  "error": {
    "code": "PROVIDER_UNAVAILABLE",
    "message": "All providers in fallback chain exhausted",
    "details": { "attempts": 3, "providers": ["openai", "anthropic", "ollama"] }
  }
}

Authentication

All routes (except health checks) require a valid workspace API key passed via the Authorization: Bearer <key> header. Keys are validated by the gateway middleware (security/gateway/middleware.ts).

Rate Limiting

Per-workspace rate limits are enforced by the gateway:

Tier	Requests/minute	Burst
Free	60	10
Standard	300	50
Enterprise	2000	200

---

OpenAI-Compatible Routes

These routes implement the OpenAI API specification, allowing existing clients to use Layerr as a drop-in replacement.

Route	Method	Description
/v1/chat/completions	POST	Main chat completions endpoint. Accepts OpenAI-format requests, routes through Layerr intelligence
/v1/models	GET	List available models across all configured providers
/v1/models/{model}	GET	Get details for a specific model

/v1/chat/completions

Request body (OpenAI-compatible with Layerr extensions):

{
  "model": "layerr-auto",
  "messages": [{"role": "user", "content": "Write a React component"}],
  "stream": true,
  "layerr": {
    "strategy": "quality",
    "fallback": "relaxed",
    "explain": true
  }
}

Layerr extensions (all optional):

Field	Type	Description
layerr.strategy	string	Override strategy: cost, speed, quality, balanced
layerr.fallback	string	Fallback mode: strict, relaxed, none
layerr.explain	boolean	Include routing explanation in response headers
layerr.workspace	string	Target workspace slug (for admin keys)

---

Chat & Conversation Routes

Route	Method	Description
/api/chat	POST	Layerr-native chat endpoint with full orchestration
/api/conversations	GET	List conversation history
/api/conversations/{id}	GET	Get a specific conversation
/api/conversations/{id}	DELETE	Delete a conversation
/api/conversations/{id}/messages	POST	Add a message to a conversation

/api/chat

The native chat endpoint provides more control than the OpenAI-compatible route:

Request body:

{
  "messages": [{"role": "user", "content": "Refactor this to TypeScript"}],
  "context": {
    "files": ["src/App.js", "src/types.ts"]
  },
  "preferences": {
    "strategy": "quality",
    "maxCost": 0.50,
    "maxLatency": 30000
  }
}

---

Provider Management Routes

Route	Method	Description
/api/providers	GET	List all configured providers
/api/providers	POST	Add a new provider connection
/api/providers/{id}	GET	Get provider details
/api/providers/{id}	PATCH	Update provider configuration
/api/providers/{id}	DELETE	Remove a provider
/api/providers/{id}/health	GET	Get provider health status
/api/providers/{id}/test	POST	Test provider connectivity
/api/providers/discover	GET	Auto-discover local providers (Ollama, etc.)
/api/providers/capabilities	GET	Get capability matrix for all providers

Provider Object

{
  "id": "openai-prod",
  "name": "OpenAI Production",
  "type": "openai",
  "baseUrl": "https://api.openai.com/v1",
  "models": ["gpt-4o", "gpt-4o-mini", "o1-preview"],
  "status": "active",
  "health": {
    "status": "healthy",
    "latencyP50": 1200,
    "latencyP99": 4500,
    "errorRate": 0.002
  }
}

---

Workspace Routes

Route	Method	Description
/api/workspaces	GET	List workspaces
/api/workspaces	POST	Create a workspace
/api/workspaces/{slug}	GET	Get workspace details
/api/workspaces/{slug}	PATCH	Update workspace
/api/workspaces/{slug}	DELETE	Delete workspace
/api/workspaces/{slug}/health	GET	Workspace health dashboard
/api/workspaces/{slug}/limits	GET	Current limit usage
/api/workspaces/{slug}/limits	PATCH	Update limits
/api/workspaces/{slug}/runtime	GET	Runtime profile
/api/workspaces/{slug}/runtime	PATCH	Update runtime profile
/api/workspaces/{slug}/restrictions	GET	Provider restrictions
/api/workspaces/{slug}/restrictions	PATCH	Update restrictions

---

Strategy Routes

Route	Method	Description
/api/strategies	GET	List strategies
/api/strategies	POST	Create custom strategy
/api/strategies/{id}	GET	Get strategy details
/api/strategies/{id}	PATCH	Update strategy
/api/strategies/{id}	DELETE	Delete strategy
/api/strategies/{id}/calibrate	POST	Trigger calibration for this strategy
/api/workspaces/{slug}/strategy	GET	Get workspace default strategy
/api/workspaces/{slug}/strategy	PUT	Set workspace default strategy

---

Execution & Trace Routes

Route	Method	Description
/api/traces	GET	List execution traces
/api/traces/{id}	GET	Get trace details
/api/traces/{id}/replay	POST	Replay a trace
/api/traces/{id}/compare/{id2}	GET	Compare two traces
/api/traces/{id}/explain	GET	Get routing explanation for trace
/api/traces/{id}/economics	GET	Get economic analysis for trace
/api/traces/recent	GET	Get recent traces (with filtering)
/api/traces/analytics	GET	Trace analytics and trends

Trace Object

{
  "traceId": "trace-uuid",
  "workspaceId": "my-project",
  "intent": {
    "classification": "coding",
    "confidence": 0.94
  },
  "strategy": "quality",
  "routingDecision": {
    "primaryProvider": "anthropic-prod",
    "primaryModel": "claude-sonnet-4",
    "fallbackChain": ["openai-prod", "ollama-local"],
    "scores": {
      "quality": 0.92,
      "speed": 0.78,
      "cost": 0.65
    }
  },
  "execution": {
    "attempts": 1,
    "finalProvider": "anthropic-prod",
    "latencyMs": 3400,
    "tokensIn": 1240,
    "tokensOut": 892,
    "costUsd": 0.023
  },
  "explanation": {
    "summary": "Selected Claude Sonnet for high-quality code generation",
    "providerRationale": "Top quality score (0.92) for coding workloads"
  }
}

---

Evaluation Routes

Route	Method	Description
/api/evaluation/calibration	GET	Get latest calibration report
/api/evaluation/calibration	POST	Run new calibration
/api/evaluation/calibration/history	GET	Calibration history
/api/evaluation/quality	GET	Quality metrics overview
/api/evaluation/quality/providers	GET	Per-provider quality scores
/api/evaluation/benchmarks	GET	List benchmark runs
/api/evaluation/benchmarks	POST	Run new benchmark
/api/evaluation/benchmarks/{id}	GET	Get benchmark results
/api/evaluation/coding	POST	Submit code for evaluation
/api/evaluation/coding/{id}	GET	Get code evaluation result
/api/evaluation/outcomes	GET	Execution outcome metrics

---

Economics Routes

Route	Method	Description
/api/economics/summary	GET	Economic summary for workspace
/api/economics/providers	GET	Per-provider cost breakdown
/api/economics/categories	GET	Cost by model category
/api/economics/simulate	POST	Run cost simulation
/api/economics/simulate/{id}	GET	Get simulation result
/api/economics/savings	GET	Savings attribution report
/api/economics/budget	GET	Current budget status
/api/economics/budget	PATCH	Update budget settings
/api/economics/insights	GET	Economic insights and recommendations

Budget Object

{
  "workspaceId": "my-project",
  "monthlyBudget": 100.00,
  "weeklyAlertThreshold": 60.00,
  "spentThisMonth": 34.50,
  "remainingBudget": 65.50,
  "projectedSpend": 98.20,
  "status": "healthy"
}

---

Security & Admin Routes

Route	Method	Description
/api/admin/secrets	GET	List secrets (admin only)
/api/admin/secrets	POST	Add secret (admin only)
/api/admin/secrets/{id}/rotate	POST	Rotate secret (admin only)
/api/admin/guardrails	GET	Guardrail policies
/api/admin/guardrails	PATCH	Update guardrail policies
/api/admin/audit	GET	Audit log
/api/admin/tenancy	GET	Tenant diagnostics
/api/health	GET	System health check (no auth)
/api/health/detailed	GET	Detailed health with component status
/api/telemetry	POST	Submit telemetry data

---

Route Summary by Category

Category	Count	Prefix
OpenAI-Compatible	4	/v1/
Chat & Conversations	5	/api/chat, /api/conversations
Provider Management	9	/api/providers
Workspace Management	11	/api/workspaces
Strategy	8	/api/strategies
Execution & Traces	7	/api/traces
Evaluation	10	/api/evaluation
Economics	9	/api/economics
Security & Admin	9	/api/admin, /api/health
Total	135

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Insufficient permissions
WORKSPACE_NOT_FOUND	404	Workspace does not exist
PROVIDER_UNAVAILABLE	502	All providers exhausted in fallback chain
RATE_LIMITED	429	Workspace or provider rate limit exceeded
BUDGET_EXCEEDED	402	Workspace has exceeded its budget
TIMEOUT	504	Request exceeded timeout profile
INVALID_STRATEGY	400	Requested strategy does not exist
GUARDRAIL_VIOLATION	400	Request violates content policy
CALIBRATION_PENDING	503	System is recalibrating, try again later

SDK Compatibility

Because Layerr implements the OpenAI API specification, it is compatible with:

• OpenAI SDK (Python/JS), point base_url to your Layerr instance
• LangChain, use OpenAI-compatible adapter
• Vercel AI SDK, use createOpenAI with custom endpoint
• Continue.dev, configure as custom OpenAI-compatible provider
• Cursor, set API base URL in settings

---

API documentation generated from GitNexus route map. 135 routes indexed across 1,090 source files.