Copy page

AI Gateway

AI Gateway Universal API

Zuplo AI Gateway provides a universal API that standardizes interactions with various AI providers. This API follows the OpenAI API specification, making it easy to integrate with existing apps that already use OpenAI's API.

Using the Universal API

Every AI Gateway app serves the Universal API. The app page in the portal shows each app's API URL, which ends in the app's ID—for example https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e. Client libraries expect a base URL ending in /v1, so append that suffix. When the gateway runs the authentication policy, send the app's API key as a bearer token.

Models are referenced as providerName/model, where providerName is the provider name configured in your gateway. This is how the gateway knows which provider to route each request to—and it means one app can use models from several providers through the same endpoint.

If you are using an SDK or library that supports custom base URLs, you can configure it to use your app's URL. For example, with the OpenAI Node.js SDK, you can set the baseURL option:

Code
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZUPLO_APP_API_KEY,
  baseURL:
    "https://my-gateway-main-2e18f50.zuplo.app/config_fe0a04972d2848e0a94ae4b8bcd1497e/v1",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-6-luna",
  messages: [
    {
      role: "user",
      content: "Write a one-sentence bedtime story about a unicorn.",
    },
  ],
});

console.log(response.choices[0].message.content);

Supported endpoints

Endpoint	Notes
/v1/chat/completions	Chat completions for every provider
/v1/embeddings	Embeddings for the providers marked in the capability matrix
/v1/responses	OpenAI Responses API: OpenAI, and the OpenAI-compatible models that serve it on Azure AI, Bedrock Mantle and OpenRouter
/v1/messages	Anthropic Messages API: Anthropic, and the Claude models of Azure AI, Bedrock Mantle, Vertex AI and OpenRouter

Jev is the exception: it serves TypeSafe's System One API on /v1/systemone, which takes a state and typed questions rather than chat messages. That endpoint isn't part of the Universal API. See Jev.

Request headers

The gateway forwards your request headers to the provider. A header your client or your own policies set—a session ID, a trace header, a feature flag—arrives with the request.

The gateway removes what it owns first:

Removed	Why
authorization, x-api-key, api-key, proxy-authorization, and cookies	Credentials addressed to the gateway. The provider gets its own credential from your provider configuration instead.
content-type, accept, anthropic-version, anthropic-beta	The gateway controls the wire format it sends upstream, which isn't always the one your client asked for.
openai-organization, openai-project, x-goog-api-key, x-goog-user-project	Another vendor's credentials and tenant selectors. They cause a 401 as soon as a request routes to a provider they don't belong to.
host, connection, transfer-encoding, content-length, and the rest of the hop-by-hop set	They describe the connection to the gateway, not the one to the provider.
cdn-loop, and anything starting with zp-, cf-, or x-amz-	They describe the path your request took to reach the gateway.

Everything else reaches the provider, including user-agent, x-forwarded-for, true-client-ip, idempotency-key, x-request-id, and the x-stainless-* headers the OpenAI and Anthropic SDKs set.

To change what the provider receives, add a header policy—set-headers-inbound, remove-headers-inbound, or clear-headers-inbound—to the app's policy chain. Headers are copied after the chain runs, so a policy that adds one puts it on the provider request too. Setting Authorization, x-api-key, or api-key in a policy doesn't override the credential from your provider configuration.

Bedrock Runtime isn't part of the Universal API and forwards a different set, described on its own page.