Headers Reference

Floopy uses custom HTTP headers to control gateway behavior on a per-request basis. Pass these headers alongside your standard Authorization and Content-Type headers when calling the gateway.

Control how the gateway caches requests and responses.

Reference managed prompts from the Floopy prompt library.

By default a prompt’s model and provider override whatever the request sends, so a caller attached to a prompt cannot pick a different model. (The sampling parameters behave the other way round: the prompt only supplies a default, and a value on the request already wins.)

Send floopy-prompt-overwrite: true to hand that control back to the caller. The model on the request then wins over both the prompt’s model and any provider default_model configured for the organization, and the prompt fills in only the fields the request omitted:

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "floopy-prompt-id: e51a2820-8ab5-4d6a-96a0-cc7bb4759371" \
  -H "floopy-prompt-overwrite: true" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "Hi"}]}'

Accepted values are true / 1 / yes and false / 0 / no (case-insensitive).

The header takes precedence over the prompt’s own Let the request override this configuration checkbox in both directions — so floopy-prompt-overwrite: false also lets a caller pin itself to the prompt’s configuration on a prompt that otherwise hands control away. An absent or unrecognized value falls back to the prompt’s setting.

The prompt’s messages are prepended either way: the flag governs configuration, not content. Smart Selector provider overrides also still take precedence, since those are routing decisions rather than prompt configuration.

When using a managed prompt with floopy-prompt-id, you can pass an inputs object in the JSON request body to fill template variables. The gateway substitutes {{key}} placeholders in the prompt template with the corresponding values from inputs.

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "placeholder"}],
  "inputs": {
    "language": "English",
    "topic": "quantum computing"
  }
}

Resolution order: inputs values take priority, then template defaults from the prompt config, then the placeholder is left as-is. The inputs field is stripped before the request reaches the LLM provider.

See the Prompt Management guide for full examples.

Enable the LLM firewall to scan prompts for injection attacks and unsafe content.

Control how the gateway handles requests that exceed a model’s context window. This feature is planned and not yet available.

The three planned strategies are:

• truncate — Removes messages from the beginning of the conversation to fit within the model’s token limit. The system message and the most recent messages are preserved.
• middle-out — Keeps the first and last messages in the conversation and removes messages from the middle. Useful when both the initial context and the latest user message are important.
• fallback — Switches to a model with a larger context window instead of modifying the messages. The gateway selects an appropriate model from the same provider.

Override the default routing behavior for a single request.

Override the default rate limit policy for a single request.

The policy format is <limit>;w=<window>;u=<unit>;s=<segment>:

• limit — The maximum number of allowed units within the window.
• w (window) — Time window in seconds. The minimum window is 60 seconds.
• u (unit) — The unit to count: request (number of requests) or cents (cost in cents).
• s (segment) — How to segment the limit: global (shared across all users), user (per end-user via floopy-user-id), or custom (per custom key).

Example: 100;w=60;u=request;s=global means 100 requests per 60 seconds, applied globally.

Segment requests by project for per-project cost tracking and analytics.

See the Projects guide for the full fallback chain and environment model.

Attach session metadata and custom properties to requests for tracking and analytics.

Custom properties appear in the observability dashboard and can be used to filter and group requests.

The gateway adds these headers to every response. They provide metadata about how the request was processed.