Quickstart.
A base URL and an API key from the portal are all you need: existing OpenAI and Anthropic clients run unchanged through the Noirdoc gateway.
Send your first request.
Create a px- key in the Noirdoc portal under Models → API keys and store it in NOIRDOC_API_KEY (self-registration requires an EU or EFTA connection without a VPN, Private Relay, proxy or data centre IP; initial setup asks about § 203 German Criminal Code (StGB)). Point base_url at https://api.noirdoc.de/v1 and pass a model ID such as qwen3.8-27b.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.noirdoc.de/v1",
api_key=os.environ["NOIRDOC_API_KEY"],
)
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[{"role": "user", "content": "Check § 4 for deadlines."}],
)
print(res.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.noirdoc.de/v1",
apiKey: process.env.NOIRDOC_API_KEY,
});
const res = await client.chat.completions.create({
model: "qwen3.8-27b",
messages: [{ role: "user", content: "Check § 4 for deadlines." }],
});
console.log(res.choices[0].message.content);curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3.8-27b",
"messages": [{"role": "user", "content": "Check § 4 for deadlines."}]
}'// 200 OK · Header: X-Noirdoc-Provider: ionos
{
"id": "chatcmpl-8e21a9",
"object": "chat.completion",
"model": "qwen3.8-27b",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "Clause 4 sets a three-month notice period.",
},
"finish_reason": "stop",
},
],
"usage": {
"prompt_tokens": 14,
"completion_tokens": 14,
"total_tokens": 28,
},
}The response names the answering provider in X-Noirdoc-Provider. Browse all model IDs in the model catalogue or query GET /v1/models.
Starter credit: Your first organisation receives a starter credit capped at 5 requests per minute and 25 per day UTC (exceeding this returns
429starter_rate_limit_exceeded). Before your first confirmed top-up, only starter-eligible models such asqwen3.8-27bcan be called on managed providers; models marked After top-up return403starter_model_not_allowed. Your first top-up and your own provider keys (BYOK) lift both restrictions immediately; see Credit & billing.
Inspect inputs with Shield.
With X-Noirdoc-Shield: on, Noirdoc Shield inspects inbound text statelessly before forwarding to the provider so the model receives sanitised input. By default, personal data is redacted with markers such as [PERSON] or [PHONE], while secrets and prompt injections are blocked with status 403 (shield_violation).
Please call Jonas Becker back on +49 30 901820.
Please call [PERSON] back on [PHONE].
res = client.chat.completions.create(
model="qwen3.8-27b",
messages=[
{
"role": "user",
"content": "Please call Jonas Becker back on +49 30 901820.",
}
],
extra_headers={"X-Noirdoc-Shield": "on"},
)const res = await client.chat.completions.create(
{
model: "qwen3.8-27b",
messages: [
{
role: "user",
content: "Please call Jonas Becker back on +49 30 901820.",
},
],
},
{ headers: { "X-Noirdoc-Shield": "on" } },
);curl https://api.noirdoc.de/v1/chat/completions \
-H "Authorization: Bearer $NOIRDOC_API_KEY" \
-H "Content-Type: application/json" \
-H "X-Noirdoc-Shield: on" \
-d '{
"model": "qwen3.8-27b",
"messages": [{
"role": "user",
"content": "Please call Jonas Becker back on +49 30 901820."
}]
}'New organisations start with default_off. Configure permanent rules per key, request tag or organisation under Models → Shield; see Policy and precedence.
Authentication and headers.
Every request (except GET /v1/prices) requires an active px- key; otherwise the gateway returns status 401 (invalid_api_key) with message "Missing or invalid API key" (no header starting with px-) or "Invalid or inactive API key" (unknown/disabled key or inactive organisation). The gateway checks the three key headers in table order and strips your key along with X-Noirdoc-*, User-Agent, cookies and custom X-* headers before forwarding to the provider.
| Header | Direction | Effect |
|---|---|---|
Authorization: Bearer px-... | Request | Default for the OpenAI SDK and curl (checked first). |
x-api-key: px-... | Request | Default for the Anthropic SDK (checked second; selects the Anthropic format on /v1/files). |
api-key: px-... | Request | Compatible with Azure OpenAI clients (checked third). |
X-Noirdoc-Shield | Request & response | Request: on or off (true/false/1/0) overrides default_on/default_off below enforced, key and tag. Response: redacted=<n> on full inspection, partial; redacted=<n> when non-enforced requests include uninspectable binary/reference attachments, otherwise absent. |
X-Noirdoc-Mask | Request | Compatible alias for X-Noirdoc-Shield. On pre-existing organisations still using legacy masking until 2026-11-30, controls reversible masking (responses carry Deprecation: true and Sunset: Mon, 30 Nov 2026 23:59:59 GMT). |
X-Noirdoc-Tags | Request | Attaches 1 to 5 comma-separated tags (^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$) for budgets, model allowlists and Shield (403 request_tags_disabled unless enabled; see Request tags). |
X-Noirdoc-Provider | Response | Slug of the provider that answered or failed last (omitted on /v1/files, /v1/skills, gateway-only routes, pre-routing errors and streams flushed after 15 s in favour of : provider=<slug>). |
X-Noirdoc-Masked | Response | true on full Shield inspection (redacted=<n>) or active legacy masking; false on partial, uninspected requests and errors before routing. |
The gateway forwards only Content-Type, Accept, anthropic-version (fixed to 2023-06-01 on Anthropic, or moved with anthropic-beta into the body on Google Vertex AI), anthropic-beta and OpenAI-Beta; OpenAI-Organization, OpenAI-Project and Idempotency-Key are kept only with your own provider keys (BYOK). On all model endpoints, model alone selects the provider rather than the auth header (/v1/skills always goes to Anthropic, and /v1/files follows x-api-key vs Bearer/api-key or X-Provider; see Files & Skills). Keep px- keys on servers only and cap spend per application via Budgets per key.
| Status | Code | Meaning |
|---|---|---|
| 400 | model_required | The request names no model (model in the body, or in the form field for /v1/audio/transcriptions). |
| 401 | invalid_api_key | The key is missing, invalid or deactivated, or the organisation is not active. |
| 402 | insufficient_credit | The organisation's credit is used up or lower than the estimated maximum cost of the request (including Noirdoc Shield, also on BYOK routes when Shield is active). |
| 403 | model_not_allowed_for_key | The model is not one of this key's allowed models. |
| 403 | starter_model_not_allowed | The organisation is still using only its starter credit, and the model or its managed provider is not included in starter credit. |
| 403 | shield_violation | Noirdoc Shield blocked the request before forwarding to the provider because an active protection filter configured with block matched; message names the triggered rule (secrets, pii, ner, injection or custom). |
| 404 | model_not_available | The model ID is not available to the organisation. |
| 429 | starter_rate_limit_exceeded | The organisation is still using only its starter credit and has reached the limit of 5 requests per minute or 25 requests per day (UTC) for managed providers. The response contains Retry-After with the wait in seconds. |
Endpoints.
All endpoints sit under https://api.noirdoc.de/v1 (the Anthropic SDK uses https://api.noirdoc.de as its base URL and appends /v1 itself). Each reference page documents Noirdoc-specific rules and limits relative to the upstream API.
| Endpoint | Format | Documentation |
|---|---|---|
POST /v1/chat/completions | OpenAI | Chat Completions |
POST /v1/responses | OpenAI | Responses |
POST /v1/messages, POST /v1/messages/count_tokens | Anthropic | Messages |
POST /v1/embeddings | OpenAI | Embeddings |
POST /v1/rerank | Rerank | Rerank |
POST /v1/audio/transcriptions, POST /v1/audio/speech | OpenAI | Audio |
POST /v1/images/generations | OpenAI | Images |
/v1/files, /v1/skills | OpenAI, Anthropic | Files & Skills |
POST /v1/shield/inspect, /v1/shield/policy | Noirdoc | Shield Inspect, Shield Policy |
GET /v1/models, GET /v1/prices | OpenAI, Noirdoc (public) | Models & pricing |
/v1/tags | Noirdoc (Preview) | Request tags |