API Guarantees

This page summarizes the practical guarantees Keel documents for the current public API surface. It is intentionally narrow. If a behavior is not documented on the public routes Keel exposes today, do not treat it as guaranteed.

Public product contract

These are the strongest public claims to rely on:

POST /v1/permits is the canonical decision contract.
On Keel-managed execution routes, Keel evaluates governance before provider execution.
If a Keel-managed execution request is denied, that route does not continue to provider dispatch.
Governed requests produce documented decision or execution evidence on the supported public surfaces for that route family.

Stability

Keel’s stable public endpoints are not changed silently.

If a change would break an existing integration, Keel should either:

introduce that break behind an explicit version boundary, or
provide a clearly communicated migration path for the affected public route

This is a compatibility expectation for the documented public API surface, not a claim that every internal implementation detail remains fixed.

Idempotency

Keel exposes idempotency so clients can retry safely when a network call is interrupted or a response is lost.

For permit creation, the canonical idempotency field is idempotency_key in the request body. For execution routes, the canonical field is the Idempotency-Key header.

For the same route and retry attempt, clients should reuse the documented idempotency field rather than mint a new one. That is the supported way to retry safely after a timeout, dropped connection, or unknown response outcome.

Keel documents stronger replay semantics on some surfaces than others. Permit creation and the provider-native proxy routes document explicit replay and conflict behavior; the normalized execution routes document the same header-based retry contract, but route-specific details still matter.

For exact route behavior, see Idempotency.

What Keel guarantees today

A denied Keel-managed execution request does not reach the provider.
Tenant isolation is enforced at both the database and application layers across the decision and evidence path.
Keel offers an optional external accounting-durability mode that checkpoints accounting envelopes before provider dispatch.
Proxy routes have the strongest public same-key replay contract; /v1/executions, /v1/execute, and permit replay are narrower, route-specific guarantees.
Permit-first closeout requires verification material; Keel does not directly observe the provider call on the permit-first path. The verification track attaches receipt evidence.
Decision and evidence records are tamper-evident on the integrity path. The broader audit model uses persisted evidence with tiered external verification.

For the full coverage and non-claim model — provider parity, permit-first observation, accounting precision, content-inspection scope, and integrity proof scope — see Scope and Limits.

Error Contract

Keel uses a stable structured error contract for the current documented public runtime surface.

At minimum, clients should depend on:

the HTTP status code
error.code
error.message

Treat that as the compatibility boundary. Do not assume every route exposes the same optional error fields beyond those documented minimums.

Minimal example:


{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key"
  }
}

For route-specific error codes, see Errors.

Authentication Expectations

Public runtime requests use project API keys.

Clients should send a valid project API key on the documented public runtime routes. If the key is missing, invalid, revoked, or otherwise not accepted for the route being called, Keel returns an authentication or authorization error predictably rather than continuing as if the request were valid.

In practice, integrations should treat missing or invalid keys as normal auth failures and handle them separately from retryable transport issues.

Retry Guidance

Retry behavior should be practical and conservative:

safe retries depend on using the documented idempotency field for the route you are calling
if a request may have reached Keel but the client did not receive a response, retry with the same idempotency key
do not rotate the idempotency key for an uncertain retry unless you intend to create a new governed action
treat 409 conflict on reused keys as a signal that the same key was paired with a different semantic request

Without idempotency, retries on execution paths should be treated as new work.

Trust Boundaries

Keel governs the public AI request surface it documents today, including the public decision and execution routes described in this docs site.

That guarantee should not be stretched beyond the documented supported routes. Dashboard-only paths, operator tooling, future endpoints, and provider behavior outside Keel’s documented request boundary are not covered by this page.

For the conservative security boundary, see Threat Model and Security.

Current Limits

These guarantees apply to the current documented public surface, not every internal route and not every future route Keel may add later.

If a route is undocumented, internal-only, experimental, or not yet part of the published public API surface, assume it may change without the guarantees described here until it is explicitly documented.

Scope and Limits — full coverage and non-claim model
Security
Threat Model
Known Limits
Idempotency
Errors
Public API Surface