API Reference

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

This count excludes three internal-only routes not meant for API consumers: the container liveness/readiness probes GET /healthz and GET /readyz (see Health & Readiness), and the production-only SPA catch-all that serves the frontend for unmatched paths (it doesn’t even exist as an Express route in dev mode, where Vite’s own middleware handles it instead).

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

Most routes require the ADMIN_API_KEY or a valid session, passed either as Authorization: Bearer <key>, the x-admin-key: <key> header, or the layerr_session cookie set by /api/auth/login. The key/session is validated by the gateway middleware (security/gateway/middleware.ts).

Gateway / orchestration routes (the OpenAI-compatible /v1/* endpoints) additionally require the gateway_access capability and the orchestration.execute scope, and accept scoped lgw_* gateway tokens (see Gateway Token Management) in addition to admin keys and session cookies.

Routes marked [admin-only] below require an admin-role account regardless of capability grants. Routes marked with a capability name (e.g. traces, budget_controls) additionally require that capability be granted to the caller’s plan/workspace (see Entitlements & Access).

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 (streaming and non-streaming). Accepts OpenAI-format requests, routes through Layerr intelligence
/v1/embeddings	POST	Embeddings passthrough to the caller’s configured cloud provider only — there is no local-model embeddings path
/v1/models	GET	List available models across all configured providers; best-effort live provider discovery is merged in
/v1/models/{modelId}	GET	Get details for a specific model (for SDKs that require this endpoint to exist)

/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/router	POST	Classify a raw prompt and return a routing decision (no model call)
/api/chat	POST	Layerr-native chat endpoint; queues, applies backpressure/global concurrency limiting, and streams the response as newline-delimited JSON
/api/conversations	GET	List conversations; paginated if limit/offset given, else the legacy full list
/api/conversations	POST	Create a conversation
/api/conversations/{id}	GET	Get a specific conversation with full messages
/api/conversations/{id}	PUT	Update a conversation (title/messages)
/api/conversations/{id}	DELETE	Delete a conversation
/api/conversations/export	GET	Full export of all of the caller’s conversations, all messages included
/api/conversations/{id}/project	PATCH	Assign a conversation to a project
/api/projects	GET	List projects
/api/projects	POST	Create a project (blocked once the workspace’s project_count usage limit is reached)
/api/projects/{id}	PUT	Update a project
/api/projects/{id}	DELETE	Delete a project; ?deleteChats=true cascades to its conversations

Two-Stage Routing Flow

The Layerr-native path is split into two calls:

1. POST /api/router — send the raw prompt. Returns a routing decision of the shape { category, model, provider, reasoning, confidence }.
2. The client enriches that decision with the provider URL and a fallback pool.
3. POST /api/chat — send the enriched decision plus messages. The response streams back as newline-delimited JSON.

/api/router

Request body:

{
  "prompt": "Refactor this function to TypeScript",
  "hasAttachments": false
}

Response (routing decision):

{
  "category": "CODING",
  "model": "claude-sonnet-4",
  "provider": "anthropic-prod",
  "reasoning": "Code refactor on a quality-weighted workspace profile",
  "confidence": 0.94
}

/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
  }
}

---

Auth & Sessions Routes

Route	Method	Description
/api/auth/status	GET	Current auth/session state, registration-enabled flag, active workspace
/api/auth/login	POST	Username/password login; sets the layerr_session cookie. Rate-limited
/api/auth/api-key-login	POST	Login via a layerr-api-issued API key. Rate-limited
/api/auth/workspaces/refresh	POST	Re-fetch linked workspaces/active workspace for a layerr-api-linked account
/api/auth/register	POST	Self-service registration; 403s unless the admin has enabled registration. Rate-limited
/api/auth/logout	POST	Clear the session cookie / server-side session
/api/auth/password	PUT	Change the caller’s own password; invalidates all existing sessions and issues a new one. Rate-limited

---

Global/User Config Routes

Per-user runtime configuration (provider URLs, API keys, category models) — distinct from the workspace strategy/orchestration profiles under Workspace Management.

Route	Method	Description
/api/config	GET	Read the effective provider config for the caller; secret keys are masked before returning
/api/config	POST	Save user config; validates URLs (SSRF guard), restores masked keys by identity, syncs the provider-count usage metric

---

Onboarding Routes

Route	Method	Description
/api/onboarding/state	GET	Read resumable onboarding state
/api/onboarding/state	PUT	Dispatch an onboarding state-machine action
/api/onboarding/skip	POST	Skip onboarding
/api/onboarding/complete	POST	Mark onboarding complete (auto-derives licenseKeyPresent)
/api/onboarding/reset	POST	Reset onboarding state
/api/onboarding/providers/detect-local	POST	Probe well-known local ports (Ollama, LM Studio, etc.) for running runtimes
/api/onboarding/providers/probe	POST	Probe an arbitrary provider URL + key (SSRF-guarded) and infer its capabilities
/api/onboarding/providers/save	POST	Idempotent upsert of a provider into the user’s or workspace’s local provider list
/api/integrations/snippets	GET	Render ready-to-paste integration code snippets (Cursor, Claude Code, etc.) with the caller’s gateway URL
/api/integrations/diagnose	POST	Run 4 canned probes (compatibility, streaming, tool-calling, invalid-model) against the caller’s own /v1/chat/completions

---

Provider Management Routes

Route	Method	Description
/api/health	GET	Probe all configured providers’ connectivity plus Ollama auto-detection; includes a credential-health summary
/api/models	GET	Aggregate discovered models across all configured local providers
/api/models/capabilities	GET	Model capability registry lookup (single model, or a filtered list with optional benchmark data)
/api/providers/health	GET	Per-provider health snapshots (ring-buffer derived) plus basic connectivity
/api/providers/orchestration	GET	Per-provider orchestration-role statistics, idle-provider detection, deterministic recommendations
/api/providers/credentials/health	GET	Full credential/connection health report
/api/providers/credentials/{id}/health	GET	Health for one credential connection
/api/providers/credentials/{id}/rotate	POST	Begin or immediately complete a credential rotation
/api/providers/credentials/{id}/validate	POST	Probe one credential right now
/api/providers/credentials/{id}/revoke	POST	Revoke a credential
/api/providers/credentials/{id}/log	GET	Rotation history log for one connection
/api/providers/credentials/validate-all	POST	Validate every tracked connection at once
/api/providers/rate-limits	GET	Per-provider rate-limit configs plus live utilization telemetry

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 Management Routes

Named orchestration contexts and their strategy weighting — distinct from the per-user provider config under Global/User Config.

Route	Method	Description
/api/workspace/profiles	GET	List all workspace profiles with their settings
/api/workspace/preferences	GET	Get the caller’s active-workspace preference
/api/workspace/preferences	PUT	Set the caller’s active-workspace preference (pin + optimization strategy)
/api/workspace/active	GET	Resolve the effective workspace profile (weights/thresholds) for a category

---

Strategy Routes

Route	Method	Description
/api/strategy/resolve	GET	Resolve an execution strategy from workload signals (category, complexity, latency/cost sensitivity, etc.)
/api/strategy/workspaces	GET	List workspaces with strategy configuration
/api/strategy/workspaces/{slug}/strategies	GET	List strategies for a workspace

---

Execution & Trace Routes

Route	Method	Description
/api/traces	GET	List persisted orchestration traces (retention-window filtered)
/api/traces/{id}	GET	Load and build the full replay view of one trace
/api/traces/compare	GET	Compare two traces via query params (?a=<id>&b=<id>)
/api/traces/trends	GET	Trend analysis over recent traces
/api/runtime/health	GET	Orchestration runtime health: queue depth, concurrency, degraded-mode policy, provider saturation
/api/runtime/diagnostics	GET	Heap/event-loop/cache-size diagnostics snapshot
/api/runtime/incidents	GET	Detected incident patterns (failure spikes, saturation) summary
/api/runtime/incidents/export	GET	NDJSON export of incidents for log aggregators
/api/runtime/error-codes	GET	Static LAYERR-XXXX error-code registry
/api/runtime/executions	GET	Live plus recent (30-minute window) orchestration executions from the tracer ring buffer; regular users are self-scoped, admins may pass ?scope=all
/api/scoring/runtime-preview	GET	Preview computed runtime scores for a category’s candidate model pool
/api/workload/analyze	GET	Analyze a prompt/message set into a workload profile with a signal breakdown
/api/intelligence	GET	Active intelligence-module flags plus 30-minute ring-buffer request statistics (categories, fallback/retry/timeout rates)
/api/intelligence/adaptive	GET	Adaptive-learning score adjustments (provider affinity, strategy effectiveness, etc.)

Recent activity is served by GET /api/usage/recent (see Usage & Limits), not by a trace route. Per-trace cost analysis lives at GET /api/economics/trace/{traceId} (see Economics Routes).

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"
  }
}

---

Repository Intelligence Routes

Route	Method	Description
/api/repo/intelligence	GET	Repository profile and snapshot (language/framework inference, etc.) for the server’s current working-directory project

---

Project Memory Routes

Route	Method	Description
/api/project/memory	GET	List all project-memory records for the caller
/api/project/memory/current	GET	Get the memory record (plus adjustments) for the server’s current working-directory project
/api/project/memory/{projectKey}	DELETE	Delete one project-memory record

---

Gateway Token Management Routes

Scoped lgw_* tokens for third-party integrations that shouldn’t hold a full admin key or session cookie.

Route	Method	Description
/api/gateway/tokens	POST	Create a scoped gateway token (raw value is shown once and cannot be retrieved again)
/api/gateway/tokens	GET	List the caller’s tokens (metadata only)
/api/gateway/tokens/{id}	DELETE	Revoke a token
/api/gateway/tokens/scopes	GET	List all available token scopes and their descriptions
/api/gateway/audit	GET	List gateway auth/scope audit events
/api/gateway/audit	DELETE	Purge audit events older than retentionDays
/api/gateway/analytics	GET	Gateway request/latency/fallback analytics by client type; ?global=true (admin) aggregates across users

---

Entitlements & Access Routes

Route	Method	Description
/api/entitlements/me	GET	The caller’s effective entitlements
/api/entitlements/check/{capability}	GET	Check whether the caller has one named capability
/api/entitlements/workspace	GET	Full capability map for the caller’s workspace
/api/entitlements/plans	GET	Public catalog of plans, capabilities, and deployment mode
/api/access/me	GET	The caller’s resolved workspace role and granted permissions
/api/access/check	GET	Check one permission (?permission=) for the caller
/api/admin/entitlements	GET	List every user’s plan/entitlement
/api/admin/entitlements/{userId}	PUT	Assign a plan to a user

---

Licensing Routes

Route	Method	Description
/api/license	GET	Resolve the current license state for the caller
/api/license	DELETE	Deactivate a license (?userId= target, defaults to self)
/api/license/activate	POST	Activate a license key (format-validated)
/api/license/snapshot	GET	The current offline license snapshot
/api/license/snapshot/refresh	POST	Force-refresh the offline snapshot
/api/license/events	GET	License activity audit log
/api/license/generate	POST	Generate a local license key for testing / self-hosted activation
/api/admin/licenses	GET	List all active licenses across users

---

Admin User Management Routes

Route	Method	Description
/api/admin/users	GET	List all users
/api/admin/users	POST	Create a user, cloning the admin’s config as the default
/api/admin/users/{id}	DELETE	Delete a user (cannot delete self)
/api/admin/users/{id}/reset	PUT	Force-reset another user’s password
/api/admin/settings	GET	Read admin-level settings (e.g. the registration toggle)
/api/admin/settings	PUT	Update admin-level settings

---

Security & Admin Routes

Route	Method	Description
/api/admin/secrets	GET	Secret-store status plus a list of stored secret names (no values)
/api/admin/secrets	POST	Store a named secret
/api/admin/secrets/{name}	DELETE	Delete a named secret
/api/guardrails	GET	List guardrail policy rules
/api/guardrails	POST	Create a guardrail rule (warn / sanitize / reroute / block)
/api/guardrails/{id}	PATCH	Update a guardrail rule; invalidates the rule cache
/api/guardrails/{id}	DELETE	Delete a guardrail rule; invalidates the rule cache

---

Budgets & Cost Routes

Route	Method	Description
/api/budgets	GET	List budget rules with current-period spend
/api/budgets	POST	Create a budget rule (scope/period/limit/action validated)
/api/budgets/{id}	PATCH	Update a budget rule (owner-or-admin checked inline)
/api/budgets/{id}	DELETE	Delete a budget rule
/api/budgets/events	GET	List recent budget-threshold events
/api/cost/dashboard	GET	Aggregate cost dashboard: period stats, per-provider/domain stats, top models, fallback cost impact
/api/cost/intelligence	GET	Deterministic, rule-based cost-optimization recommendations

Budget Object

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

---

Usage & Limits Routes

Route	Method	Description
/api/usage/recent	GET	Recent usage / activity feed
/api/usage/summary	GET	Aggregated usage summary
/api/usage/limits	GET	Caller’s own usage counters and configured limits
/api/usage/limits/{userId}/{metric}	GET	Check one metric for any user
/api/usage/limits/{userId}/{metric}	PUT	Upsert a per-user limit override
/api/usage/limits/{userId}/{metric}/reset	POST	Manually reset a usage counter

---

Economics Routes

Route	Method	Description
/api/economics/trace/{traceId}	GET	Run or load baseline simulations for a trace; compute an efficiency score (0–100) and a deterministic cost narrative
/api/economics/profiles	GET	Catalog of baseline simulation profiles with descriptions
/api/economics/insights	GET	Full ranked optimization-insight report
/api/economics/insights/summary	GET	Insight summary string plus counts only
/api/economics/savings	GET	Full multi-dimension savings-attribution report
/api/economics/savings/summary	GET	Top-level savings numbers only
/api/economics/savings/providers	GET	Savings broken down by provider
/api/economics/savings/strategies	GET	Savings broken down by strategy (category)
/api/economics/savings/monthly	GET	Monthly savings trend
/api/economics/savings/fallbacks	GET	Savings attributed to fallback-chain use
/api/economics/savings/premium	GET	Premium (above-baseline) spend / premium-avoidance savings
/api/economics/simulations	GET	List stored simulation snapshots (filterable by profile)
/api/economics/simulations/aggregate	GET	Aggregate simulation/savings stats for the caller
/api/economics/simulate/{traceId}	GET	Simulate all baseline profiles for one trace
/api/economics/simulate/{traceId}/{profile}	GET	Simulate a single named baseline profile for a trace

---

Evaluation Routes

Route	Method	Description
/api/evaluation/outcomes	GET	Full multi-dimension execution-outcome evaluation report
/api/evaluation/outcomes/summary	GET	Overall outcome score (requires at least 5 traces)
/api/evaluation/outcomes/providers	GET	Per-provider outcome scores
/api/evaluation/outcomes/strategies	GET	Per-category outcome scores
/api/evaluation/coding	POST	Evaluate a coding response’s text and persist the result
/api/evaluation/coding	GET	List coding evaluations, filterable by domain/grade/score/date
/api/evaluation/coding/summary	GET	Aggregate coding-evaluation summary over N days
/api/evaluation/coding/{traceId}	GET	Retrieve one stored coding evaluation
/api/evaluation/quality	GET	Aggregate quality/confidence score over a window
/api/evaluation/quality/trace/{traceId}	GET	Per-trace confidence score
/api/evaluation/benchmarks	POST	Run a benchmark harness pass over stored traces (requires at least 3 matching traces)
/api/evaluation/benchmarks	GET	List stored benchmark runs
/api/evaluation/benchmarks/{id}	GET	Get one benchmark run (ownership-checked)
/api/evaluation/benchmarks/{id}	DELETE	Delete a benchmark run
/api/evaluation/calibration	GET	Compute (without persisting) a calibration report
/api/evaluation/calibration	POST	Compute and persist a calibration report
/api/evaluation/calibration/latest	GET	Latest persisted calibration report
/api/evaluation/calibration/history	GET	Alignment-score trend history
/api/evaluation/calibration/apply	POST	Apply a safe recommendation (currently only invalidate-cache)

---

Health & Readiness Routes

Route	Method	Description
/api/runtime/readiness	GET	Full readiness report (provider probes, gateway uptime, secret/permission/environment checks); ?scope= narrows to providers/gateway/environment

Two additional routes exist purely for container/orchestrator probing and are not counted above or meant for API consumers:

• GET /healthz — Liveness-only probe: returns uptime/pid, never touches the database or providers by design.
• GET /readyz — Readiness probe: reports whether migrations and subsystem init have finished (the layerrReady flag).

---

Route Summary by Category

Category	Count	Prefix
OpenAI-Compatible	4	/v1/
Chat & Conversations	13	/api/router, /api/chat, /api/conversations, /api/projects
Auth & Sessions	7	/api/auth
Global/User Config	2	/api/config
Onboarding	10	/api/onboarding, /api/integrations
Provider Management	13	/api/providers, /api/health, /api/models
Workspace Management	4	/api/workspace
Strategy	3	/api/strategy
Execution & Traces	14	/api/traces, /api/runtime, /api/scoring, /api/workload, /api/intelligence
Repository Intelligence	1	/api/repo
Project Memory	3	/api/project/memory
Gateway Token Management	7	/api/gateway
Entitlements & Access	8	/api/entitlements, /api/access, /api/admin/entitlements
Licensing	8	/api/license, /api/admin/licenses
Admin User Management	6	/api/admin/users, /api/admin/settings
Security & Admin	7	/api/admin/secrets, /api/guardrails
Budgets & Cost	7	/api/budgets, /api/cost
Usage & Limits	6	/api/usage
Economics	15	/api/economics
Evaluation	19	/api/evaluation
Health & Readiness	1	/api/runtime/readiness
Total	158

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 manually reconciled against server.ts’s actual route registrations on 2026-07-06 (158 documented routes, excluding 2 internal health probes and the SPA catch-all).