Developer DocsstableUpdated 2026-07-06

SDKs

Use Kadryn SDK examples and integration patterns for Gateway, direct ingest, tracing and webhooks.

SDKs and examples help you integrate Kadryn faster.

Use this page to understand the recommended client shape even when you call Kadryn with plain HTTP.

A Kadryn client should be configured server-side with:

bash
KADRYN_API_KEY="kadryn_live_..."
KADRYN_API_BASE_URL="https://api.kadryn.com/v1"
KADRYN_GATEWAY_BASE_URL="https://gateway.kadryn.com/v1"

Minimal TypeScript wrapper

ts
type KadrynClientConfig = {
  readonly apiKey: string;
  readonly apiBaseUrl: string;
  readonly gatewayBaseUrl: string;
};

export function createKadrynHeaders(apiKey: string): HeadersInit {
  return {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  };
}

Gateway helper

ts
type SendGatewayChatInput = {
  readonly config: KadrynClientConfig;
  readonly project: string;
  readonly feature: string;
  readonly environment: string;
  readonly requestGroupId?: string;
  readonly body: {
    readonly model: string;
    readonly messages: readonly {
      readonly role: "system" | "user" | "assistant";
      readonly content: string;
    }[];
  };
};

export async function sendGatewayChat({
  config,
  project,
  feature,
  environment,
  requestGroupId,
  body,
}: SendGatewayChatInput): Promise<Response> {
  return fetch(`${config.gatewayBaseUrl}/chat/completions`, {
    method: "POST",
    headers: {
      ...createKadrynHeaders(config.apiKey),
      "X-Kadryn-Project": project,
      "X-Kadryn-Feature": feature,
      "X-Kadryn-Environment": environment,
      ...(requestGroupId
        ? { "X-Kadryn-Request-Group-Id": requestGroupId }
        : {}),
    },
    body: JSON.stringify(body),
  });
}

Direct ingest helper

ts
type UsageEvent = {
  readonly timestamp: string;
  readonly provider: string;
  readonly model: string;
  readonly inputTokens: number;
  readonly outputTokens: number;
  readonly costCents: string;
  readonly project: string;
  readonly feature: string;
  readonly environment: string;
};

export async function sendUsageEvent(input: {
  readonly config: KadrynClientConfig;
  readonly event: UsageEvent;
  readonly idempotencyKey: string;
}): Promise<Response> {
  return fetch(`${input.config.apiBaseUrl}/usage/events`, {
    method: "POST",
    headers: {
      ...createKadrynHeaders(input.config.apiKey),
      "Idempotency-Key": input.idempotencyKey,
    },
    body: JSON.stringify(input.event),
  });
}

Production expectations

Your wrapper should:

  • keep secrets server-side;
  • require metadata;
  • support idempotency keys;
  • preserve trace IDs;
  • avoid logging secrets;
  • expose request IDs in errors;
  • distinguish retryable and permanent errors.

What SDKs should not hide

Do not hide:

  • policy blocks;
  • validation errors;
  • provider route failures;
  • retry exhaustion;
  • missing metadata;
  • idempotency conflicts.

A good client makes production failure modes explicit.