Skip to content
Kodakodadocs
Reference

Control-plane API

OpenAPI surface for provider, agent, and access management.

The control-plane API is served at /api/control-plane/* on port 8090. It covers every operator-configurable surface — providers, agents, secrets, access, onboarding. The authoritative contract is /openapi/control-plane.json; this page indexes the routes by domain.

Authentication at a glance

All routes require either the operator session cookie (koda_operator_session), a bearer token from the /auth/tokens endpoint, or the break-glass CONTROL_PLANE_API_TOKEN when it's configured.

Authentication & sessions

  • POST /auth/register-owner — create the first owner account (first-run only).
  • POST /auth/login — start an operator session.
  • POST /auth/logout — end the current session.
  • GET /auth/status — current session + identity.
  • GET /auth/sessions — list every active session for the owner.
  • DELETE /auth/sessions/:id — revoke a session.
  • POST /auth/tokens, DELETE /auth/tokens/:id — manage long-lived API tokens.
  • POST /auth/bootstrap/exchange — redeem the short-lived setup code.
  • POST /auth/password/change, POST /auth/password/recover — password lifecycle.

Agents

  • GET /agents, POST /agents — list and create.
  • GET /agents/:agent_id, PATCH /agents/:agent_id — read and update.
  • POST /agents/:agent_id/publish — move from draft to published (runnable).
  • POST /agents/:agent_id/activate — toggle operational state without republishing.
  • PUT /agents/:agent_id/secrets/:secret_key — write an agent-scoped secret.
  • DELETE /agents/:agent_id/secrets/:secret_key — remove one.

Providers

  • PUT /providers/:provider_id/connection/api-key — save an API-key credential.
  • PUT /providers/:provider_id/connection/local — save a local-endpoint provider (Ollama).
  • POST /providers/:provider_id/connection/verify — round-trip verification.
  • DELETE /providers/:provider_id/connection — remove the stored credential.

Connections & integrations

  • GET /connections/catalog — every supported provider and integration.
  • PUT /connections/defaults/:connection_key — set the system-default connection for an integration.
  • POST /connections/defaults/:connection_key/verify — verify the default round-trip.
  • GET /integrations/:integration_id/health — recent health snapshots.

System & onboarding

  • GET /system-settings, PATCH /system-settings — global toggles (allowed users, defaults, policy).
  • GET /onboarding/status — where the first-run flow currently is.
  • POST /onboarding/bootstrap — advance the bootstrap sequence.

Skills

  • GET /skills — every registered skill, the same catalogue the /skill command uses.
  • GET /skills/:skill_id — skill metadata, frontmatter, and body.

Conventions

  • Content type. Every write endpoint expects application/json. Reads return JSON.
  • Idempotency. Creation endpoints accept an optional Idempotency-Key header. Retried requests with the same key return the original response.
  • Pagination. List endpoints accept limit and cursor query parameters and return next_cursor in the response body when more pages exist.
  • Errors. Non-2xx responses carry a structured error body: code, message, optional details. The code is a stable machine string — auth.session_expired, provider.credential_invalid, agent.not_found.
  • Rate limiting. Auth-adjacent routes use stricter buckets than general operator routes. See Control plane for the specific budgets.

OpenAPI spec

/openapi/control-plane.json ships with the platform and is the authoritative contract. The dashboard, CLI, and any custom integration are all built against it. Import it into Postman or Bruno for exploratory work, or feed it to an OpenAPI generator to get a typed client in your language of choice.

Next steps