Platform Surfaces

This page tracks Keel’s customer-visible route families and the public boundaries around them.

It is intentionally not a full inventory of non-advertised compatibility routes, dashboard-only helpers, or implementation detail.

Two public tiers

Keel’s public HTTP surface is split into two tiers with different stability commitments:

Runtime API — the stable contract for customer integrations. Project-API-key authenticated, SDK-covered, and governed by the breaking-change policy in Surface Maturity. This is what you build against.
Management API — authenticated dashboard-adjacent routes (user JWT). These back the Keel dashboard: project CRUD, policy CRUD, provider-key management, billing. The shape of these routes may change alongside dashboard UI evolution. Scripting against them is possible but carries more change risk than the Runtime API.

Everything on this page is one or the other. The taxonomy below maps each family to a tier.

Surface taxonomy

Use this page as the public surface map:

Runtime API (project-API-key, SDK-covered, stable contract)

decision surfaces: permit creation, readback, export, and permit-first closeout
governed execution surfaces: /v1/execute, /v1/executions, /v1/proxy/*, and async jobs
lifecycle and evidence surfaces: request timeline, governance events, and compliance exports
status surfaces: public status summary

Management API (user-JWT, dashboard-driven, shape subject to change)

project, policy, provider-key, billing, and runtime-key management

Beta support matrix

Surface family	Tier	Beta status	Notes
Permit decision contract	Runtime API	Stable	`POST /v1/permits` remains the canonical public decision seam.
Unified execution	Runtime API	Stable	`POST /v1/execute` and `POST /v1/executions` are active public execution surfaces with different request contracts.
Proxy execution	Runtime API	Limited	Capability coverage differs by provider and route. Treat provider parity as route-specific, not universal.
Async jobs and lifecycle replay	Runtime API	Stable	Public async job submission, status, and request timeline replay are mounted.
Governance events and compliance exports	Runtime API	Stable	Public project-scoped readback and export surfaces are mounted.
Authenticated management surfaces	Management API	Shape subject to change	Project, policy, billing, provider-key, and runtime-key flows. Coupled to dashboard UI; contract may evolve with dashboard redesigns.
Dashboard-only and operator tooling	—	Not part of the public contract	Internal and UI-focused surfaces are intentionally omitted.

Runtime API

Routes below are project-API-key authenticated, SDK-covered, and governed by the strict stability policy in Surface Maturity. This is the contract to build against.

Canonical decision surface

Route	Notes
`POST /v1/permits`	Stable provider-agnostic decision contract.

Execution and lifecycle surfaces

Route	Notes
`POST /v1/execute`	Primary public runtime surface for provider-shaped input with normalized output and a `resolved` block.
`POST /v1/executions`	Provider-neutral execution route for the documented sync and streaming subset.
`POST /v1/proxy/openai`	Provider-native OpenAI route. Coverage and streaming behavior are route-specific.
`POST /v1/proxy/anthropic`	Provider-native Anthropic route. Coverage and streaming behavior are route-specific.
`POST /v1/proxy/google`	Provider-native Google route. Coverage and streaming behavior are route-specific.
`POST /v1/proxy/xai`	Provider-native xAI route. Coverage and streaming behavior are route-specific.
`POST /v1/proxy/meta`	Provider-native Meta route. Coverage and streaming behavior are route-specific.
`POST /v1/jobs`	Async job submission for supported public async execution flows.
`GET /v1/jobs/{job_id}`	Async job status and result readback.
`GET /v1/requests/{request_id}/timeline`	Public normalized request lifecycle replay for the authenticated project.
`GET /v1/permits`	Permit audit and readback.
`GET /v1/permits/{permit_id}`	Permit audit and readback.
`GET /v1/permits/export`	Project-scoped audit export.
`POST /v1/permits/{permit_id}/usage`	Permit-first usage reporting. Public completed reports require verification material and still require positive billed cost.
`GET /v1/executions/{request_id}`	Public execution inspector and readback route for the authenticated project.
`GET /v1/compliance/exports`	Project-scoped Business+ gated compliance export list.
`POST /v1/compliance/exports`	Create a Business+ gated compliance export job for the authenticated project.
`GET /v1/compliance/exports/{export_id}`	Fetch a Business+ gated compliance export job or result record.
`GET /v1/governance/events`	Governance-event readback for the authenticated project.
`GET /v1/governance/events/stream`	SSE governance-event stream for the authenticated project.
`GET /v1/governance/events/{event_id}`	Governance-event detail readback.
`GET /v1/webhooks`	Webhook subscription list.
`POST /v1/webhooks`	Create a webhook subscription. See the request lifecycle docs for current delivery guarantees.
`DELETE /v1/webhooks/{subscription_id}`	Delete a webhook subscription.
`GET /v1/metrics/executions`	Project-scoped execution metrics.

Status surface

Route	Notes
`GET /v1/public/status/summary`	Public status summary: readiness and coarse provider-status for the documented subset. Use this for uptime integrations.

Management API

Routes below are authenticated with a user JWT (dashboard session) and back the Keel dashboard UI. Shape may change alongside dashboard UI evolution. Scripting against them is possible, but carries more change risk than the Runtime API. Management routes are not wrapped by the SDKs.

Authentication and session

Route	Notes
`POST /v1/auth/exchange`	Exchanges a verified user JWT for an authenticated dashboard session.
`POST /v1/auth/logout`	Revokes the current dashboard session.

Project, policy, and provider management

Route	Notes
`GET /v1/policies` and `POST /v1/policies`	Policy management. Primary authenticated policy configuration surface.
`DELETE /v1/policies/{policy_id}` and `PATCH /v1/policies/{policy_id}`	Policy mutation.
`GET /v1/projects` and `POST /v1/projects`	Project management.
`GET /v1/projects/{project_id}/api-keys` and `POST /v1/projects/{project_id}/api-keys`	Runtime API-key management.
`POST /v1/projects/{project_id}/api-keys/{key_id}/revoke`	Runtime API-key revoke.
`GET /v1/projects/{project_id}/providers`	Provider-key status list.
`PUT /v1/projects/{project_id}/providers/{provider}/key`	Provider-key set or replace.
`DELETE /v1/projects/{project_id}/providers/{provider}/key`	Provider-key delete.
`POST /v1/projects/{project_id}/providers/{provider}/test`	Active provider-key test.
`GET /v1/projects/{project_id}/permits`	Project permit readback.
`GET /v1/projects/{project_id}/usage`	Project usage summary.
`GET /v1/projects/{project_id}/cost-forecast`	Project cost forecast.
`GET /v1/projects/{project_id}/policy` and `PATCH /v1/projects/{project_id}/policy`	Per-project policy override.
`GET /v1/projects/{project_id}/prompt-analytics`	Prompt analytics.

Billing

Route	Notes
`POST /v1/billing/checkout`	Billing checkout flow.
`POST /v1/billing/stripe/webhook`	Stripe webhook endpoint (Stripe-signed, not user-JWT).

Intentionally omitted from this page

This page does not enumerate:

non-advertised compatibility aliases
dashboard-only helpers and UI-focused routes
operator-only and control-plane tooling
implementation internals such as adapters or fallback internals
non-public realtime scaffolding that does not have a public session-start route

Current boundaries

/v1/permits remains the canonical public decision seam
/v1/executions and /v1/execute are both active public execution routes, but they do not have the same request contract
/v1/executions is provider-neutral at the request boundary, but it is still a narrower contract than the provider-native proxy routes
/v1/execute accepts a provider-shaped input object and returns the normalized execution envelope plus a resolved block
public proxy streaming is stronger than /v1/executions: all five current proxy routes support streaming text-generation or text-message payloads, while /v1/executions streaming remains OpenAI-only
public routing controls are currently exposed on /v1/executions, /v1/proxy/openai, and /v1/proxy/anthropic
public cross-provider fallback is explicit, non-stream, and limited to the implemented OpenAI and Anthropic text-translation subset
compliance export routes are Business+ gated, while permit audit export is a separate route family
async jobs are public
there is no public realtime session-start route today