Chat completions

POST https://api.safeguard.sh/gpt/v1/chat/completions

The request and response follow OpenAI's Chat Completions format. Safeguard reads a few fields itself, passes a fixed set of optional fields to the provider, and ignores everything else.

Request

Send JSON with Content-Type: application/json and your key in Authorization: Bearer <key>. The body can be up to 8 MiB; a larger body is refused with 413 request_too_large.

Fields Safeguard reads

The output token cap sent to the provider is the value you set, lowered to the model's max_output_tokens when the catalog states one. If you set none, the cap is 4,096 tokens or the model's maximum, whichever is lower.

Fields passed to the provider

These are forwarded unchanged when present. The gateway does not check their values; the provider does.

For Anthropic models, only temperature, tools and tool_choice from the two tables are sent with the messages and the token cap; top_p, stop, response_format, seed, the penalties and parallel_tool_calls are not. When you set no temperature, the provider's own default applies.

Any field not listed on this page is ignored and not forwarded.

Messages

Each message is an object with a role and, usually, content.

• role is one of system, developer, user, assistant or tool. The gateway accepts all five; whether a model accepts developer or tool messages is up to its provider.
• content is a string, null, or an array of text parts such as {"type": "text", "text": "..."}. A part of any other type, such as an image or audio, is refused with 400 unsupported_parameter.
• name, tool_calls and tool_call_id are kept. Other keys on a message are dropped.

Routing options

provider is a Safeguard extension:

"provider": { "allow_fallbacks": true, "zdr": true }

Fallbacks never leave the model family, and never go to the models Safeguard uses for its own platform features.

Where routing is switched on for your workspace, provider also takes order, only, ignore and sort, and the request can list more models in models. Where it is not, those fields are refused with 400 unsupported_parameter.

When a provider rejects a parameter

Providers do not all accept the same parameters. If a provider rejects the token limit's name, the gateway switches between max_tokens and max_completion_tokens and sends the request again. If it rejects another optional parameter as unsupported for the model, such as a temperature the model does not allow, the gateway drops that parameter and sends the request again. These repeats go to the same provider and are not fallbacks.

Examples

A basic request

curl https://api.safeguard.sh/gpt/v1/chat/completions \
  -H "Authorization: Bearer $SAFEGUARD_INFERENCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "system", "content": "Answer in one short paragraph."},
      {"role": "user", "content": "What does reachability analysis add to a vulnerability scan?"}
    ],
    "max_completion_tokens": 300,
    "temperature": 0.2
  }'

Calling a tool

The gateway passes tools and tool_choice to the provider and returns the provider's tool_calls in the message.

curl https://api.safeguard.sh/gpt/v1/chat/completions \
  -H "Authorization: Bearer $SAFEGUARD_INFERENCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Is lodash 4.17.20 affected by a known vulnerability?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "lookup_package",
        "description": "Look up known vulnerabilities for a package version.",
        "parameters": {
          "type": "object",
          "properties": {
            "ecosystem": {"type": "string"},
            "name": {"type": "string"},
            "version": {"type": "string"}
          },
          "required": ["ecosystem", "name", "version"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

To continue the conversation, send the assistant message with its tool_calls, then a tool message with the matching tool_call_id and your function's result as content.

Requiring zero data retention and allowing fallbacks

provider is not an OpenAI parameter, so the OpenAI SDKs send it through extra_body (Python) or as an extra field (Node.js).

curl https://api.safeguard.sh/gpt/v1/chat/completions \
  -H "Authorization: Bearer $SAFEGUARD_INFERENCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Summarise this incident report in three bullet points: ..."}],
    "provider": {"zdr": true, "allow_fallbacks": true}
  }'

Response

{
  "id": "gen-6f1c2e0a9b4d4c7e8a1f3b5d7c9e0a2b",
  "object": "chat.completion",
  "created": 1791475000,
  "model": "MODEL_ID",
  "provider": "openai",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Reachability analysis checks whether ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 41,
    "completion_tokens": 120,
    "total_tokens": 161,
    "cost": 0.000521
  }
}

The values above are illustrative.

Cost

For each request the gateway works out:

cost = (input tokens × input price + output tokens × output price) ÷ 1,000,000

with prices in US dollars per million tokens from the catalog, and no markup. When the catalog has a cached-input price, cached input tokens are charged at that price instead of the input price. The result is rounded half up to 8 decimal places.

Before calling the provider, the gateway reserves the most the request could cost and refuses it with 402 if that does not fit your credit or a spend limit. After the call, it charges the actual cost and releases the rest. A request that ends in an error before any output costs nothing. See Limits and Pricing and billing.

Errors

Errors use OpenAI's shape, {"error": {"message", "type", "code", "param"}}. Errors lists every status and code.

Related

• Streaming
• Models
• Errors
• Limits