Overview
Understand the developer integration model for Gateway, direct ingest, metadata, tracing, webhooks and production readiness.
Kadryn connects AI usage to costs, owners, policies and operational evidence.
A good developer integration does four things:
- authenticates server-side systems securely;
- sends complete usage or runtime traffic;
- attaches metadata that makes spend attributable;
- preserves traceability for debugging and audit.
Integration modes
Kadryn supports two primary integration modes.
| Mode | What it does | Best for |
|---|---|---|
| Gateway | Your application sends provider-compatible AI requests through Kadryn. | Runtime control, budget caps, policy checks, route visibility and request tracing. |
| Direct ingest | Your application or pipeline sends usage events after provider execution. | Offline usage import, backfills, external proxies and observability without proxying. |
Use Gateway when Kadryn must evaluate a request before provider execution.
Use Direct ingest when Kadryn only needs to receive usage data after the request happened.
Minimum production contract
Every production integration should provide:
- a workspace API key;
- a project identifier;
- an environment identifier;
- a feature, workflow or agent identifier;
- a trace ID or request group ID;
- idempotency keys for retryable writes;
- safe error handling;
- server-side secret storage.
Data flow
A typical integration produces these signals:
- authentication identifies the workspace;
- metadata identifies the business context;
- usage or gateway events record provider, model, tokens, cost, latency and status;
- Logs & Traces expose request-level debugging;
- Costs and Guardrails use the normalized records;
- Alerts, reports and webhooks notify downstream systems.
What to verify first
Before rolling out production traffic, verify that:
- a test request appears in Developers → Logs & Traces;
- the request has the expected project and environment;
- cost appears in the right period;
- failures include enough IDs for debugging;
- no secret is visible in frontend code or logs;
- retries do not create duplicate usage.
Recommended rollout
Start with a single low-risk service.
Send traffic from one environment, such as staging, then verify:
- authentication;
- route readiness;
- metadata quality;
- trace search;
- cost normalization;
- error handling;
- idempotency behavior.
Only then expand to production and additional services.