Chat & Responses.

Generates model responses in the format of the OpenAI Chat Completions and Responses APIs, inspects inputs with Noirdoc Shield and routes across European providers.

Chat Completions.

Accepts requests in the format of the OpenAI Chat Completions API (https://api.noirdoc.de/v1) and routes them across European providers.

POST https://api.noirdoc.de/v1/chat/completions

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 clause 4 deadlines."}],
    extra_headers={"X-Noirdoc-Shield": "on"},
)
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 clause 4 deadlines." }],
  },
  { headers: { "X-Noirdoc-Shield": "on" } },
);
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" \
  -H "X-Noirdoc-Shield: on" \
  -d '{
    "model": "qwen3.8-27b",
    "messages": [
      {"role": "user", "content": "Check clause 4 deadlines."}
    ]
  }'
JSON
// 200 OK · X-Noirdoc-Provider: ionos · X-Noirdoc-Shield: redacted=0
{
  "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": 18,
    "completion_tokens": 22,
    "total_tokens": 40,
  },
}

Browse public model IDs in the model catalogue or query GET /v1/models.

Standard fields such as messages, tools, tool_choice, response_format and stream work as documented by OpenAI. Only the following gateway rules differ:

AreaNoirdoc behaviour
modelPublic model ID of family chat from GET /v1/models (for example qwen3.8-27b). All OpenAI-format models and Google Vertex Gemini models run on this endpoint; managed claude-* models return 400 wrong_endpoint_for_model (use POST /v1/messages instead). Organisations still on starter credit can call starter-eligible models only; other managed models return 403 starter_model_not_allowed (Credit). The gateway rewrites upstream model names in model back to the ID you sent.
Provider & failoverX-Noirdoc-Provider names the executing provider, including on upstream errors. If a provider fails with 429, 5xx or a network error before the first byte, the gateway tries up to three providers of the same kind (managed providers and BYOK are never mixed; see Routing).
SSE keep-alive & usageWith "stream": true, if the provider has not sent response headers after 15 seconds, the gateway flushes HTTP 200 and sends a : ping comment line every 15 seconds (600 s total limit vs 120 s non-streaming). When 200 was flushed early, : provider=<slug> precedes the first data event instead of the HTTP header. For billing, the gateway sets stream_options.include_usage upstream and strips the extra usage chunk again unless you requested include_usage: true yourself (Streaming).
Noirdoc ShieldWhen active, redacts sensitive spans in messages in place with fixed placeholders ([PERSON], [IBAN], …) without adding system prompts or buffering stream chunks; block hits return 403 shield_violation (Inspected fields). Legacy reversible masking (<<PERSON_1>>) applies only to existing organisations during the transition until 2026-11-30 (Legacy masking).
Files, images & file_idimage_url, file and input_audio parts require Allow file attachments and images in requests under Models → Shield (otherwise 403 file_content_not_allowed). Shield inspects inline UTF-8 text files under 4 MiB directly; binary files, images and audio produce X-Noirdoc-Shield: partial; redacted=<n> or 422 shield_uninspectable_content under enforced (Files). On managed providers, any referenced file_id must belong to your organisation (otherwise 404 object_not_found).
Storage & subroutesOn managed providers, "store": true returns 403 stored_responses_disabled unless Allow Responses API storage at provider is enabled under Models → Shield. GET /v1/chat/completions, GET|DELETE /v1/chat/completions/{id} and GET /v1/chat/completions/{id}/messages work only with your own OpenAI-format provider key (BYOK; otherwise 403 endpoint_not_available_on_platform, or 502 provider_not_configured if none is configured). Stored completions retain one-way [PERSON] placeholders. Other paths under /v1/chat/completions/ return 404 unsupported_endpoint.
Stripped headersBefore forwarding, the gateway removes your API key, X-Noirdoc-Shield and X-Noirdoc-Mask.
Status Code Meaning
400 invalid_request_path The path contains a dot segment (. or ..), a %, a backslash or a control character.
400 model_required The request names no model (model in the body, or in the form field for /v1/audio/transcriptions).
400 wrong_endpoint_for_model The model belongs to a different endpoint family or API format than the endpoint called.
400 invalid_request_body The body is not a JSON object or not encoded in UTF-8.
400 invalid_request_error A parameter on /v1/shield/inspect or /v1/shield/policy is invalid (such as an empty input or one over 256 KB, more than 64 entries, an unknown rule or an invalid custom pattern), or the JSON body is nested too deeply for Shield extraction.
400 provider_rejected_request The provider itself rejected the request, for example because of an invalid parameter or a context that is too long. The response carries the provider's status code (400, 404, 409, 413, 422 or another 4xx status code except 401, 402, 403 and 429), and message contains the provider's message, shortened and sanitised, at most 500 characters. On routes with your own provider key (BYOK) the gateway also reports the provider's status codes 401, 402, 403 and 429 this way, because the key, credit and quota belong to the customer; with 429 it adds Retry-After.
400 invalid_request_tags The X-Noirdoc-Tags header or the tag name in the path under /v1/tags is empty, contains more than 5 tags or does not match the format ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$.
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).
402 key_budget_exhausted This key's budget is used up for the current period or does not cover the estimated cost of the request.
402 tag_budget_exhausted The budget of a tag named in X-Noirdoc-Tags is used up for the current period or does not cover the estimated cost of the request; message names the tag.
403 endpoint_not_available_on_platform The call would read data from the shared account of a provider managed by Noirdoc and is blocked there.
403 stored_responses_disabled The request would store input and response at the managed provider (store, previous_response_id or a sub-route for stored responses), and your organisation has not turned on storage at the provider.
403 reference_not_available_on_platform The body refers to objects at the provider (such as conversation, prompt.id or vector_store_ids) whose ownership the gateway cannot check for managed providers.
403 model_not_allowed_for_key The model is not one of this key's allowed models.
403 provider_not_allowed_for_tenant The organisation counts as bound by professional secrecy (§ 203 StGB); this excludes every provider that offers this model.
403 provider_not_allowed_for_key The key's restrictions (providers, data residency, CLOUD Act, § 203) exclude every provider of this model.
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).
403 file_content_not_allowed The request contains files, images or audio, and the organisation does not allow file content.
403 file_pii_blocked A file contains personal data, and the organisation's legacy file analysis (transition until 30.11.2026) is set to block or to detect_only under enforced.
403 model_not_billable The model has no complete price on record, so it cannot be used with credit.
403 request_tags_disabled The request sends X-Noirdoc-Tags or calls /v1/tags, but request tags (Preview) are not enabled for this organisation.
403 tag_not_found The named tag does not exist. On requests with X-Noirdoc-Tags, automatic tag creation is turned off (status code 403); on /v1/tags/{name}, the gateway answers with status code 404.
403 tag_disabled A tag named in X-Noirdoc-Tags is deactivated.
403 tag_limit_exceeded The organisation has reached the maximum of 1,000 request tags.
403 model_not_allowed_for_tag The model is not one of the allowed models of a tag named in X-Noirdoc-Tags.
403 provider_not_allowed_for_tag The restrictions of a tag named in X-Noirdoc-Tags (providers, data residency, CLOUD Act, § 203) exclude every provider of this model.
404 object_not_found The object (file, skill or stored response) does not exist or does not belong to your organisation.
404 model_not_available The model ID is not available to the organisation.
413 request_too_large The body exceeds the endpoint's size limit.
413 shield_input_too_large The text to inspect in this request exceeds the Shield service limit of 4 MiB of encoded text in a single call.
413 masking_input_too_large A single text segment in a legacy-masked request (transition until 30.11.2026) exceeds the detector's character limit.
422 shield_uninspectable_content The Shield policy is enforced, and the request carries content that Shield cannot inspect as text (binary_document such as PDF or Office, media_not_inspectable such as images, audio or video, file_reference by ID or URL, file_too_large at 4 MiB or above, file_not_decodable or unrecognised_content). The gateway did not forward the request.
422 shield_config_invalid The organisation's stored Shield configuration is invalid (for example enforced without any active protection filter, or a pattern that fails compilation); the gateway did not forward the request.
422 file_unprocessable A file could not be processed in legacy file analysis (transition until 30.11.2026): it is too large, unreadable or in a format without analysis. The gateway did not forward the request.
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.
429 resource_exhausted The provider reported capacity problems or exhausted credit (status code 429 or 402), even after failover across up to three providers. The response contains Retry-After with the wait in seconds.
500 internal_error An unexpected error occurred in the gateway.
500 detection_error Detecting personal data in legacy masking (transition until 30.11.2026) failed; the gateway did not forward the request.
502 provider_not_configured The organisation has no suitable provider set up for this request.
502 provider_misconfigured The configuration of the selected provider is invalid, for example a base URL that is not allowed.
502 provider_unreachable The gateway could not connect to the provider, or the connection dropped.
502 provider_error The provider answered with an error (status code 5xx except 503 and 529, or 401 and 403 on routes with a provider managed by Noirdoc) that the request did not cause. The gateway replaces the provider's message with a fixed text. On routes with your own provider key it reports 401 and 403 as provider_rejected_request.
502 stream_interrupted The provider's stream broke off or reported an error after the response had started. The error is in the stream itself, because status code 200 has already been sent by then. stream_interrupted carries no retry_after; only errors in the stream that correspond to an HTTP error with a wait carry it.
503 capacity_exhausted All providers of the model were at their capacity limit or paused after a 429, even after a wait of up to 10 seconds. The response contains Retry-After with the seconds until a provider is expected to be free again, at most 60, or 5 seconds if that is not known.
503 provider_overloaded The provider reported overload (status code 503 or 529), even after failover across up to three providers. The status code is 503 on OpenAI endpoints and 529 on /v1/messages and /v1/skills. The response contains Retry-After with the provider's value between 1 and 60 seconds, otherwise 5 seconds.
503 service_overloaded The gateway is temporarily at capacity. The response contains Retry-After with 5 seconds.
503 forwarding_pool_exhausted All of the gateway's connections to the providers are in use. This is a limit of the gateway, not of a provider. The response contains Retry-After with 5 seconds.
503 provider_auth_unavailable The gateway's credentials for the provider are currently unavailable. The response contains Retry-After with 5 seconds.
503 ownership_check_unavailable The gateway could not check just now whether the object belongs to your organisation and rejected the request. The response contains Retry-After with 5 seconds.
503 shield_unavailable The Noirdoc Shield inspection service is temporarily unreachable; the gateway never forwards a request that requires inspection uninspected (fail-closed). The response contains Retry-After with 5 seconds.
503 masking_unavailable The legacy masking detector (transition until 30.11.2026) is temporarily unreachable; the gateway did not forward the request. The response contains Retry-After with 10 seconds.
503 gateway_restarting The gateway was restarted (deployment) while the stream was still waiting for the provider's response. The error is in the running stream, because status code 200 has already been sent by then. The error object contains retry_after with 5 seconds.
504 provider_timeout The provider did not answer within the gateway's timeout. The response contains Retry-After with 10 seconds.

