Proxy Endpoints

The /v1/ proxy routes, supported paths, and utility endpoints.

How the proxy works

Noirdoc exposes a catch-all route at ANY /v1/{path} that accepts any HTTP method. Incoming requests are pseudonymized, forwarded to the configured upstream LLM provider, and the response is restored before being returned to your application. The proxy is transparent — your client code does not need to know that Noirdoc sits in between.

Authentication: All proxy endpoints require a proxy API key (px-*). See API Overview.

Supported paths

PathMethodDescription
/v1/chat/completionsPOSTOpenAI-compatible chat completions
/v1/responsesPOSTOpenAI Responses API
/v1/messagesPOSTAnthropic Messages API
/v1/modelsGETList available models from the provider
/v1/filesPOSTUpload a file
/v1/filesGETList uploaded files
/v1/files/{file_id}GETRetrieve file metadata
/v1/files/{file_id}/contentGETRetrieve file content
/v1/pseudonymizePOSTStandalone PII pseudonymization
/v1/detectPOSTStandalone PII detection

Requests to unsupported paths return a 404 with error code unsupported_endpoint.

Chat completions

The most common endpoint. Send a chat conversation and receive a model-generated response.

curl -X POST https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Summarize the contract for Max Mustermann, IBAN DE89370400440532013000."}
    ]
  }'

Noirdoc pseudonymizes the user message before it reaches the provider. The model sees <<PERSON_1>> and <<IBAN_1>> instead of the real values. The response is de-pseudonymized before being returned to you.

Streaming is supported — pass "stream": true. See Streaming for details.

Anthropic Messages

Send messages using the Anthropic API format. Use the x-api-key header:

curl -X POST https://api.noirdoc.de/v1/messages \
  -H "x-api-key: px-your-key" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Summarize the patient record for Maria Huber."}
    ]
  }'

Responses API

Proxies requests to the OpenAI Responses API:

curl -X POST https://api.noirdoc.de/v1/responses \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "input": "Explain the claim filed by Dr. Weber on 2024-03-15."
  }'

Session continuity is preserved across chained responses via previous_response_id.

Azure OpenAI

Use the api-key header and include the api-version query parameter:

curl "https://api.noirdoc.de/v1/chat/completions?api-version=2025-04-01-preview" \
  -H "api-key: px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [
      {"role": "user", "content": "Summarize the contract for Anna Schmidt, phone +49 170 1234567."}
    ]
  }'

Models

List available models from the configured provider:

curl https://api.noirdoc.de/v1/models \
  -H "Authorization: Bearer px-your-key"

Files

Upload and manage files. Noirdoc scans uploaded files for PII according to the tenant’s file handling settings.

curl -X POST https://api.noirdoc.de/v1/files \
  -H "Authorization: Bearer px-your-key" \
  -F "file=@document.pdf" \
  -F "purpose=assistants"

Utility endpoints

These endpoints let you use Noirdoc’s PII detection and pseudonymization independently, without forwarding to an LLM provider.

POST /v1/pseudonymize

Pseudonymize text and return the result with entity details and the mapping table.

curl -X POST https://api.noirdoc.de/v1/pseudonymize \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Max Mustermann, born 15.03.1985, email max@example.com, IBAN DE89370400440532013000.",
    "language": "de"
  }'

Response:

{
  "original": "Max Mustermann, born 15.03.1985, email max@example.com, IBAN DE89370400440532013000.",
  "pseudonymized": "<<PERSON_1>>, born <<DATE_1>>, email <<EMAIL_1>>, IBAN <<IBAN_1>>.",
  "entities": [
    { "entity_type": "PERSON", "text": "Max Mustermann", "start": 0, "end": 14, "score": 0.95 },
    { "entity_type": "DATE", "text": "15.03.1985", "start": 21, "end": 31, "score": 0.90 },
    { "entity_type": "EMAIL", "text": "max@example.com", "start": 39, "end": 54, "score": 0.99 },
    { "entity_type": "IBAN", "text": "DE89370400440532013000", "start": 61, "end": 83, "score": 0.99 }
  ],
  "mapping": {
    "<<PERSON_1>>": "Max Mustermann",
    "<<DATE_1>>": "15.03.1985",
    "<<EMAIL_1>>": "max@example.com",
    "<<IBAN_1>>": "DE89370400440532013000"
  }
}

Request body:

FieldTypeRequiredDescription
textstringYesThe text to scan for PII
languagestringYesLanguage code (de, en, etc.)

POST /v1/detect

Detect PII entities without pseudonymizing. Returns entity locations and confidence scores.

curl -X POST https://api.noirdoc.de/v1/detect \
  -H "Authorization: Bearer px-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Call Anna Schmidt at +49 170 1234567.",
    "language": "de"
  }'

Header format summary

ProviderHeader formatExample
OpenAI / OpenRouterAuthorization: Bearer <key>Authorization: Bearer px-abc123
Anthropicx-api-key: <key>x-api-key: px-abc123
Azure OpenAIapi-key: <key>api-key: px-abc123

Noirdoc determines the provider pipeline based on which header format is used.

Provider routing

Noirdoc determines the upstream provider based on the authentication header, endpoint path, model name, and query parameters. If no provider is configured for the detected provider type, the API returns a 502 with error code provider_not_configured.

Next steps