Embeddings & Rerank.

Generates vector embeddings and re-orders search candidates by relevance, both with stateless Noirdoc Shield input inspection.

Embeddings.

Accepts requests in the format of the OpenAI Embeddings API (endpoint_family: "embeddings" in GET /v1/models) and passes optional parameters such as encoding_format and dimensions through to the provider.

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

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.embeddings.create(
    model="BAAI/bge-m3",
    input=[
        "The notice period is three months.",
        "The contract ends at the end of the quarter.",
    ],
    extra_headers={"X-Noirdoc-Shield": "on"},
)
print(len(res.data[0].embedding))
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.embeddings.create(
  {
    model: "BAAI/bge-m3",
    input: [
      "The notice period is three months.",
      "The contract ends at the end of the quarter.",
      "Renewal extends the term by twelve months.",
    ],
  },
  { headers: { "X-Noirdoc-Shield": "on" } },
);
console.log(res.data[0]?.embedding.length);
curl
curl https://api.noirdoc.de/v1/embeddings \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Noirdoc-Shield: on" \
  -d '{
    "model": "BAAI/bge-m3",
    "input": [
      "The notice period is three months.",
      "The contract ends at the end of the quarter."
    ]
  }'
JSON
// 200 OK · X-Noirdoc-Provider: ionos · X-Noirdoc-Shield: redacted=0
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0184, -0.0291, 0.0412],
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [-0.0093, 0.0318, 0.0127],
    },
  ],
  "model": "BAAI/bge-m3",
  "usage": {
    "prompt_tokens": 17,
    "total_tokens": 17,
  },
}
AreaNoirdoc behaviour
modelPublic model ID of family embeddings from GET /v1/models (other families return 400 wrong_endpoint_for_model). Organisations still on starter credit can call starter-eligible models only; other managed models return 403 starter_model_not_allowed (Credit). The response model field is rewritten back to the ID you sent.
Noirdoc ShieldWhen active (default_on, enforced, shield_mode: on on key or tag, or X-Noirdoc-Shield: on), Shield inspects string inputs, string arrays, multimodal text fields and integer token arrays (decoded via tiktoken, redacted and re-encoded into token IDs) before forwarding. Responses carry X-Noirdoc-Shield: redacted=<n> and X-Noirdoc-Masked: true; block hits return 403 shield_violation (Inspected fields). Existing organisations on legacy masking until 2026-11-30 receive 403 masking_not_supported_for_endpoint under enforced or X-Noirdoc-Mask: on unless X-Noirdoc-Shield: on is set.
StreamingNot supported. "stream": true returns 400 streaming_not_supported_for_endpoint.
BillingInput tokens from upstream usage (estimated from the request body if unreported), plus Noirdoc Shield when active (Shield).
Subroutes & headersNo subroutes (other paths under /v1/embeddings/ return 404 unsupported_endpoint). X-Noirdoc-Provider names the provider; your API key, X-Noirdoc-Shield and X-Noirdoc-Mask are stripped before forwarding.
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 streaming_not_supported_for_endpoint The request asks for streaming, but the endpoint does not support it.
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 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 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 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.
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.
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.
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.
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 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.
504 provider_timeout The provider did not answer within the gateway's timeout. The response contains Retry-After with 10 seconds.

Rerank.

Scores and orders candidate documents by relevance to a search query (endpoint_family: "rerank" in GET /v1/models) and returns a normalised response structure across providers.

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

Python
import os
import httpx

