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.

Python
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)
TypeScript
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
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."}]
  }'
JSON
// 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 429 starter_rate_limit_exceeded). Before your first confirmed top-up, only starter-eligible models such as qwen3.8-27b can be called on managed providers; models marked After top-up return 403 starter_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).

Your input

Please call Jonas Becker back on +49 30 901820.

Sent to the model

Please call [PERSON] back on [PHONE].

Turn on Shield per request
Python
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"},
)
TypeScript
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
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.

HeaderDirectionEffect
Authorization: Bearer px-...RequestDefault for the OpenAI SDK and curl (checked first).
x-api-key: px-...RequestDefault for the Anthropic SDK (checked second; selects the Anthropic format on /v1/files).
api-key: px-...RequestCompatible with Azure OpenAI clients (checked third).
X-Noirdoc-ShieldRequest & responseRequest: 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-MaskRequestCompatible 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-TagsRequestAttaches 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-ProviderResponseSlug 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-MaskedResponsetrue 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.

EndpointFormatDocumentation
POST /v1/chat/completionsOpenAIChat Completions
POST /v1/responsesOpenAIResponses
POST /v1/messages, POST /v1/messages/count_tokensAnthropicMessages
POST /v1/embeddingsOpenAIEmbeddings
POST /v1/rerankRerankRerank
POST /v1/audio/transcriptions, POST /v1/audio/speechOpenAIAudio
POST /v1/images/generationsOpenAIImages
/v1/files, /v1/skillsOpenAI, AnthropicFiles & Skills
POST /v1/shield/inspect, /v1/shield/policyNoirdocShield Inspect, Shield Policy
GET /v1/models, GET /v1/pricesOpenAI, Noirdoc (public)Models & pricing
/v1/tagsNoirdoc (Preview)Request tags