LLM Proxy

Base URL: https://api.nozle.app/engine/api/v1 Reverse proxy routes that forward LLM requests to OpenAI or Anthropic and record their token usage as a usage event in your organization, signed with your own X-Nozle-Key. Use it when you cannot change your LLM client. When you can, prefer usage capture in the SDK: it works with any provider and keeps LLM traffic out of Nozle. The usage event bills only when your plan has a metered Feature with the same code; see Set up AI token billing.

LLM proxy routes use X-Nozle-Key for Nozle authentication, not the Authorization header. The Authorization header is reserved for the customer’s own LLM provider API key, which the proxy forwards untouched to the provider.

/api/v1/proxy/openai/v1/*

Proxies all requests to https://api.openai.com/v1/*. Usage is recorded for chat completions (including streams), the Responses API and embeddings. Auth: X-Nozle-Key header (sk_ only) Required headers:

Header	Description
`X-Nozle-Key`	Your Nozle secret key (`sk_nozle_...`). It needs `event:write` permission.
`X-Nozle-Customer-Id`	External customer ID to bill for this usage. Missing returns `400`.
`Authorization`	Customer’s OpenAI API key (`Bearer sk-...`)

Optional headers:

Header	Description
`X-Nozle-Subscription`	External subscription ID to bill. It must be an active subscription of that customer. Needed when the customer has several active subscriptions.
`X-Nozle-Feature-Code`	Code of the usage event. Default `llm_tokens`. Must match a metered Feature to bill.
`X-Nozle-Feature`	Stored as the `feature` property of the event.

cURL

curl -X POST https://api.nozle.app/engine/api/v1/proxy/openai/v1/chat/completions \
  -H "X-Nozle-Key: sk_nozle_your_secret_key" \
  -H "X-Nozle-Customer-Id: cust_123" \
  -H "Authorization: Bearer sk-customer-openai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<openai-model>",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

/api/v1/proxy/anthropic/v1/*

Proxies all requests to https://api.anthropic.com/v1/*. Auth: X-Nozle-Key header (sk_ only) Required headers:

Header	Description
`X-Nozle-Key`	Your Nozle secret key (`sk_nozle_...`). It needs `event:write` permission.
`X-Nozle-Customer-Id`	External customer ID to bill for this usage. Missing returns `400`.
`x-api-key`	Customer’s Anthropic API key
`anthropic-version`	Anthropic API version

Optional headers:

Header	Description
`X-Nozle-Subscription`	External subscription ID to bill. It must be an active subscription of that customer. Needed when the customer has several active subscriptions.
`X-Nozle-Feature-Code`	Code of the usage event. Default `llm_tokens`. Must match a metered Feature to bill.
`X-Nozle-Feature`	Stored as the `feature` property of the event.

cURL

curl -X POST https://api.nozle.app/engine/api/v1/proxy/anthropic/v1/messages \
  -H "X-Nozle-Key: sk_nozle_your_secret_key" \
  -H "X-Nozle-Customer-Id: cust_123" \
  -H "x-api-key: customer-anthropic-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<anthropic-model>",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

The proxy returns the provider’s response unchanged. Your customer’s API key is forwarded but never stored. Token usage is read from the response and recorded as a usage event in your organization, with the code from X-Nozle-Feature-Code (default llm_tokens) and the external_subscription_id of the subscription it is billed to.

Before this release the proxy recorded usage under Nozle’s own organization instead of yours, so proxy usage from earlier calls is not in your account.

Subscription

Engine finds the subscription to bill before it calls the provider. Without X-Nozle-Subscription, the customer must have exactly one active subscription. With it, that subscription must be an active subscription of the customer in your organization. Otherwise Engine answers 422 and the provider is not called:

Case	Response
Unknown customer, no active subscription, or `X-Nozle-Subscription` names no active subscription of the customer	`422 active_subscription_not_found`
Several active subscriptions and no `X-Nozle-Subscription`	`422 active_subscription_ambiguous`
The lookup failed	`503 unavailable`. Retry later.

How it works

The path after /proxy/openai/ or /proxy/anthropic/ is sent to the provider host unchanged, with the same method, query string, headers and body, except as noted below.
Engine removes X-Nozle-Key, X-Nozle-Customer-Id, X-Nozle-Subscription, X-Nozle-Feature and X-Nozle-Feature-Code before forwarding. All other headers, including Authorization and x-api-key, are forwarded. Accept-Encoding is set to identity so the usage can be read.
A chat completion stream ("stream": true to /chat/completions) is sent with stream_options.include_usage: true, because OpenAI leaves usage out of streams otherwise.
Streaming (text/event-stream) responses are passed through as they arrive; usage is read from the stream as it passes.
Usage is recognised by the shape of the response: chat completions, the Responses API, and Anthropic messages, including cached input and cache writes.
An event is recorded only for a successful response that reports more than zero tokens. It carries external_customer_id and the resolved external_subscription_id, so it is billed to that subscription. Its transaction_id is llm-<format>-<response id>, so the same response is never billed twice. Its properties are provider, provider_host, model, input_tokens (all input, including cached), output_tokens, latency_ms and, when sent, feature. Recording runs in the background; a recording failure does not change the response.

Errors

These come from Engine. Provider errors are returned unchanged, with the provider’s status and body.

Status	Body	Meaning
`400`	`{"code": "invalid_request", "error": "missing X-Nozle-Customer-Id header"}`	`X-Nozle-Customer-Id` is missing.
`401`	`{"code": "unauthorized", "error": "missing X-Nozle-Key header"}`	`X-Nozle-Key` is missing.
`401`	`{"code": "unauthorized", "error": "invalid nozle key"}`	The key is unknown.
`403`	`{"code": "publishable_key_not_allowed", ...}`	A publishable key was used.
`403`	`{"code": "permission_denied", "error": "API key requires event:write permission"}`	The key cannot write events, so the call is refused before it reaches the provider.
`422`	`{"code": "active_subscription_not_found", "error": "customer has no matching active subscription"}`	The customer is unknown, has no active subscription, or `X-Nozle-Subscription` names no active subscription of the customer. The provider is not called.
`422`	`{"code": "active_subscription_ambiguous", "error": "customer has multiple active subscriptions; set X-Nozle-Subscription"}`	The customer has several active subscriptions. Send `X-Nozle-Subscription`. The provider is not called.
`502`	Empty	Engine could not reach the provider.
`503`	`{"code": "unavailable", "error": "API key verification is unavailable"}`	The key could not be verified. Retry later.
`503`	`{"code": "unavailable", "error": "subscription lookup is unavailable"}`	The subscription could not be looked up. The provider is not called. Retry later.

Overview

Application Workflows

Billing Resources

Usage & Metering

Invoicing & Payments

Platform & Operations

/api/v1/proxy/openai/v1/*

/api/v1/proxy/anthropic/v1/*

Subscription

How it works

Errors

​/api/v1/proxy/openai/v1/*

​/api/v1/proxy/anthropic/v1/*

​Subscription

​How it works

​Errors

/api/v1/proxy/openai/v1/*

/api/v1/proxy/anthropic/v1/*

Subscription

How it works

Errors