res = httpx.post(
    "https://api.noirdoc.de/v1/rerank",
    headers={
        "Authorization": f"Bearer {os.environ['NOIRDOC_API_KEY']}",
        "X-Noirdoc-Shield": "on",
    },
    json={
        "model": "Qwen/Qwen3-VL-Reranker-8B",
        "query": "What is the notice period?",
        "documents": [
            "The contract ends at the end of the quarter.",
            "The notice period is three months.",
            "Rent is due on the first day of each month.",
        ],
        "top_n": 2,
        "return_documents": True,
    },
)
res.raise_for_status()
print(res.json()["results"][0])
TypeScript
const res = await fetch("https://api.noirdoc.de/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NOIRDOC_API_KEY}`,
    "Content-Type": "application/json",
    "X-Noirdoc-Shield": "on",
  },
  body: JSON.stringify({
    model: "Qwen/Qwen3-VL-Reranker-8B",
    query: "What is the notice period?",
    documents: [
      "The contract ends at the end of the quarter.",
      "The notice period is three months.",
      "Rent is due on the first day of each month.",
    ],
    top_n: 2,
    return_documents: true,
  }),
});
const data = await res.json();
console.log(data.results[0]);
curl
curl https://api.noirdoc.de/v1/rerank \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Noirdoc-Shield: on" \
  -d '{
    "model": "Qwen/Qwen3-VL-Reranker-8B",
    "query": "What is the notice period?",
    "documents": [
      "The contract ends at the end of the quarter.",
      "The notice period is three months.",
      "Rent is due on the first day of each month."
    ],
    "top_n": 2,
    "return_documents": true
  }'
JSON
// 200 OK · X-Noirdoc-Provider: weber · X-Noirdoc-Shield: redacted=0
{
  "results": [
    {
      "index": 1,
      "relevance_score": 0.94,
      "document": {
        "text": "The notice period is three months.",
      },
    },
    {
      "index": 0,
      "relevance_score": 0.31,
      "document": {
        "text": "The contract ends at the end of the quarter.",
      },
    },
  ],
  "usage": {
    "total_tokens": 44,
  },
}
Field / areaNoirdoc rule
model (required)Public model ID of family rerank from GET /v1/models (other families return 400 wrong_endpoint_for_model; non-starter managed models on starter credit return 403 starter_model_not_allowed).
query & documents (required)query must be a non-empty plain string; documents must be an array of 1 to 1,000 plain strings. Images or content arrays are rejected beforehand with 400 invalid_rerank_request.
instruction, top_n, return_documentsAll optional: instruction task string, top_n integer >= 1 limiting returned candidates (< 1 returns 400 invalid_rerank_request), and return_documents: true to include document.text in each result.
Normalised responseresults[] carries index (0-based index into documents), relevance_score (model-specific scale — compare only within one response) and document normalised as {"text": "…"} (holding the redacted text when Shield redacted documents), plus usage.
Noirdoc ShieldInspects query, instruction and documents[] before forwarding (X-Noirdoc-Shield: redacted=<n>, X-Noirdoc-Masked: true, or 403 shield_violation on block). Under legacy masking until 2026-11-30, enforced and X-Noirdoc-Mask: on without X-Noirdoc-Shield: on return 403 masking_not_supported_for_endpoint.
Streaming, methods & billingPOST only (405 method_not_allowed otherwise); "stream": true returns 400 streaming_not_supported_for_endpoint; subpaths under /v1/rerank/ return 404 unsupported_endpoint. Billed per 1M input tokens (per1MTokens, estimated when usage is absent) or flat per request (perRequest via price_input), plus Shield when active (Models & pricing).

Prompt tags for Qwen3-Reranker

Qwen3-Reranker models achieve their best accuracy when query carries <Instruct>: and <Query>: tags and each entry in documents starts with <Document>:. The gateway forwards your strings unchanged without adding tags automatically:

Prompt tags for Qwen3-Reranker
instruct = "Find contract clauses that answer the question."
question = "What is the notice period?"
docs = [
    "The contract ends at the end of the quarter.",
    "The notice period is three months.",
]

payload = {
    "model": "Qwen/Qwen3-VL-Reranker-8B",
    "query": f"<Instruct>: {instruct}\n<Query>: {question}",
    "documents": [f"<Document>: {d}" for d in docs],
}
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 streaming_not_supported_for_endpoint The request asks for streaming, but the endpoint does not support it.
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_rerank_request query is not a non-empty string, documents is not a list of 1 to 1,000 strings or top_n is not an integer of at least 1; message names the field.
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 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 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 model_not_available The model ID is not available to the organisation.
405 method_not_allowed The endpoint accepts only POST.
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.
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.
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.
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.
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 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.
504 provider_timeout The provider did not answer within the gateway's timeout. The response contains Retry-After with 10 seconds.