Onwinds API

Onwinds is an OpenAI-compatible gateway for teams and production systems. Your organisation controls models, routing, governance, and spend centrally, and your users and your apps share the same control plane.

View API reference Contact

API surface

Onwinds exposes three public endpoints. They are OpenAI-compatible, so existing SDKs work with a base URL swap.

List models

returns the tenant’s logical models.

Chat completions

supports streaming and enforces policy + spend before tokens flow.

Embeddings

routes embeddings through your allowlist and bills deterministically.

Quickstart

Use your Onwinds API key with a standard OpenAI client. Set base URL to .

Chat (streaming)

Drop-in OpenAI SDK usage; Onwinds enforces routing, governance, and spend.

import OpenAI from "openai";

const client = new OpenAI({

apiKey: process.env.ONWINDS_API_KEY,

baseURL: "https://api.onwinds.com/v1",

defaultHeaders: {

"x-onwinds-region-required": "eu",

"x-onwinds-retention-mode": "zdr",

});

await client.chat.completions.create({

model: "gpt-5-mini",

stream: true,

max_tokens: 800,

messages: [{ role: "user", content: "Write a board-ready update for Q3." }],

});

Governance headers

Governance is enforced per request. Use these headers to require EU-only routing and a stricter retention posture.

x-onwinds-region-required

Set to to require an EU-compliant route. If no compliant route exists, the request does not run (fail-closed).

x-onwinds-retention-mode

Set to to request Zero Data Retention for Onwinds logging paths while preserving billing metadata.

Minimal example

curl https://api.onwinds.com/v1/chat/completions \
  -H "Authorization: Bearer ow_…" \
  -H "Content-Type: application/json" \
  -H "x-onwinds-region-required: eu" \
  -H "x-onwinds-retention-mode: zdr" \
  -d '{"model":"gpt-5-mini","stream":true,"max_tokens":256,"messages":[{"role":"user","content":"Write a concise incident update."}]}'

Common pitfalls

Provider retention differs. Onwinds doesn’t train on your prompts or outputs, but upstream provider handling depends on your selected provider and your contract/configuration with them.
ZDR is about Onwinds logging. You still get the metadata required for billing, limits, and request traceability.
Fail-closed means fail-fast. If you require EU routing and no EU route exists, you should handle that error path in your client (fallback model, retries, or policy changes).

Governance overview →

Embeddings

Embeddings are tenant scoped. Use the embeddings endpoint with the logical model `onwinds/embeddings`.

Embeddings request

OpenAI-compatible embeddings call through Onwinds.

import OpenAI from "openai";

const client = new OpenAI({

apiKey: process.env.ONWINDS_API_KEY,

baseURL: "https://api.onwinds.com/v1",

});

const res = await client.embeddings.create({

model: "text-embedding-3-small",

input: "Summarize this document in one sentence.",

});

console.log(res.data[0]?.embedding?.length);

Models

List the logical models your tenant has enabled and allowlisted.

List models

Returns `onwinds/*` logical models and metadata.

import OpenAI from "openai";

const client = new OpenAI({

apiKey: process.env.ONWINDS_API_KEY,

baseURL: "https://api.onwinds.com/v1",

});

const models = await client.models.list();

console.log(models.data.map((m) => m.id));

Identity model

Requests are always executed in a tenant context. API keys are tenant-scoped and the gateway derives context server-side; clients do not provide tenant IDs in the payload.

Humans

Users sign in to the workspace and the platform applies organisation policy (allowed models, governance, and spend) automatically.

Apps & agents

Apps use an API key on the OpenAI-compatible endpoints. Each request is attributed and billed deterministically.

Errors and tracing

Onwinds returns structured errors and attaches request identifiers to help you debug failures deterministically.

Error shape

On failure, you’ll receive a machine-readable and (when available) a .

Request IDs

Responses include request identifiers (for example via / ) so incidents are debuggable without guesswork.

Loading…

curl https://api.onwinds.com/v1/chat/completions \ -H "Authorization: Bearer ow_…" \ -H "Content-Type: application/json" \ -H "x-onwinds-region-required: eu" \ -H "x-onwinds-retention-mode: zdr" \ -d '{"model":"gpt-5-mini","stream":true,"max_tokens":256,"messages":[{"role":"user","content":"Write a concise incident update."}]}'