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.

Request Headers

Cache Headers

Control how the gateway caches requests and responses.

Prompt Headers

Reference managed prompts from the Floopy prompt library.

Body Field: inputs

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.

Security Headers

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

Token Handling Headers (Coming Soon)

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.

Routing Headers

Override the default routing behavior for a single request.

Rate Limit Headers

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.

Project Scoping

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

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

Session and Property Headers

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.

Response Headers

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