Responses.

Accepts requests in the format of the OpenAI Responses API and forwards them to OpenAI-format providers that offer this endpoint (endpoint_family: "chat" in GET /v1/models; if a provider rejects the format, you receive provider_rejected_request).

POST https://api.noirdoc.de/v1/responses

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.responses.create(
    model="qwen3.8-27b",
    instructions="Answer in at most three sentences.",
    input="Which deadlines does clause 8 set?",
    extra_headers={"X-Noirdoc-Shield": "on"},
)
print(res.output_text)
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.responses.create(
  {
    model: "qwen3.8-27b",
    instructions: "Answer in at most three sentences.",
    input: "Which deadlines does clause 8 set?",
  },
  { headers: { "X-Noirdoc-Shield": "on" } },
);
console.log(res.output_text);
curl
curl https://api.noirdoc.de/v1/responses \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Noirdoc-Shield: on" \
  -d '{
    "model": "qwen3.8-27b",
    "instructions": "Answer in at most three sentences.",
    "input": "Which deadlines does clause 8 set?"
  }'
JSON
// 200 OK · X-Noirdoc-Provider: azure
{
  "id": "resp_4f92c1",
  "object": "response",
  "model": "qwen3.8-27b",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Clause 8 sets a 14-day review deadline.",
        },
      ],
    },
  ],
  "usage": {
    "input_tokens": 23,
    "output_tokens": 15,
    "total_tokens": 38,
  },
}

