Develop / Reference
Inspected fields (Shield)
Which request fields Noirdoc Shield inspects per endpoint, how it handles attachments and roles, and which fields it leaves unchanged.
This page applies to requests on which Noirdoc Shield is active. Whether Shield runs on a given request is determined by the five-tier precedence across organisation policy, API key, request tags and the X-Noirdoc-Shield header; see Noirdoc Shield and Configure & use Shield.
Endpoints
| Endpoint | Shield inspection | Behaviour |
|---|---|---|
/v1/chat/completions | yes | Inspects messages, tool call arguments and inline UTF-8 text files under 4 MiB |
/v1/responses | yes | Inspects instructions, input, function calls and outputs; /v1/responses/input_tokens skips Shield at €0 |
/v1/messages | yes | Inspects system, messages, tool blocks, text documents and citations; /v1/messages/count_tokens skips Shield at €0 |
/v1/embeddings | yes | Inspects strings, string arrays, multimodal text fields and token ID arrays (tiktoken) |
/v1/rerank | yes | Inspects query, instruction and documents[] |
POST /v1/shield/inspect | yes | Standalone text inspection without calling a model, see Shield (/v1/shield) |
/v1/audio/transcriptions, /v1/audio/speech | no | Not inspected by Shield; returns 403 masking_not_supported_for_endpoint under enforced or with X-Noirdoc-Mask: on |
/v1/images/generations | no | Not inspected by Shield; returns 403 masking_not_supported_for_endpoint under enforced or with X-Noirdoc-Shield: on / X-Noirdoc-Mask: on |
/v1/files, /v1/skills | no | Uploads and skill payloads return 403 masking_not_supported_for_endpoint under enforced or with X-Noirdoc-Mask: on; read/list/delete stay open |
Chat Completions
/v1/chat/completions
| Field | Inspected | Role for injection |
|---|---|---|
messages[].content as string | yes | system, developer and assistant exempt; all other roles checked (user, tool/function as tool, missing or unknown roles as user) |
messages[].content[], parts of type text | yes | follows the message role |
messages[].tool_calls[].function.arguments, every JSON string value | yes | assistant (exempt from injection) |
file parts with inline UTF-8 text under 4 MiB (data: URL) | yes | file text always tool (checked); filename follows the message role |
prediction.content as string or text parts | yes | user (checked) |
image_url, input_audio and binary, referenced or large file parts | no, see Files and images | – |
tools[] (name, description, parameters) and response_format | no | – |
Tool call arguments are JSON strings. Shield parses the JSON, inspects and redacts each string value individually, and re-serialises valid JSON with keys and structure intact. If an argument string is not valid JSON, Shield inspects it as plain text.
The injection filter exempts only system, developer and assistant so system prompts, developer instructions and prior assistant turns do not trigger false positives. All other roles are checked – including user, tool and function (mapped to tool), and missing or unknown roles (mapped to user). All other active filters (secrets, pii, ner, custom) inspect every role.
Responses
/v1/responses
| Field | Inspected | Role for injection |
|---|---|---|
instructions as string or list of items | yes | system (exempt from injection) |
input as string | yes | user (checked) |
input[], messages with string content or input_text / output_text parts | yes | follows the message role |
input[], items of type function_call: arguments, every JSON string value | yes | assistant (exempt from injection) |
input[], items of type function_call_output: output as string or text parts | yes | tool (checked) |
input_file parts with inline UTF-8 text under 4 MiB (data: URL) | yes | file text always tool (checked); filename follows the message role |
input_image and binary, referenced or large input_file parts | no, see Files and images | – |
tools[] (name, description, parameters) and text.format | no | – |
Messages
/v1/messages
| Field | Inspected | Role for injection |
|---|---|---|
system as string or text blocks | yes | system (exempt from injection) |
messages[].content as string or text blocks | yes | user checked; assistant exempt |
tool_use.input, all string values (including nested structures) | yes | assistant (exempt from injection) |
tool_result.content as string or text blocks | yes | tool (checked) |
Code execution blocks (server_tool_use, bash_code_execution_tool_result, text_editor_code_execution_tool_result) | yes | assistant / tool |
document blocks with text source (text, content or Base64 UTF-8 under 4 MiB), plus title and context | yes | user or tool (always checked) |
search_result blocks (text blocks in content[] and title) | yes | user or tool (always checked) |
citations[] in text blocks: cited_text and document_title | yes | follows the message role |
image blocks and binary, referenced or large document blocks | no, see Files and images | – |
thinking blocks returned from earlier responses | no | – |
tools[] (name, description, input_schema) | no | – |
For Anthropic’s code execution tool, Shield inspects all string values inside input on server_tool_use blocks (excluding fixed text-editor command names), as well as stdout, stderr, content and lines on result blocks.
Tool definitions in tools[], output schemas (response_format, text.format) and signed thinking blocks are intentionally left untouched so tool invocations and cryptographic block signatures remain valid at the provider.
Embeddings
/v1/embeddings
| Field | Inspected | Behaviour |
|---|---|---|
input as a single string | yes | Inspected directly and forwarded with [LABEL] placeholders |
input as an array of strings | yes | Each element is inspected as its own segment |
input as multimodal object(s) | yes | All string fields except image and image_url are inspected; image fields count as uninspectable media |
input as an integer token ID array (or array of token ID arrays) | yes | Decoded via tiktoken for the target model, inspected and redacted by Shield, then re-encoded into token IDs |
All segments on /v1/embeddings are evaluated under the user role. If a token array cannot be decoded, it is recorded as unrecognised_content and rejected with status code 422 (shield_uninspectable_content) under enforced.
Rerank
/v1/rerank
| Field | Inspected | Behaviour |
|---|---|---|
query | yes | Inspected as a string or across the text fields of an object (user role) |
instruction | yes | Inspected when passed as a string |
documents[] | yes | Every string or document object text field (excluding image / image_url) is inspected |
No modification of the response
Noirdoc Shield modifies only the outbound request and stores no state between request and response:
- The model receives fixed category placeholders such as
[PERSON],[IBAN]or[CUSTOM]and may refer to those placeholders in its reply. - Text completions,
tool_calls/tool_useblocks, citations and streaming chunks pass straight back to your application with zero sentence-buffering latency and no reverse substitution. - No extra system prompt is injected.
When local tools invoked by the model need to look up records in your own database, expose internal record identifiers (such as contact_id: "c_8492") to the model rather than relying on reversed personal names or IBANs in tool_calls.
Files and images
Before Shield runs, the organisation gate Allow file and image attachments in requests (allow_file_content under Models → Shield → Advanced Settings) is checked. When turned off, any request containing file, image or audio parts is rejected with status code 403 (file_content_not_allowed).
When allow_file_content is turned on, Shield handles attachments as follows:
| Attachment type | Behaviour under default_on / on | Behaviour under enforced |
|---|---|---|
Inline UTF-8 text attachments (text/*, JSON, XML, CSV, Markdown, YAML) under 4 MiB decoded | Decoded, inspected by Shield and redacted in-place (X-Noirdoc-Shield: redacted=<n>, X-Noirdoc-Masked: true) | Same as left (fully inspected and permitted) |
| Binary documents (PDF, DOCX, XLSX, PPTX) | Text fields are inspected; file is forwarded alongside (X-Noirdoc-Shield: partial; redacted=<n>, X-Noirdoc-Masked: false) | Rejected with 422 shield_uninspectable_content |
Images, audio and video (image_url, image, input_image, input_audio) | Text fields are inspected; media is forwarded alongside (partial; redacted=<n>, X-Noirdoc-Masked: false) | Rejected with 422 shield_uninspectable_content |
External references via file_id or URL, inline files >= 4 MiB or non-UTF-8 payloads | Text fields are inspected; reference/file is forwarded alongside (partial; redacted=<n>, X-Noirdoc-Masked: false) | Rejected with 422 shield_uninspectable_content |
To have PDF, Word or Excel documents inspected by Shield – including under enforced – extract their text client-side before calling the API and pass it as message text or an inline UTF-8 text attachment under 4 MiB.
Legacy masking
Pre-existing organisations in transition mode until 30 November 2026 (2026-11-30T23:59:59Z) that have not yet switched to Noirdoc Shield continue using legacy reversible masking on /v1/chat/completions, /v1/responses and /v1/messages (unless X-Noirdoc-Shield: on or shield_mode: "on" is active):
- Numbered placeholders & reverse substitution: detected values become
<<TYPE_N>>(such as<<PERSON_1>>), the mapping is stored encrypted in Redis (Mapping-TTL, default 30 days), a brief system instruction is prepended, and responses, tool call arguments, sentence-buffered streams and downloaded text/DOCX/XLSX files have original values substituted back in. - No inspection on Embeddings or Rerank:
/v1/embeddingsand/v1/rerankare not supported by legacy masking (403 masking_not_supported_for_endpointunderenforcedor withX-Noirdoc-Mask: on). - Legacy file analysis: Base64 files (including PDF, DOCX, XLSX and optional OCR) follow the configured
file_analysis_mode(passthrough,detect_only,pseudonymize,block; error codes403 file_pii_blockedand422 file_unprocessable).
See Noirdoc Shield – Legacy masking for details on the Deprecation and Sunset headers and the one-click switch under Models → Shield.