Guard Gateway API Reference

The Guard Gateway is the primary way to route AI traffic through BeyondGuard. Requests and responses follow the OpenAI chat completions format, so you can point an existing OpenAI-compatible client at it by changing only the base URL and the auth header — no changes to your prompts or model configuration. Every response carries additional BeyondGuard metadata fields, each prefixed with __beyond_guard_, that report the security verdict.

Endpoint


Method	`POST`
URL	`https://<guard_url>/guard-gateway/{gateway-id}`
Content-Type	`application/json`
Authentication	`X-Guard-Token: <token>`

The {gateway-id} in the path is specific to the gateway you configured in your panel, and the <token> is a valid API token issued from that panel. Treat the token like any other long-lived secret.

Send a request

Requests use the standard chat completions body.

curl -X POST https://<guard_url>/guard-gateway/ba18a3ea-61ab-49e5-95ac-8fc6e0ec91a2 \
  -H "Content-Type: application/json" \
  -H "X-Guard-Token: <token>" \
  -d '{"messages": [{"role": "user", "content": "Hello!"}]}'

import requests

res = requests.post(
    "https://<guard_url>/guard-gateway/ba18a3ea-61ab-49e5-95ac-8fc6e0ec91a2",
    headers={"X-Guard-Token": "<token>"},
    json={"messages": [{"role": "user", "content": "Hello!"}]},
)
data = res.json()

is_passed = data["__beyond_guard_checks_result"]["passed"]
content = data["choices"][0]["message"]["content"]

Read the verdict

Every response combines the familiar chat completions envelope with BeyondGuard’s own metadata. The two fields you will use most often:

__beyond_guard_checks_result.passed — true if the request cleared every security control.
__beyond_guard_rejection_codes — populated with reason codes when passed is false.

When passed is false, inspect __beyond_guard_rejection_codes and __beyond_guard_checks_result.details to see exactly which control fired and why.

Response fields

Standard fields

Field	Description
`id`	Unique identifier for the request.
`object`	Always `chat.completion`.
`created`	Unix timestamp of when the response was created.
`model`	Always `beyond-guard-security` for guarded requests.
`choices[].message.role`	`assistant` — the response role.
`choices[].message.content`	The assistant’s reply, or a guard status message.
`choices[].finish_reason`	`stop` when the response completed normally.

BeyondGuard metadata

Field	Description
`__beyond_guard_checks_result.passed`	Boolean — `true` if the request passed all security checks.
`__beyond_guard_checks_result.details`	Array of per-control results; empty when all controls passed.
`__beyond_guard_rejection_codes`	Array of rejection codes; empty when the request is allowed.
`__beyond_guard_timing.total_service_time_ms`	Time spent in the guard service, in milliseconds.
`__beyond_guard_timing.total_processing_time_ms`	Total end-to-end processing time, in milliseconds.
`__beyond_guard_token_usage.model`	Model used for guard token accounting.
`__beyond_guard_token_usage.estimated_cost`	Estimated input, output, and total cost in USD.

Token usage in __beyond_guard_token_usage shows 0 for guard-only requests that were resolved before reaching the language model — for example, a prompt injection denied at the input stage.

Example response

A request that passes all input controls returns the chat completion alongside a populated __beyond_guard_checks_result:

{
  "id": "chatcmpl-ec89f773-3215-4080-a441-27faa",
  "object": "chat.completion",
  "created": 1774444324,
  "model": "beyond-guard-security",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Input controls completed successfully. Request passed security checks.",
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 },
  "__beyond_guard_checks_result": {
    "passed": true,
    "details": []
  },
  "__beyond_guard_rejection_codes": [],
  "__beyond_guard_timing": {
    "total_service_time_ms": 1740.67,
    "total_processing_time_ms": 1752
  }
}

When a control fails, passed is false, __beyond_guard_rejection_codes lists the reason, and details carries the failing control’s verdict, confidence, and evidence.

Quickstart

Route your first request through the Guard Gateway.

Controls Catalog

The controls that produce each verdict.

Policy Configuration

Set the thresholds and outcomes the gateway enforces.

How It Works

Where the gateway sits in your architecture.

Get Started

Core Concepts

Guards

Platform

API Reference

Guides

Deployment

Resources

Guard Gateway API Reference

Endpoint

Send a request

Read the verdict

Response fields

Standard fields

BeyondGuard metadata

Example response

Quickstart

Controls Catalog

Policy Configuration

How It Works

​Endpoint

​Send a request

​Read the verdict

​Response fields

​Standard fields

​BeyondGuard metadata

​Example response

​Related

Quickstart

Controls Catalog

Policy Configuration

How It Works

Endpoint

Send a request

Read the verdict

Response fields

Standard fields

BeyondGuard metadata

Example response

Related