Request tags (Preview)

Request tags let you attribute individual requests to a matter, cost centre, team or client of your application through the X-Noirdoc-Tags header – without issuing a separate API key for every matter. Each tag keeps its own usage counters and can carry its own euro budget, its own model and provider restrictions and its own Noirdoc Shield mode (shield_mode).

1. Set up the default tag template or create tags in the portal

   Once enabled, admins of your organisation manage tags under Models → Tags.

   In the Default tag template section, you define how the gateway handles unknown tag names in the X-Noirdoc-Tags header:

   • Automatically create unknown tags on first use (default: turned on): when your application sends a new tag, the gateway creates it automatically on the first forwarded request and copies the budget, the model and provider restrictions and shield_mode from the template.
   • Automatic creation turned off: the gateway rejects unknown tags in the X-Noirdoc-Tags header with status code 403 and error code tag_not_found. Create valid tags in advance through New tag or with POST /v1/tags.

   Tag names follow these rules:

   • Format: 1 to 64 characters from a-z, A-Z, 0-9 and _, ., : and -, starting with a letter or digit (^[a-zA-Z0-9][a-zA-Z0-9_.:-]{0,63}$).
   • Reserved name: _default is reserved for the template endpoint /v1/tags/_default and cannot be used as a tag name.
   • Limit: each organisation can create up to 1,000 request tags (tag_limit_exceeded).

   Result: your organisation has a default tag template or pre-created tags.

2. Set the budget, restrictions and Noirdoc Shield per tag

   For the Default tag template and for each individual tag, you can set the same guardrails as for an API key (see Budgets per key, Restrict models & providers and Set up Noirdoc Shield):

   • Spending limit (€) and Reset: Never, Daily (00:00 UTC), Weekly (Mondays at 00:00 UTC) or Monthly (on the 1st of the month at 00:00 UTC). Empty means no separate limit for this tag.
   • Noirdoc Shield (shield_mode): Inherit ("inherit", defers to headers and the organisation default), On ("on", turns Shield on for requests carrying this tag) or Off ("off", turns Shield off unless the organisation policy is enforced or the API key or another attached tag turns Shield on).
   • Allowed models: All models or Selected models only.
   • Provider restrictions: Data residency, Only providers without CLOUD Act exposure, Only §203-covered providers and a selection of allowed Providers.

   Result: under Models → Tags, the table shows the status (Active or Inactive), usage in the current period, total spend and the time of last use for each tag.

3. Send X-Noirdoc-Tags with requests

   Pass 1 to 5 comma-separated tag names in the X-Noirdoc-Tags header. If the same tag appears more than once on a request, the gateway deduplicates it. Before forwarding the request to the provider, the gateway strips the header.

   GET /v1/models also evaluates X-Noirdoc-Tags and returns only models permitted for both the key and all named tags. Likewise, POST /v1/shield/inspect accepts X-Noirdoc-Tags for cost attribution and tag budget enforcement.

   Result: the gateway checks the budget and restrictions of the named tags and books the request to each tag after the response.

   curl Python TypeScript

   Shell

   curl https://api.noirdoc.de/v1/chat/completions \
     -H "Authorization: Bearer $NOIRDOC_API_KEY" \
     -H "X-Noirdoc-Tags: mandat-2026-042,team-arbeitsrecht" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "qwen3.8-27b",
       "max_tokens": 500,
       "messages": [{"role": "user", "content": "Hello"}]
     }'

   Python

   import os
   from openai import OpenAI
   
   client = OpenAI(
       base_url="https://api.noirdoc.de/v1",
       api_key=os.environ["NOIRDOC_API_KEY"],
   )
   
   response = client.chat.completions.create(
       model="qwen3.8-27b",
       max_tokens=500,
       messages=[{"role": "user", "content": "Hello"}],
       extra_headers={
           "X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht",
       },
   )

   TypeScript

   import OpenAI from "openai";
   
   const client = new OpenAI({
     baseURL: "https://api.noirdoc.de/v1",
     apiKey: process.env.NOIRDOC_API_KEY,
   });
   
   const response = await client.chat.completions.create(
     {
       model: "qwen3.8-27b",
       max_tokens: 500,
       messages: [{ role: "user", content: "Hello" }],
     },
     {
       headers: {
         "X-Noirdoc-Tags": "mandat-2026-042,team-arbeitsrecht",
       },
     },
   );

Multiple tags and interaction with the key

When you send one or more tags in X-Noirdoc-Tags, the gateway combines the rules of the organisation, the API key and all named tags:

• Allowed models and providers (intersection): a model and a provider are eligible only if they are permitted for the organisation (§ 203 StGB), for the calling API key and for every attached tag. If any tag excludes the model or all of its providers, the gateway answers with 403 model_not_allowed_for_tag or provider_not_allowed_for_tag.
• Noirdoc Shield (shield_mode and precedence): whether Shield inspects a request follows the precedence order organisation enforced > API key shield_mode ("on" / "off") > request tag shield_mode > X-Noirdoc-Shield header > organisation default (default_on / default_off), see Policy and precedence. When multiple tags are sent in X-Noirdoc-Tags, any "on" among attached tags wins over "off"; "inherit" defers to the next level.
• Order of budget checks: before forwarding the request, the gateway checks the organisation’s credit first (insufficient_credit), then the API key’s budget (key_budget_exhausted) and then the budgets of the tags in the order listed in X-Noirdoc-Tags. If a tag’s budget is used up or smaller than the request’s cost estimate, the gateway answers with 402 tag_budget_exhausted; message names the affected tag.
• Full cost booked per tag: after the response or inspection, the gateway books the full cost of the request – priced models managed by Noirdoc as well as the Noirdoc Shield inspection fee (€0.40 per 1M inspected input tokens, including on POST /v1/shield/inspect and on BYOK routes when Shield is active) – both to the API key and to every tag named in X-Noirdoc-Tags. This lets you track independent dimensions – such as a matter budget (mandat-2026-042) and a department budget (team-arbeitsrecht) – on the same request. As with key budgets, requests through your own providers (BYOK) without active Shield count as €0.

Managing tags via the API (/v1/tags)

Alongside the interface under Models → Tags, you can manage tags and the default tag template through the /v1/tags endpoint – for example automatically when opening a new file in your practice management software.

API key permission

By default, an API key is not allowed to call /v1/tags (403 insufficient_key_permissions). Under Models → API keys, turn on Allow tag management (/v1/tags) when creating or editing the key.

Endpoints at a glance

curl -X PUT https://api.noirdoc.de/v1/tags/mandat-2026-042 \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Matter 2026/042 – Employment law",
    "budget_limit_eur": 25.0,
    "budget_reset": "monthly",
    "shield_mode": "on",
    "allowed_residencies": ["DE", "EU"],
    "require_no_cloud_act": true,
    "require_section203": true
  }'

Errors