Workflow Intent Header Convention
Direct API callers and orchestrator integrations attach governed requests to a declared workflow with:
X-Keel-Workflow-Id: <workflow_id>The value must match a workflow declared in the authenticated project. Keel reads the header during permit evaluation and records the workflow state observed at decision time.
Why it is a header
Workflow id is request context, not provider input. Keeping it in a header lets existing permit, execute, and proxy request bodies stay compatible while SDKs and orchestrators can thread workflow context through normal transport metadata.
The header applies to governed request routes such as:
POST /v1/permitsPOST /v1/executePOST /v1/executionsPOST /v1/proxy/*
Direct API example
curl -sS https://api.keelapi.com/v1/execute \
-H "Authorization: Bearer $KEEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: wf-exec-001" \
-H "X-Keel-Workflow-Id: invoice-batch-2026-05-13" \
-d '{
"provider": "openai",
"model": "gpt-5-mini",
"input": {
"messages": [
{"role": "user", "content": "Summarize invoice INV-1001."}
],
"max_tokens": 80
}
}'Orchestrator guidance
An orchestrator should declare the workflow once, store the returned workflow_id, and attach X-Keel-Workflow-Id to every governed model call that belongs to that run.
If a call references an unknown, completed, expired, or rejected workflow, Keel denies the request with workflow_intent.unknown_or_inactive.
If the workflow has reached max_calls, Keel denies the request with workflow_intent.max_calls_exceeded.
Egress behavior
X-Keel-Workflow-Id is Keel request metadata. It is stripped before upstream provider dispatch and before forwarding to external tools or MCP servers. Providers should not receive the header.