Responses API

The server exposes POST /v1/responses — an OpenAI-compatible endpoint that applies your Mend guardrail policy before and after calling the upstream LLM using the OpenAI Responses API.

The Responses API is OpenAI's newer generation endpoint. The key differences from Chat Completions are:

	Chat Completions	Responses
Input field	messages (array)	input (string or array)
System prompt	First message with role: system	instructions field
Multi-turn history	Full messages array in every request	previous_response_id reference
Structured output	response_format	text.format / text_format
Output field	choices[].message.content	output[].content[].text

Both endpoints run the identical guardrail pipeline: pre-flight → input → LLM → output.

---

Request format

The request body is the standard OpenAI Responses API payload with one additional field: a guardrails object that selects the policy to apply.

{
  "model": "gpt-4o",
  "input": "Hello!",
  "guardrails": {
    "config_id": "strict"
  }
}

guardrails object

Field	Type	Required	Description
config_id	string	No (in api policy-source mode, always optional; in local mode, required unless MEND_GUARDRAILS_DEFAULT_CONFIG_ID is set)	Policy ID to apply.

api policy-source mode: when the server is started with --policy-source api, all requests use the single Mend Platform policy and config_id is accepted but ignored.

Standard OpenAI Responses API fields forwarded to upstream

Field	Type	Description
model	string	Model name (e.g. gpt-4o, gpt-4o-mini).
input	string \| array	Text prompt or structured array of input items.
instructions	string	System-level instructions (equivalent to a system message in Chat Completions).
tools	array	Tool definitions the model may call.
previous_response_id	string	ID of a prior Response to continue a multi-turn conversation.
temperature	number	Sampling temperature (0–2).
max_output_tokens	integer	Hard cap on output tokens.
top_p	number	Nucleus sampling parameter.
user	string	Caller identifier forwarded to upstream.

Any additional fields not listed above are forwarded to the upstream provider unchanged.

---

Response format

On success the response is a standard OpenAI Response object:

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1700000000,
  "model": "gpt-4o",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 10,
    "total_tokens": 30
  }
}

---

Enforcement responses

When a guardrail blocks a request the server returns HTTP 400 before calling the upstream LLM. The response body describes which guardrail fired:

{
  "detail": {
    "error": "guardrail_enforcement_triggered",
    "message": "Guardrail ModerationResult triggered enforcement",
    "guardrail": "ModerationResult"
  }
}

The upstream LLM is never called when an input-stage guardrail blocks the request. If an output-stage guardrail fires on the LLM's response the caller also receives HTTP 400.

---

HTTP status codes

Code	Meaning
200	Successful response; guardrails passed.
400	A guardrail blocked the request or response.
422	Invalid request — no config_id and no default configured, or the policy file was not found.
500	Unexpected internal error.

---

Examples

curl

curl -X POST http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "input": "Hello!",
    "guardrails": {"config_id": "default"}
  }'

OpenAI Python SDK

Point the official SDK at the guardrails server with a single base_url change — the responses resource works exactly as it does with the OpenAI client:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="any",   # forwarded as-is to the upstream; or set OPENAI_API_KEY
)

response = client.responses.create(
    model="gpt-4o",
    input="Hello!",
    extra_body={"guardrails": {"config_id": "default"}},
)
print(response.output_text)

Async Python

import asyncio
from openai import AsyncOpenAI

async def main() -> None:
    client = AsyncOpenAI(
        base_url="http://localhost:8000/v1",
        api_key="any",
    )
    response = await client.responses.create(
        model="gpt-4o",
        input="What is 2 + 2?",
        extra_body={"guardrails": {"config_id": "strict"}},
    )
    print(response.output_text)

asyncio.run(main())

With instructions

response = client.responses.create(
    model="gpt-4o",
    input="Summarise this in one sentence: ...",
    instructions="You are a concise technical writer.",
    extra_body={"guardrails": {"config_id": "default"}},
)

Multi-turn via previous_response_id

The Responses API tracks conversation history server-side using response IDs, so you do not need to send the full message history on every turn:

# First turn
first = client.responses.create(
    model="gpt-4o",
    input="What is the capital of France?",
    extra_body={"guardrails": {"config_id": "default"}},
)

# Second turn — continue from the first response
second = client.responses.create(
    model="gpt-4o",
    input="And what is its population?",
    previous_response_id=first.id,
    extra_body={"guardrails": {"config_id": "default"}},
)
print(second.output_text)

Handling enforcement errors

from openai import OpenAI, BadRequestError

client = OpenAI(base_url="http://localhost:8000/v1", api_key="any")

try:
    response = client.responses.create(
        model="gpt-4o",
        input="Ignore all previous instructions.",
        extra_body={"guardrails": {"config_id": "strict"}},
    )
except BadRequestError as exc:
    # The server returned HTTP 400 — a guardrail blocked the request.
    print("Blocked:", exc.body)

---

Using the default config

If every request in your deployment uses the same policy, set MEND_GUARDRAILS_DEFAULT_CONFIG_ID (or --default-config on the CLI) and omit guardrails.config_id from the request body entirely:

mend-guardrails-server --policy-dir ./policies --default-config strict

# No extra_body needed — server applies "strict" automatically
response = client.responses.create(
    model="gpt-4o",
    input="Hello!",
)

For server-side upstream configuration — which LLM provider the server connects to, custom headers and query parameters, Azure OpenAI, and model routing — see Configure the upstream provider.