Files

Files reach a model in two ways:

• Inline in the body: as a Base64 data: URL in a message to /v1/chat/completions, /v1/responses or /v1/messages. Noirdoc Shield can decode and inspect inline UTF-8 text files.
• Upload through /v1/files: the gateway passes the file to the provider unchanged. Messages then refer to it by file_id.

Allow file and image attachments

Under Models → Shield in Advanced Settings, the Allow file and image attachments in requests (allow_file_content) switch is on by default. If it is off, the gateway rejects these requests with 403 file_content_not_allowed:

• Messages with file, image or audio parts, including with a file_id reference
• All requests to /v1/files and /v1/skills
• Transcriptions through /v1/audio/transcriptions

Send files inline

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": [
        {
          "type": "text",
          "text": "Summarise the notes."
        },
        {"type": "file", "file": {
          "filename": "notes.txt",
          "file_data": "data:text/plain;base64,Sm9uYXMg..."
        }}
      ]
    }]
  }'

Upload files

curl https://api.noirdoc.de/v1/files \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -F purpose="user_data" \
  -F file="@contract.pdf"

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noirdoc.de/v1",
    api_key=os.environ["NOIRDOC_API_KEY"],
)

uploaded = client.files.create(
    file=open("contract.pdf", "rb"), purpose="user_data"
)
print(uploaded.id)

import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.noirdoc.de/v1",
  apiKey: process.env.NOIRDOC_API_KEY,
});

const uploaded = await client.files.create({
  file: fs.createReadStream("contract.pdf"),
  purpose: "user_data",
});
console.log(uploaded.id);

Managed providers

With providers managed by Noirdoc, several organisations share one account at the provider. The gateway therefore assigns every uploaded file to your organisation:

• GET /v1/files lists your organisation’s files.
• The gateway treats a file_id of another organisation like an unknown one: 404 object_not_found. This also applies to references in messages.

With your own provider (BYOK), this assignment does not apply; there you see your provider’s account.

Skills

/v1/skills passes requests through to Anthropic’s Skills API, also without Shield inspection. The same rule as for /v1/files applies under enforced and X-Noirdoc-Mask: on: the gateway then rejects creating skills and versions with 403 masking_not_supported_for_endpoint. The endpoints are described in detail under Files & Skills.

Legacy file analysis (sunset on 30.11.2026)

For pre-existing organisations still running legacy masking during the transition period until 30.11.2026, the gateway continues to apply file_analysis_mode to inline files when masking is active (including PDF, DOCX, XLSX and text up to the configured maximum size of 25 MB by default, optionally with OCR for scans and images):

• passthrough (Pass through): forwards the file without inspection.
• detect_only (Detect only): detects personal data and forwards the file unchanged (rejected with 403 file_pii_blocked under enforced).
• pseudonymize (Pseudonymize): replaces personal data with placeholders such as <<PERSON_1>> (DOCX, XLSX and text keep their format; PDFs are replaced by their masked text). Text-based downloads via GET /v1/files/{id}/content are re-identified using stored mappings.
• block (Block): rejects files containing personal data with 403 file_pii_blocked.

If legacy file analysis cannot process a file in the block or pseudonymize modes (size limit exceeded, unreadable or unknown format), the gateway answers with 422 file_unprocessable. Once an organisation switches to Noirdoc Shield under Models → Shield, these modes are replaced by the inline UTF-8 text inspection described above.

Errors