Skip to Content
Concepts

Concepts

Keel is a permit-driven decision and execution layer in front of AI providers. It gives an application one place to evaluate policy, persist audit evidence, and either execute itself or hand off provider dispatch to Keel. This page introduces the integration modes Keel supports and the domain objects every other surface refers to.

Five integration modes

Keel exposes five public integration modes. They are not equivalent — each shifts the boundary of what Keel owns versus what the caller owns. The Execution Modes page covers each in depth; this page is the orienting summary.

Permit-first

The caller asks Keel for a decision through POST /v1/permits, then performs the provider call from its own infrastructure, and reports completed usage back to Keel through POST /v1/permits/{permit_id}/usage. Keel owns the decision record; the caller owns transport.

Unified execute

The caller submits a provider-shaped payload to POST /v1/execute. Keel resolves the target (provider/model alias resolution, project-scoped health, active routing budgets), evaluates the permit, dispatches to the provider, and returns a normalized response with a resolved block.

Provider-neutral execution

The caller submits a canonical operation plus messages or inputs to POST /v1/executions. Keel evaluates the permit, dispatches to the provider through its adapters, and returns a normalized execution envelope.

Provider-specific proxy

The caller submits provider-native payloads to POST /v1/proxy/openai, POST /v1/proxy/anthropic, POST /v1/proxy/google, POST /v1/proxy/xai, or POST /v1/proxy/meta. Keel evaluates the permit, dispatches through provider-native adapters, and returns provider-native responses.

Async jobs

The caller submits a canonical permit plus provider payload to POST /v1/jobs. Keel persists job state, executes in the background through the same governance and execution path, and either delivers the result via best-effort callback or makes it fetchable through GET /v1/jobs/{job_id}.

Core domain objects

Every other page on this site references the objects below.

Project

The unit of tenancy. Projects hold policy overrides, permits, governed request state, provider keys, runtime API keys, async jobs, and observability data. All Keel public runtime routes scope to a project.

Project API key

The runtime credential a caller sends to public permit, execute, executions, proxy, jobs, and request-timeline routes. Project API keys are project-scoped and authenticate every request. They are stored hashed; raw key material is shown once at creation and is never returned again.

Provider key

A server-side provider secret stored per project. Keel-managed execution dispatches use the project’s stored provider key. Provider keys are encrypted at rest with AES-256-GCM and are never returned to runtime callers in raw form.

Permit

The persisted decision record Keel produces for every governed request. A permit captures the decision (allow, deny, challenge), the reason code, the matched policy, the budget snapshot at decision time, the routing intent, and the request fingerprint. The permit is the canonical anchor for everything else — usage, verification, replay, and signed exports all reference back to it.

Governed request

The logical request-level record Keel uses to track final decision, final status, billability, and the surface that produced it. A governed request typically corresponds to a permit and an execution event sequence; the governed request is the layer that ties them.

Async job

A persisted background execution record with its own status, request id, result assets, usage metrics, and callback metadata. Async jobs reuse the same governance and execution pipeline as sync routes; the status semantics differ.

Execution event

A normalized lifecycle event such as routing.selected_model, provider.request_sent, usage.recorded, job.processing, or request.completed. Execution events feed Timeline Replay and are the building blocks of customer-visible request lifecycles.

Request timeline

A replay view reconstructed from persisted permits, governed request rows, execution events, async job rows, and usage rows. The timeline is rebuilt from persisted data only; Keel does not interpolate latency, durations, or state transitions that were not written.

Routing

The explicit selection of a provider/model target for a governed request — including alias resolution on POST /v1/execute, request-scoped routing on POST /v1/executions, and explicit fallback chains. See Routing for the two-layer model and per-surface capability matrix.

Usage record

The actual execution accounting attached after dispatch — token counts, cost in microdollars, provider response identifiers, and timing. Usage is recorded on every Keel-managed dispatch; on permit-first integrations, usage is reported back through POST /v1/permits/{permit_id}/usage.

What this surface does and does not claim

  • The integration modes are not interchangeable. Each makes a different trade-off between Keel and the caller; choose deliberately.
  • Permit-first means Keel owns the decision but the caller owns provider transport. Keel does not directly observe the provider call on permit-first flows; the caller’s reported usage is trusted but unverified unless the verification track is used.
  • Realtime session APIs are not part of the current public surface.
  • The objects in the glossary are persisted records, not synthetic abstractions. Every object listed has a database backing, an audit trail, and stable identifiers.
Last updated on Edit this page on GitHub 
ArchitectureQuickstart