Kyzos API Docs

Welcome to the Kyzos API documentation. This folder is the source of truth for developer docs and is rendered in the web UI.

Quick start

1. Create an account and log in
2. Generate an API key at /api-keys
3. Call the orchestration endpoint

bash
Copy
curl -X POST "http://localhost:3000/api/orchestrator/orchestrate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: aip_your_key" \
  -d '{
    "prompt": "Write a short product description for a smart thermostat",
    "qualityPreference": "quality"
  }'

Base URL

• Local dev: http://localhost:3000/api

Authentication

You can authenticate with:

• JWT bearer token (from /auth/login) — set as HttpOnly cookies
• API key (X-API-Key header)

See authentication.md for details.

Main endpoints

Orchestration

• POST /orchestrator/orchestrate — Quick orchestration (rate limited: 20/min)
• POST /orchestrator/blueprint — Generate blueprint plan (rate limited: 30/min)
• POST /orchestrator/blueprint/:id/execute — Execute blueprint (rate limited: 20/min)
• POST /orchestrator/blueprint/:id/stream — SSE streaming execution (rate limited: 20/min)
• GET /orchestrator/models
• GET /orchestrator/models/by-provider
• GET /orchestrator/models/by-category
• GET /orchestrator/executions/:executionId/assets
• GET /orchestrator/executions/:executionId/deliverables

Streaming Chat

• POST /streaming/chat — SSE streaming chat with tool use support

Projects

• GET /projects
• POST /projects
• GET /projects/:id
• PUT /projects/:id
• DELETE /projects/:id

Documents (RAG)

• POST /projects/:id/documents — Upload document for RAG context
• GET /projects/:id/documents — List project documents
• DELETE /projects/:id/documents/:docId — Remove document

Analytics (ADMIN/DEVELOPER only)

• GET /analytics/overview
• GET /analytics/cost-over-time
• GET /analytics/model-usage
• GET /analytics/success-rate
• GET /analytics/activity-heatmap
• GET /analytics/model-leaderboard
• GET /analytics/performance
• GET /analytics/models
• GET /analytics/provider-stats
• GET /analytics/timeseries
• GET /analytics/costs
• GET /analytics/models/compare
• GET /analytics/export
• GET /analytics/project/:projectId

Model Profiles (ADMIN/DEVELOPER only)

• GET /model-profiles — Model DNA performance data

API Keys (ADMIN/DEVELOPER only)

• POST /api-keys
• GET /api-keys
• DELETE /api-keys/:id

Tier & Usage

• GET /tier/usage — Current user's tier limits and usage counts

Subscription (Stripe)

• POST /subscription/checkout — Create Stripe Checkout session
• POST /subscription/portal — Create Stripe Customer Portal session
• GET /subscription/status — Stripe availability + subscription status

Admin (ADMIN/DEVELOPER only)

• GET /admin/overview — Platform stats
• GET /admin/users — Paginated user list
• GET /admin/users/:id — User detail
• PATCH /admin/users/:id/role — Change user role
• PATCH /admin/users/:id/tier — Change user tier
• PATCH /admin/users/:id/active — Suspend/reactivate
• POST /admin/users/bulk — Bulk actions
• GET /admin/audit — Audit logs

MCP (Enterprise only)

• POST /mcp/servers — Register MCP server
• GET /mcp/servers — List MCP servers
• DELETE /mcp/servers/:id — Remove MCP server
• PATCH /mcp/servers/:id/toggle — Toggle active/inactive
• GET /mcp/tools — List available MCP tools

Webhooks

• POST /webhooks — Register webhook endpoint
• GET /webhooks — List webhooks
• DELETE /webhooks/:id — Remove webhook

Health

• GET /monitoring/healthz — Simple health check
• GET /monitoring/health — Full health (DB + Redis + LLM providers)
• GET /monitoring/metrics — Prometheus metrics
• GET /monitoring/platform-stats — Public platform stats (model count)

Environment Variables

Key API environment variables (see apps/api/.env.example for full list):

Swagger

Swagger UI is available at /api/docs (development only).

Security

All orchestration and chat endpoints are protected by:

• Input moderation (blocks harmful prompts before LLM call)
• System prompt hardening (instruction hierarchy, anti-injection)
• Content filter on outputs (PII, injection, harmful patterns)
• Tool output sanitization (strips injection from web/MCP results)
• Rate limiting per endpoint
• Tier-based access control (tools, models, usage limits)
• Cost caps per execution