Architecture

This page describes Keel’s architecture at the product boundary. It is about guarantees, route families, and trust boundaries, not internal stage names or service wiring.

Keel is a permit-centric AI governance control plane with governed execution and proxy surfaces. Every public route either returns a decision, executes a governed request, or closes the loop with usage and evidence data.

A permit is the recorded decision Keel makes before an AI call runs. Every governed request produces a permit; the permit ties the decision, the policy that applied, the budget state, and the evidence into one artifact you can read back later.

Core contract

The public runtime is organized around one shared idea: Keel evaluates the request before a Keel-managed provider call is dispatched.

Policies are expressed as rule sets with nested boolean conditions and evaluated by a unified engine at permit time. Available actions include allow, deny, constrain, rate-limit, throttle, and budget enforcement.

That gives developers and buyers a few concrete guarantees:

• one place to enforce supported policy and budget controls
• a stable choice between decision-only, primary runtime, provider-neutral, and provider-native execution routes
• no provider call on a denied Keel-managed execution request
• persisted records for permits, executions, usage, jobs, and related readback flows

The main public modes are:

Public request model

Across the public routes, Keel presents one public model:

• Decision Boundary: Keel authenticates the project and applies the documented governance checks before execution.
• Execution: if the route is Keel-managed and the request is allowed, Keel executes it against the selected provider.
• Evidence: Keel records the decision outcome and route-appropriate usage or execution evidence.

The routes differ intentionally:

• choose /v1/permits when your application needs the decision boundary but keeps provider control
• choose /v1/execute when you want the primary public runtime surface with normalized output
• choose /v1/executions when you want the most portable public execution contract
• choose /v1/proxy/* when provider-native parity matters more than normalization

Route example

These are the routes most developers will touch first:

• POST /v1/permits for a decision-first flow
• POST /v1/execute for a provider-shaped request with normalized output
• POST /v1/executions for a canonical provider-neutral execution request
• POST /v1/proxy/* for provider-native payloads

Example:

curl -sS https://api.keelapi.com/v1/execute \
  -H "Authorization: Bearer keel_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: architecture-demo-001" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o-mini",
    "input": {
      "messages": [
        {"role": "user", "content": "Describe the Keel request flow in one sentence."}
      ],
      "max_tokens": 80
    }
  }'

Keel resolves the concrete target for this request, applies the documented execution controls for the route, executes the provider call, and returns a normalized execution envelope.

What Keel guarantees today

• A denied Keel-managed execution request does not reach the provider.
• Decision and evidence records are tamper-evident on the integrity path; signed exports and externally anchored checkpoints are independently verifiable. See Trust & Integrity.
• Tenant isolation is enforced at both the database and application layers across the decision and evidence path. Deployment-specific isolation coverage is reviewed with customers during onboarding.
• Keel supports permit-first and Keel-managed execution patterns; the verification track attaches receipt evidence to permit-first integrations.
• Keel offers an optional external accounting-durability mode that checkpoints accounting envelopes before provider dispatch.
• Routing is explicit and recorded; selection is auditable and never bypasses governance.

For coverage boundaries — provider parity, replay scope, permit-first observation, accounting precision, and the integrity proof model — see Scope and Limits.

Next reading

• Quickstart
• Permits
• Executions
• Execute
• API Reference
• Security
• Observability