Surface Maturity

Read this alongside Route Guarantees: that page defines the security and audit properties each route guarantees; this page defines how stable the contract is.

Scope: Runtime API only

This page covers the Runtime API — project-API-key authenticated routes that Keel commits to as a stable customer integration contract. The Management API (user-JWT dashboard routes: projects, policies, provider keys, billing) is documented in Platform Surfaces and is intentionally excluded from these stability tiers because those routes evolve alongside dashboard UI.

For the current customer-facing route projection, use Public API Surface. This page documents stability posture for the authored route families and may lag newly added generated rows until they receive explicit maturity labels.

Tier definitions

Tier	Meaning
GA	Stable contract. Breaking changes require a version bump plus a 90-day deprecation notice.
Beta	Shape may change between releases. Keel publishes release notes for every change and will not introduce silent breaks, but the contract is not SemVer-stable.
Internal	Not for customer use. Administrative, bootstrap, or diagnostic surface. May change or be removed without notice.
Deprecated	Still functional. Sunset date is stated. Replacement listed. Remove your dependency before the sunset date.

Tier change policy

Event	Customer-visible action
Beta → GA	Changelog entry + email to all active project owners. The route’s contract is now locked.
GA → Deprecated	Changelog entry + email to active project owners + `Deprecation` and `Sunset` response headers (RFC 8594).
Deprecated → removed	Changelog entry at least 90 days before removal. Final email 30 days out.
Internal added or removed	No notice obligation. Internal surfaces carry no compatibility commitment.
Beta route changed	Release notes in the changelog. No email. Beta callers accept this risk.

What “breaking change” means for GA routes

A breaking change is any of the following:

Removing or renaming a required request field.
Removing or renaming a response field documented in Route Guarantees.
Changing an HTTP method, route path, or status code (unless labeled as a redirect).
Narrowing the set of accepted authentication credential types.
Adding a new required request field without a documented default.

Adding optional request fields, adding response fields, or relaxing validation is not a breaking change.

Execution surfaces

Route	Tier	Since	Notes
`POST /v1/executions`	GA	v1.0	Core governed execution path. Permit, chain event, constraint clamp, signed export coverage locked.
`POST /v1/execute`	Beta	v1.3	Unified single-call variant. Response shape still aligning with `/v1/executions` contract; promoted to GA when shape converges.
`POST /v1/proxy/openai/*`	GA	v1.0	OpenAI-compatible proxy. Provider protocol follows OpenAI versioning; Keel wrapper contract is GA.
`POST /v1/proxy/anthropic/*`	GA	v1.1	Anthropic-compatible proxy. Same stability commitment as OpenAI proxy.
`POST /v1/proxy/google/*`	Beta	v1.4	Google provider support; request/response normalization shape still stabilizing.
`POST /v1/proxy/meta/*`	Beta	v1.4	Newer provider; shape stabilizing.
`POST /v1/proxy/xai/*`	Beta	v1.5	xAI provider integration; upstream provider API surface itself is in flux.
`POST /v1/permits`	GA	v1.0	Pre-flight permit issuance. Contract is the public API of the Budget and Policy features.
`POST /v1/permits/dry-run`	Beta	v1.2	Policy evaluation without persistence. Response shape may gain fields as the policy engine matures.

Governance read surfaces

Route	Tier	Since	Notes
`GET /v1/permits`	GA	v1.0	Paginated permit list. Filter params and response envelope are stable.
`GET /v1/permits/{id}`	GA	v1.0	Single permit retrieval.
`GET /v1/permits/{id}/bundle`	GA	v1.1	Permit + all attached governance events in a single payload for replay.
`GET /v1/permits/{id}/lineage`	GA	v1.1	Permit ancestry chain.
`GET /v1/permits/{id}/usage`	Beta	v1.3	Usage rollup per permit. Shape will gain additional dimension fields before GA.
`POST /v1/permits/{id}/usage`	Beta	v1.3	Permit-first usage closeout. Public closeout requires verification material and positive billed cost.
`GET /v1/permits/export`	Beta	v1.3	Bulk permit export. Format and compression options still settling. Prefer `/v1/compliance/exports` for audit-grade exports.
`GET /v1/governance/events`	GA	v1.0	Paginated chain event list. Field names and event type vocabulary are stable.
`GET /v1/governance/events/{id}`	GA	v1.0	Single event with full payload and chain digest.
`GET /v1/governance/events/stream`	Beta	v1.3	SSE live feed of chain events. Best-effort; not a replay substitute.
`POST /v1/jobs`	Beta	v1.3	Async job submission for supported public async execution flows.
`GET /v1/jobs/{id}`	Beta	v1.3	Async job status and result readback.
`GET /v1/requests/{id}/timeline`	Beta	v1.3	Normalized request lifecycle replay for the authenticated project.

Compliance surface

Route	Tier	Since	Notes
`POST /v1/compliance/exports`	GA	v1.1	Creates a signed, manifest-covered export. Ed25519 signature contract is locked.
`GET /v1/compliance/exports`	GA	v1.1	Lists exports for the project.
`GET /v1/compliance/exports/{id}`	GA	v1.1	Retrieves a single export record and its download URL.

Policy authoring surface

Route	Tier	Since	Notes
`POST /v1/policies`	GA	v1.1	Policy creation. JSON rule schema locked.
`GET /v1/policies`	GA	v1.1	Policy list for the project.
`PATCH /v1/policies/{id}`	GA	v1.1	Policy update. Emits `policy.updated` chain event.
`DELETE /v1/policies/{id}`	GA	v1.1	Policy deletion. Emits `policy.deleted` chain event. Soft-deleted records remain replayable.
`PATCH /v1/projects/{id}/policy`	GA	v1.1	Per-project override attachment.
`GET /v1/policy-templates`	Beta	v1.4	Global preset catalog. Template IDs and schema may change as the library expands.
`GET /v1/policy-templates/{id}`	Beta	v1.4	Single template retrieval.

Status surface

Route	Tier	Since	Notes
`GET /v1/public/status/summary`	GA	v1.0	Public status summary: readiness plus coarse provider-status for the documented subset. Safe for uptime integrations; no tenant data.

Internal routes (liveness probes, admin diagnostics, checkpoint endpoints, metrics endpoints) are not listed here. They carry no compatibility commitment — do not build customer integrations on them.

Current tier summary

Tier	Count
GA	19
Beta	14
Deprecated	0

Internal surfaces are not enumerated and carry no compatibility commitment.

Route Guarantees — security and audit properties per route
API Guarantees — the broader public API contract
Status and changelog — tier promotions and breaking changes are announced here