Files & Skills

Family

pass-through

Shield

no

Streaming

no

Format

as at the provider, upload as multipart/form-data

Billing

none

Requirements

Files and skills work only if admins of your organisation have turned on Allow file and image attachments in requests under Models → Shield (Advanced Settings). Otherwise, the gateway answers with 403 file_content_not_allowed.

Because /v1/files and /v1/skills are not inspected by Noirdoc Shield, the gateway rejects content-carrying calls when the enforced policy is active or the request sends X-Noirdoc-Mask: on (fail-closed). This affects all methods except GET, HEAD, OPTIONS and DELETE, for example uploading a file and creating a skill or a version. The gateway then answers with 403 masking_not_supported_for_endpoint. Listing, retrieving, downloading and deleting remain allowed.

Select the provider

These calls carry no model. The gateway therefore first determines the API format and then forwards the call to the oldest active provider of this format. Providers that your organisation has connected itself (BYOK) take precedence. Claude through Google Vertex is not eligible for this.

X-Provider selects only the format. The restrictions of your key and your organisation still apply. If no provider is set up for the format, the gateway answers with 502 provider_not_configured.

The Anthropic SDK sends the key as x-api-key. The gateway then forwards the call to an Anthropic provider. The OpenAI SDK sends Authorization: Bearer and ends up at a provider in the OpenAI format.

If an Anthropic client uses Authorization: Bearer, set X-Provider: anthropic.

curl https://api.noirdoc.de/v1/files \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "X-Provider: anthropic" \
  -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"],
)

with open("contract.pdf", "rb") as f:
    uploaded = client.files.create(file=f, 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);