Onwinds API reference

Canonical API specification rendered from the OpenAPI definition.

Base URLs

https://api.onwinds.comhttp://localhost:3000

Authentication: Use Authorization: Bearer <token>. For server-to-server access, create a tenant API key in the dashboard (prefix ow_...) and send it as the bearer token. Tenant context is derived from the bearer token or session (caller-supplied tenant_id is ignored).

Endpoints

Back to overview

POST/v1/chat/completions

Chat completions (OpenAI-compatible, streaming-first)

OpenAI-compatible chat completions endpoint. MVP requires stream=true and returns SSE.

Request

Content types: application/json

Auth: Bearer

Headers

x-onwinds-region-requiredoptional
Optional. Require an EU-compliant route for this request. If no compliant route exists, the request does not run (fail-closed).
eu
x-onwinds-retention-modeoptional
Optional. Request a stricter retention posture for Onwinds logging paths for this request while preserving billing metadata.
zdr

Responses

Status codes: 200, 400, 401, 402, 409

Debugging: errors & tracing

Example (OpenAI SDK)

Streaming chat completions with Onwinds enforcing routing, governance, and spend.

Chat (streaming)

Drop-in OpenAI SDK usage; base URL swap only.

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: "onwinds/auto",

stream: true,

max_tokens: 800,

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

});

POST/v1/embeddings

Embeddings (OpenAI-compatible, tenant scoped)

Request

Content types: application/json

Auth: Bearer

Headers

x-onwinds-region-requiredoptional
Optional. Require an EU-compliant route for this request. If no compliant route exists, the request does not run (fail-closed).
eu
x-onwinds-retention-modeoptional
Optional. Request a stricter retention posture for Onwinds logging paths for this request while preserving billing metadata.
zdr

Responses

Status codes: 200, 400, 401

Debugging: errors & tracing

Example (OpenAI SDK)

Embeddings request via the OpenAI-compatible endpoint.

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: "onwinds/embeddings",

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

});

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

GET/v1/models

List models (logical, tenant-governed)

Request

Content types: None

Auth: Bearer

Responses

Status codes: 200

Debugging: errors & tracing

Example (OpenAI SDK)

List the logical models your tenant can use.

List models

OpenAI-compatible models listing through Onwinds.

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));

Loading the kernel surface…