Skip to content
Kodakodadocs
Reference

Control-plane API

Maintained OpenAPI surface for setup, providers, agents, and access.

The control-plane API is served at /api/control-plane/* on port 8090. It owns operator configuration and management: setup, auth, providers, agents, workspaces, squads, skills, memory and knowledge surfaces, evals, quality cockpit, channel gateway, MCP, connections, and system settings.

OpenAPI is the contract
/openapi/control-plane.json mirrors every operator-facing route registered in the control plane. Some dashboard bundle routes use broad schemas because their exact fields are shared with the dashboard runtime contracts rather than promised as SDK models.

Authentication & sessions

  • POST /auth/register-owner — first-owner registration.
  • POST /auth/login, POST /auth/logout, GET /auth/status — session lifecycle.
  • PATCH /auth/profile, profile photo upload/read/delete, password recovery/change, and recovery-code regeneration.
  • GET /auth/sessions, DELETE /auth/sessions/:session_id — list and revoke sessions.
  • GET /auth/tokens, POST /auth/tokens, DELETE /auth/tokens/:token_id — API token lifecycle.
  • POST /auth/bootstrap/exchange, POST /auth/bootstrap/codes — short-lived setup code flows.

Agents

  • Agent CRUD: GET, POST, PATCH, and DELETE /agents/:agent_id.
  • Lifecycle: clone, publish, activate, pause, validate, and publish-checks.
  • Configuration: agent-spec, compiled-prompt, runtime-access, tool/model/autonomy/execution policy, and policy evaluation.
  • Assets: sections, documents, knowledge assets, templates, skills, secrets, Telegram bot info, retrieval traces, answer traces, runbooks, and knowledge graph.
  • Self-improvement: improvement-proposals list/create/detail plus approve, reject, validate, apply, and rollback.

Providers

  • Connection state, API-key setup, local endpoint setup, subscription login start/status/code, verify, and disconnect.
  • Model and voice catalogs for Ollama, ElevenLabs, Kokoro, Supertonic, Whisper, and embedding providers.
  • Download, select, delete, active-download, job detail, and cancellation routes for local models and voices.

Connections & integrations

  • GET /connections/catalog and system defaults under /connections/defaults.
  • Per-agent connections under /agents/:agent_id/connections/:connection_key with verify, tool discovery, import-default, and policies.
  • Integration health and system-enable routes under /integrations/:integration_id.
  • MCP catalog, custom MCP servers, Claude Desktop import, OAuth start/status/refresh/revoke, resources, prompts, and capability policies.

System & onboarding

  • GET /onboarding/status, /onboarding/readiness, POST /onboarding/bootstrap, and POST /onboarding/first-task.
  • GET/PUT /system-settings and /system-settings/general.
  • Global defaults, global secrets, and persistence diagnostics.
  • Workspace directory roots, list, scan, import, rescan, imported config, workspace specs, squad specs, and workspace/squad CRUD.

Skills, evals, quality, and channels

  • Skill packages: list, registry, scan, install, eval run, delete, and rollback.
  • Evals: legacy evaluation cases, eval_case.v1, eval runs, from-run case creation, trajectory export, and latest release quality.
  • Quality cockpit: overview, per-agent quality, and failure-to-proposal.
  • Channel gateway: state, pairing codes, unknown senders, approve, block, and revoke.
  • Dashboard bundles: squad rooms, threads, participants, events, messages, photos, artifacts, task claim/complete/escalate, sessions, approvals, DLQ, costs, schedules, audit, memory map, and memory curation.

Conventions

  • Auth. Routes require the operator session cookie, bearer API token, or break-glass token unless OpenAPI marks the operation with security: [].
  • Payloads. Stable public contracts have detailed schemas. Dashboard bundle routes use broad objects when the backend shape is intentionally owned by the server/dashboard contract.
  • Errors. Formalized boundaries use the operational error envelope: code, category, message, retryable, and user_action.
  • Runtime separation. Runtime task-room routes live under /api/runtime/* and are documented separately.

OpenAPI spec

Import /openapi/control-plane.json into Postman, Bruno, or an OpenAPI-aware client generator for exploration. For generated SDKs, treat broad GenericJsonObject responses as route availability and auth contracts, not as complete typed models.

Next steps

  • Runtime API — task inspection, RunGraph, workspace, terminal, browser, schedules, and control routes.
  • Platform capabilities — what the current Koda platform actually ships.