Execution Architecture

Managed execution is how Keel normally works. Keel evaluates the proposed action, dispatches only after an allow decision, and records the lifecycle facts the route supports. Choose among the managed routes by request shape and sync or async behavior. Use external enforcement, historically called permit-first, only when another trusted system already owns the execution boundary.

For the orienting glossary that introduces these modes, see Concepts.

At a glance

Reading the table:

• Provider call by — who issues the HTTP request to the upstream provider. Keel for managed execution; the caller for permit-first.
• Provider key held by — where the upstream provider’s API key lives. Keel-managed modes resolve provider credentials server-side; permit-first leaves credentials with the caller.
• Request shape — the body the caller must construct.
• Response shape — what the route returns. Normalized envelopes are stable across providers; provider-native preserves provider-specific fields.

Unified execute

Route: POST /v1/execute.

Who it is for. Applications that already have a provider-shaped input payload and want Keel to handle target resolution, permit evaluation, dispatch, and a normalized response. Unified execute is the primary public runtime surface for new integrations.

What Keel owns

• Target resolution before execution (alias resolution, project-scoped health, active routing budgets)
• Permit evaluation
• Provider dispatch through adapters
• Normalized response envelope plus a resolved metadata block
• Usage and accounting persistence

What the caller owns

• Constructing the provider-shaped input payload
• Choosing whether to send provider/model explicitly or let Keel resolve

Trade-offs. Lower-friction than permit-first when the caller wants Keel to own dispatch; less provider-native than the proxy routes; not interchangeable with POST /v1/executions despite the similar name.

Current limits

• Target resolution is explicit and rule-based, not a claim of broad autonomous routing.
• The contract is public and stable, but it is not the same request shape as /v1/executions — see Routing for the per-surface capability matrix.

Provider-neutral execution

Route: POST /v1/executions.

Who it is for. Applications that want a single canonical request and response shape across providers. The execution contract is provider-neutral: the same operation and inputs produce stable, normalized outputs regardless of which provider Keel dispatches to.

What Keel owns

• Permit formation and evaluation
• Routing plan binding from the public routing envelope
• Provider dispatch through adapters
• Usage reconciliation, ledger writes, and lifecycle persistence

What the caller owns

• Canonical input construction (operation, messages or inputs, parameters, optional routing)
• Any client-side retry policy against the Keel API
• Choosing sync or the current stream subset

Trade-offs. Cleaner than provider-native proxies for multi-provider integrations; narrower than provider-native surfaces — not every provider-specific feature is exposed through this contract. The provider-neutral envelope is the most portable shape Keel offers.

Current limits

• Streaming is narrower than the non-stream path.
• Routing and fallback behavior are bounded by the surface’s routing capability matrix.

Provider-specific proxy

Routes: POST /v1/proxy/openai, POST /v1/proxy/anthropic, POST /v1/proxy/google, POST /v1/proxy/xai, POST /v1/proxy/meta.

Who it is for. Applications that want to keep provider-native payloads and provider-native responses while Keel governs the request, holds provider credentials, and persists audit evidence. Proxy mode is the right choice when the caller depends on a provider-specific feature that the provider-neutral contract does not expose.

What Keel owns

• Stripping known transport and auth override fields from the inbound payload
• Permit evaluation and supported prompt-firewall checks
• Provider-key lookup and adapter dispatch
• Idempotency replay and caching on proxy paths
• Usage and accounting persistence and response headers

What the caller owns

• Constructing provider-native payloads
• Understanding provider-specific differences in supported operations and streaming behavior

Trade-offs. Closest to provider semantics; highest route-specific behavior — proxy routes are not interchangeable with one another. Capability coverage differs materially by provider.

Current limits

• Public routing is exposed only on the OpenAI and Anthropic proxy routes.
• Public streaming is currently primarily implemented on the OpenAI proxy.
• Capability coverage differs by provider — see Proxy Execution.

Async jobs

Routes: POST /v1/jobs, GET /v1/jobs/{job_id}.

Who it is for. Applications that want governed execution decoupled from the request/response lifetime — for example, batch processing, long-running generation, or workloads where the caller does not want to hold an HTTP connection open.

What Keel owns

• Job persistence and queue state
• Background execution through the shared governance and execution pipeline
• Usage and accounting persistence
• Optional best-effort callback delivery

What the caller owns

• Submitting the canonical permit plus provider payload
• Polling job status or receiving callbacks
• Handling eventual completion instead of inline results

Trade-offs. Durable status plus optional callback support; more moving parts than sync routes; distinct job_id and request_id lifecycles.

Current limits

• Callback URLs must pass outbound-policy validation.
• Async uses shared governance and execution machinery, but status semantics are job-oriented rather than identical to sync routes.
• Async job callbacks use bounded in-process retries; callers that need durable outbound delivery should use webhook subscriptions instead.

Realtime session governance

Routes: POST /v1/sessions, session-scoped event and turn routes, and POST /v1/sessions/{session_id}/end.

Who it is for. Customer-operated voice gateways and sidecars that need a session permit, locked policy snapshot, turn decisions, action-child permits, and verifier-readable session evidence while retaining their provider media connection.

What Keel owns

• Session-start and turn policy decisions
• Action-child permit issuance for external tool calls
• Validation and persistence of submitted signed voice atoms
• Session-chain and attestation assembly from the evidence Keel received

What the caller owns

• The provider connection, audio capture, playback, and provider credentials
• Enforcing each Keel decision before an external tool call
• Provider-specific retry, interruption, and reconnection behavior
• The truth and completeness of sidecar-submitted events and terminal usage

