Developer Docs•stable•Updated 2026-07-06

Gateway

Route AI provider traffic through Kadryn for runtime control, cost visibility, policy enforcement and traceable debugging.

Kadryn Gateway lets your application send AI provider requests through Kadryn instead of calling the provider directly.

Use it when you need runtime visibility, cost attribution, policy checks, budget caps, provider routing, traceability and production debugging for AI traffic.

Gateway is the inline path.

If you only want to send historical or externally captured usage into Kadryn, use Direct ingest instead.

What you will do

In this guide, you will:

understand when to use Gateway;
create or select a Kadryn API key;
verify provider route readiness;
send a test request through Gateway;
attach project, feature, environment and tracing metadata;
verify the request in Logs & Traces;
handle common errors and retries.

When to use Gateway

Use Gateway when Kadryn must evaluate the request before or during provider execution.

Gateway is the right path for:

central request logging;
cost and token tracking;
project, feature and environment attribution;
budget caps and policy enforcement;
provider route readiness checks;
fallback and routing visibility;
runtime debugging in Logs & Traces;
production verification with trace IDs and request group IDs.

When not to use Gateway

Do not use Gateway when you only need offline usage import.

Use Direct ingest when:

traffic already went through another proxy;
you cannot place Kadryn inline yet;
you only need cost visibility after execution;
an external source already emits normalized usage events;
you are backfilling historical usage.

Gateway gives runtime control. Direct ingest gives observability without proxying traffic.

Request flow

Your application sends the AI request to Kadryn Gateway.
Kadryn authenticates the request with your Kadryn API key.
Kadryn attaches workspace context from headers and API key metadata.
Kadryn evaluates routing, policy and guardrail configuration.
Kadryn forwards the request to the selected provider route.
Kadryn records request, tokens, cost, status, latency and trace metadata.
Your application receives the provider-compatible response.
You inspect the event in Logs & Traces.

Gateway is the runtime entry point. Guardrails defines policies. Costs analyzes spend. Logs & Traces explains individual requests.

Base URL

https://gateway.kadryn.com/v1

For OpenAI-compatible chat completions:

POST https://gateway.kadryn.com/v1/chat/completions

Prerequisites

Before sending Gateway traffic:

create a Kadryn API key;
configure at least one provider key;
verify the provider route is ready;
identify the project and environment;
decide which metadata your policies require;
decide how your service handles retries and idempotency.

Quickstart request

export KADRYN_API_KEY="kadryn_live_..."

curl https://gateway.kadryn.com/v1/chat/completions \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Kadryn-Project: prod-api" \
  -H "X-Kadryn-Feature: support-agent" \
  -H "X-Kadryn-Environment: prod" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "user",
        "content": "Hello from Kadryn Gateway"
      }
    ]
  }'

Production request

curl https://gateway.kadryn.com/v1/chat/completions \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Kadryn-Project: billing-api" \
  -H "X-Kadryn-Feature: invoice-assistant" \
  -H "X-Kadryn-Environment: prod" \
  -H "X-Kadryn-Request-Group-Id: invoice-run-2026-07-06-001" \
  -H "Idempotency-Key: invoice-run-2026-07-06-001:step-01" \
  -H "traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" \
  -d '{
    "model": "gpt-4.1-mini",
    "messages": [
      {
        "role": "system",
        "content": "You are a support assistant for billing questions."
      },
      {
        "role": "user",
        "content": "Summarize the latest invoice status for this customer."
      }
    ],
    "temperature": 0.2
  }'

Required headers

Header	Required	Description
`Authorization`	Yes	Kadryn API key using `Bearer`.
`Content-Type`	Yes	Use `application/json`.
`X-Kadryn-Project`	Recommended	Project slug or ID for attribution.
`X-Kadryn-Feature`	Recommended	Feature, workflow or agent producing the request.
`X-Kadryn-Environment`	Recommended	Environment such as `dev`, `staging`, `prod`, `test` or `preview`.

Policies may require metadata that is technically optional.

Recommended headers

Header	Use it for
`X-Kadryn-Team`	Team ownership and reporting.
`X-Kadryn-Cost-Center`	Finance allocation and chargeback.
`X-Kadryn-Budget-Owner`	Ownership-based governance.
`X-Kadryn-Customer`	Customer-level unit economics.
`X-Kadryn-Tenant`	Tenant-level attribution.
`X-Kadryn-Workflow`	Workflow or job tracking.
`X-Kadryn-Agent`	Agent-level attribution.
`X-Kadryn-Request-Group-Id`	Group related provider calls into one business operation.
`Idempotency-Key`	Safe retry behavior.
`traceparent`	Distributed tracing correlation.

Gateway readiness

Gateway readiness can appear as:

State	Meaning	What to do
`ready`	Gateway can receive traffic and route to configured providers.	Send traffic and verify Logs & Traces.
`waiting_for_traffic`	Gateway is configured but no traffic has been observed.	Generate a test command or send a request.
`missing_api_key`	No usable Kadryn API key is available.	Create an API key.
`degraded`	At least one route, key or runtime signal needs attention.	Review routes, provider keys and Logs & Traces.

Provider route readiness

State	Meaning	Next step
`ready`	Provider route is configured and usable.	Send traffic.
`needs_provider_key`	A provider key is missing.	Add a provider key.
`provider_key_error`	A configured provider key fails validation or usage.	Fix or rotate the key.
`untested`	The route has not been verified.	Send a test request.

Verify in Logs & Traces

After sending a request, open:

Developers → Logs & Traces

Search by:

trace ID;
request group ID;
project;
feature;
environment;
provider;
model;
status;
fallback usage;
synthetic traffic.

Failure handling

Failure class	Retry?	What to do
Authentication error	No	Check the Kadryn API key.
Authorization error	No	Check role, plan and workspace access.
Validation error	No	Fix payload or headers.
Policy block	No	Inspect the decision and update metadata or policy.
Provider key error	No	Fix or rotate the provider key.
Provider error	Sometimes	Follow provider-specific retry rules.
Rate limit	Yes	Use backoff and preserve idempotency.
Timeout	Yes	Retry with idempotency.
Server error	Yes	Retry with bounded backoff.

Retry rules

For retryable failures:

keep the same Idempotency-Key;
keep the same X-Kadryn-Request-Group-Id;
preserve or link the same trace context;
use exponential backoff;
stop after a bounded number of attempts.

Security notes

Do:

keep Gateway credentials server-side;
use separate keys per environment where possible;
rotate keys regularly;
preserve trace IDs;
redact sensitive payloads when required.

Do not:

expose Kadryn API keys in the browser;
log Authorization headers;
put secrets in URLs;
send provider API keys in metadata.