API Reference•stable•Updated 2026-05-14

Usage Ingestion API

Send normalized AI usage events to Kadryn without routing provider traffic through Gateway.

Endpoint

Use the Usage Ingestion API to send AI usage events from your backend to Kadryn after provider calls complete.

bash

POST /v1/usage/events
Authorization: Bearer $KADRYN_API_KEY
Content-Type: application/json
Idempotency-Key: usage_event_123

Request body

json

{
  "provider": "openai",
  "model": "gpt-4.1-mini",
  "project": "support-copilot",
  "environment": "production",
  "feature": "ticket-summary",
  "inputTokens": 1200,
  "outputTokens": 240,
  "requestId": "req_123",
  "occurredAt": "2026-05-14T10:30:00.000Z"
}

Idempotency

Send a stable idempotency key for retry-safe ingestion. Reusing the same key for the same usage event prevents duplicate cost records.

Response

A successful response confirms that Kadryn accepted the event and returns a correlation ID that can be used in diagnostics.

Errors

Handle validation errors, authentication failures, permission errors, conflicts, rate limits and retryable server errors explicitly.