Unlike OpenAI’s default, /v1/responses on Noirdoc is stateless by default and disables upstream storage:

AreaNoirdoc behaviour
Stateless default (store)On managed providers, the gateway sets store to false unless Allow Responses API storage at provider is enabled under Models → Shield (off by default for new organisations). While off, "store": true, previous_response_id and /v1/responses/{id} subroutes return 403 stored_responses_disabled. Pass prior turns directly in input; reasoning models remain usable without storage via include: ["reasoning.encrypted_content"]. Not enforced on BYOK routes.
Stored-object referencesOn managed providers, conversation, prompt.id, input[] items of type item_reference or carrying only an id, and tools[].vector_store_ids return 403 reference_not_available_on_platform. previous_response_id, file_id and containers must belong to your organisation (otherwise 404 object_not_found). Under Shield, previous_response_id needs no mapping store because [PERSON] placeholders are one-way. Not enforced on BYOK routes.
Noirdoc Shield & attachmentsInspects instructions and input in place ([PERSON], [IBAN], … or 403 shield_violation). input_image and input_file follow the same portal toggle and 4 MiB UTF-8 inspection rules as Chat Completions (Files).
SubroutesPOST /v1/responses/input_tokens counts input tokens for model, skips Shield and is billed at €0 (still returns 402 on managed providers when organisation credit or key budget is exhausted). POST /v1/responses/compact requires model, runs Shield when active and is billed by tokens. GET|DELETE /v1/responses/{id}, POST /v1/responses/{id}/cancel and GET /v1/responses/{id}/input_items carry no model and route to your organisation’s oldest active OpenAI-format provider (BYOK first; on managed providers only when storage is enabled and the ID belongs to your organisation, otherwise 404 object_not_found). Other paths under /v1/responses/ return 404 unsupported_endpoint.
Streaming & starter credit15-second : ping keep-alives, : provider=<slug> and the starter_model_not_allowed starter-credit check match /v1/chat/completions. If a stream fails mid-flight, the gateway emits an error event followed by data: [DONE] — check event.type == "error" in your OpenAI Python SDK loop (Streaming).
Status Code Meaning
400 invalid_request_path The path contains a dot segment (. or ..), a %, a backslash or a control character.
400 model_required The request names no model (model in the body, or in the form field for /v1/audio/transcriptions).
400 wrong_endpoint_for_model The model belongs to a different endpoint family or API format than the endpoint called.
400 invalid_request_body The body is not a JSON object or not encoded in UTF-8.
400 invalid_request_error A parameter on /v1/shield/inspect or /v1/shield/policy is invalid (such as an empty input or one over 256 KB, more than 64 entries, an unknown rule or an invalid custom pattern), or the JSON body is nested too deeply for Shield extraction.
400 provider_rejected_request The provider itself rejected the request, for example because of an invalid parameter or a context that is too long. The response carries the provider's status code (400, 404, 409, 413, 422 or another 4xx status code except 401, 402, 403 and 429), and message contains the provider's message, shortened and sanitised, at most 500 characters. On routes with your own provider key (BYOK) the gateway also reports the provider's status codes 401, 402, 403 and 429 this way, because the key, credit and quota belong to the customer; with 429 it adds Retry-After.
400 invalid_request_tags The X-Noirdoc-Tags header or the tag name in the path under /v1/tags is empty, contains more than 5 tags or does not match the format ^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$.
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).
402 key_budget_exhausted This key's budget is used up for the current period or does not cover the estimated cost of the request.
402 tag_budget_exhausted The budget of a tag named in X-Noirdoc-Tags is used up for the current period or does not cover the estimated cost of the request; message names the tag.
403 endpoint_not_available_on_platform The call would read data from the shared account of a provider managed by Noirdoc and is blocked there.
403 stored_responses_disabled The request would store input and response at the managed provider (store, previous_response_id or a sub-route for stored responses), and your organisation has not turned on storage at the provider.
403 reference_not_available_on_platform The body refers to objects at the provider (such as conversation, prompt.id or vector_store_ids) whose ownership the gateway cannot check for managed providers.
403 model_not_allowed_for_key The model is not one of this key's allowed models.
403 provider_not_allowed_for_tenant The organisation counts as bound by professional secrecy (§ 203 StGB); this excludes every provider that offers this model.
403 provider_not_allowed_for_key The key's restrictions (providers, data residency, CLOUD Act, § 203) exclude every provider of this model.
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).
403 file_content_not_allowed The request contains files, images or audio, and the organisation does not allow file content.
403 file_pii_blocked A file contains personal data, and the organisation's legacy file analysis (transition until 30.11.2026) is set to block or to detect_only under enforced.
403 model_not_billable The model has no complete price on record, so it cannot be used with credit.
403 request_tags_disabled The request sends X-Noirdoc-Tags or calls /v1/tags, but request tags (Preview) are not enabled for this organisation.
403 tag_not_found The named tag does not exist. On requests with X-Noirdoc-Tags, automatic tag creation is turned off (status code 403); on /v1/tags/{name}, the gateway answers with status code 404.
403 tag_disabled A tag named in X-Noirdoc-Tags is deactivated.
403 tag_limit_exceeded The organisation has reached the maximum of 1,000 request tags.
403 model_not_allowed_for_tag The model is not one of the allowed models of a tag named in X-Noirdoc-Tags.
403 provider_not_allowed_for_tag The restrictions of a tag named in X-Noirdoc-Tags (providers, data residency, CLOUD Act, § 203) exclude every provider of this model.
404 object_not_found The object (file, skill or stored response) does not exist or does not belong to your organisation.
404 model_not_available The model ID is not available to the organisation.
413 request_too_large The body exceeds the endpoint's size limit.
413 shield_input_too_large The text to inspect in this request exceeds the Shield service limit of 4 MiB of encoded text in a single call.
413 masking_input_too_large A single text segment in a legacy-masked request (transition until 30.11.2026) exceeds the detector's character limit.
422 shield_uninspectable_content The Shield policy is enforced, and the request carries content that Shield cannot inspect as text (binary_document such as PDF or Office, media_not_inspectable such as images, audio or video, file_reference by ID or URL, file_too_large at 4 MiB or above, file_not_decodable or unrecognised_content). The gateway did not forward the request.
422 shield_config_invalid The organisation's stored Shield configuration is invalid (for example enforced without any active protection filter, or a pattern that fails compilation); the gateway did not forward the request.
422 file_unprocessable A file could not be processed in legacy file analysis (transition until 30.11.2026): it is too large, unreadable or in a format without analysis. The gateway did not forward the request.
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.
429 resource_exhausted The provider reported capacity problems or exhausted credit (status code 429 or 402), even after failover across up to three providers. The response contains Retry-After with the wait in seconds.
500 internal_error An unexpected error occurred in the gateway.
500 detection_error Detecting personal data in legacy masking (transition until 30.11.2026) failed; the gateway did not forward the request.
502 provider_not_configured The organisation has no suitable provider set up for this request.
502 provider_misconfigured The configuration of the selected provider is invalid, for example a base URL that is not allowed.
502 provider_unreachable The gateway could not connect to the provider, or the connection dropped.
502 provider_error The provider answered with an error (status code 5xx except 503 and 529, or 401 and 403 on routes with a provider managed by Noirdoc) that the request did not cause. The gateway replaces the provider's message with a fixed text. On routes with your own provider key it reports 401 and 403 as provider_rejected_request.
502 stream_interrupted The provider's stream broke off or reported an error after the response had started. The error is in the stream itself, because status code 200 has already been sent by then. stream_interrupted carries no retry_after; only errors in the stream that correspond to an HTTP error with a wait carry it.
503 capacity_exhausted All providers of the model were at their capacity limit or paused after a 429, even after a wait of up to 10 seconds. The response contains Retry-After with the seconds until a provider is expected to be free again, at most 60, or 5 seconds if that is not known.
503 provider_overloaded The provider reported overload (status code 503 or 529), even after failover across up to three providers. The status code is 503 on OpenAI endpoints and 529 on /v1/messages and /v1/skills. The response contains Retry-After with the provider's value between 1 and 60 seconds, otherwise 5 seconds.
503 service_overloaded The gateway is temporarily at capacity. The response contains Retry-After with 5 seconds.
503 forwarding_pool_exhausted All of the gateway's connections to the providers are in use. This is a limit of the gateway, not of a provider. The response contains Retry-After with 5 seconds.
503 provider_auth_unavailable The gateway's credentials for the provider are currently unavailable. The response contains Retry-After with 5 seconds.
503 ownership_check_unavailable The gateway could not check just now whether the object belongs to your organisation and rejected the request. The response contains Retry-After with 5 seconds.
503 shield_unavailable The Noirdoc Shield inspection service is temporarily unreachable; the gateway never forwards a request that requires inspection uninspected (fail-closed). The response contains Retry-After with 5 seconds.
503 masking_unavailable The legacy masking detector (transition until 30.11.2026) is temporarily unreachable; the gateway did not forward the request. The response contains Retry-After with 10 seconds.
503 gateway_restarting The gateway was restarted (deployment) while the stream was still waiting for the provider's response. The error is in the running stream, because status code 200 has already been sent by then. The error object contains retry_after with 5 seconds.
504 provider_timeout The provider did not answer within the gateway's timeout. The response contains Retry-After with 10 seconds.