Trade-offs. This applies Keel’s session governance and evidence model without moving raw voice media into Keel. It is not the same dispatch boundary as /v1/execute, /v1/executions, or /v1/proxy/*: arbitrary media and tool actions performed by the customer runtime remain outside Keel-managed dispatch.

See Realtime Voice for the OpenAI GPT-Live and Realtime adapter boundary and the session endpoint sequence.

Advanced external enforcement (permit-first)

Route: POST /v1/permits (decision); POST /v1/permits/{permit_id}/usage (closeout).

Who it is for. Architectures that already have another trusted enforcement point and cannot use Keel-managed dispatch. Keel records the policy and budget decision in an AI Permit; the external system owns downstream enforcement, the provider call and the truthfulness of later closeout material.

What Keel owns

• Request authentication and project scoping
• Canonical permit evaluation (policy, budget, governance event)
• Idempotent permit persistence
• Optional later usage closeout through the public usage route

What the caller owns

• The actual provider call and its credentials
• Retry and transport behavior
• Collecting final usage and cost
• Reporting completed usage back to Keel when desired

Trade-offs. Narrow integration contract and decoupling from provider transport, but no Keel-controlled dispatch boundary and less automatic lifecycle evidence. Use it only when the external enforcement point is trusted to honor the decision and constraints.

Current limits

• Public Permit closeout requires supplied receipt or callback material and a positive billed cost. That material adds closeout evidence; it does not make the caller-owned provider call directly observed by Keel.
• The prompt firewall does not run on permit-only requests.
• Caller-executed traffic is outside Keel’s outbound policy because Keel does not make the provider call.
• Reported usage is trusted by Keel until verification material is attached. For the broader observation boundary, see Scope and Limits § Permit-first observation boundary.

Worked example: managed default and advanced contrast

The same task (“summarize a customer support ticket in one sentence”) implemented three ways. The differences are not in the AI work — they are in who owns dispatch and what the caller’s code looks like.

As unified execute

curl -sS -X POST https://api.keelapi.com/v1/execute \
  -H "Authorization: Bearer keel_sk_<project_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-1234-summary" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o-mini",
    "input": {
      "messages": [
        {"role": "user", "content": "Summarize this ticket in one sentence: <ticket-body>"}
      ],
      "max_tokens": 80,
      "temperature": 0
    }
  }'

Keel resolves the target, evaluates the permit, calls OpenAI, and returns a normalized envelope with both the model output and a resolved block describing the selection.

As provider-specific proxy

curl -sS -X POST https://api.keelapi.com/v1/proxy/openai \
  -H "Authorization: Bearer keel_sk_<project_key>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-1234-summary" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Summarize this ticket in one sentence: <ticket-body>"}
    ],
    "max_tokens": 80
  }'

The body is the OpenAI-native chat-completion payload. Keel evaluates the permit, dispatches to OpenAI, and returns OpenAI’s native response shape with Keel headers attached for governance correlation.

Advanced: as external enforcement (permit-first)

# 1. Ask Keel for a decision.
curl -sS -X POST https://api.keelapi.com/v1/permits \
  -H "Authorization: Bearer keel_sk_<project_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_uuid>",
    "idempotency_key": "ticket-1234-summary",
    "subject": {"type": "user", "id": "agent_42", "attributes": {}},
    "action": {"name": "ai.generate", "attributes": {}},
    "resource": {
      "type": "request",
      "id": "ticket_1234",
      "attributes": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "estimated_input_tokens": 800,
        "estimated_output_tokens": 60
      }
    }
  }'
 
# 2. If the decision is "allow", call OpenAI from your application.
# 3. Report observed usage back to Keel. Closing out a permit-first request
#    requires an admin-scope project API key and verification material.
curl -sS -X POST https://api.keelapi.com/v1/permits/<permit_id>/usage \
  -H "Authorization: Bearer keel_sk_<admin_project_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "actual_input_tokens": 812,
    "actual_output_tokens": 47,
    "actual_total_tokens": 859,
    "cost_usd_micros": 215,
    "usage_idempotency_key": "ticket-1234-usage",
    "verification": {
      "method": "provider_receipt",
      "provider_request_id": "req_ticket_1234",
      "receipt_json": { "request_id": "req_ticket_1234" }
    }
  }'

What changed

• Unified execute lets the caller stop maintaining a direct OpenAI dependency and gives back a normalized response that does not change shape if Keel later routes to a different provider.
• Provider-specific proxy keeps the caller on OpenAI’s native API surface, which is the right choice when the caller depends on an OpenAI-specific feature that the canonical envelope does not expose.
• External enforcement preserves a caller-owned OpenAI path, but that trusted external system must enforce Keel’s decision and constraints.

How to choose

For new integrations, unified execute is the recommended default. It has the lowest friction with full Keel-managed evidence. Provider-specific proxy is the compatibility path when a provider-specific feature is essential. External enforcement is advanced and requires a trusted system outside Keel to own the execution boundary.

What this surface does and does not claim

• The managed routes are not interchangeable. Choose by request shape and whether you need sync results; Keel owns dispatch on each.
• External enforcement does not directly observe the provider call. Reported usage is trusted; the verification track is the bridge to provider-side receipt evidence.
• Public realtime governance is exposed through /v1/sessions and its session-scoped evidence routes. These routes do not proxy the provider media stream and do not turn customer-executed tools into Keel-managed dispatch.
• Mode availability is not plan-gated — every plan that supports a route can use the mode. Some capabilities inside a mode are plan-gated: see Plans & Entitlements for cross-provider routing, prompt-firewall strengthening, integrity verification API, and other gated features.

Related pages

• Concepts — orienting glossary
• Quickstart — send a first governed request
• Permits — the permit record contract
• Executions — provider-neutral execution surface
• Execute — unified execute surface
• Proxy Execution — provider-native proxy surfaces
• Routing — per-surface routing capability matrix
• Plans & Entitlements — capabilities gated within each mode