> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beyondguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Guard Gateway API Reference

> Send prompts through BeyondGuard's OpenAI-compatible Guard Gateway and read the inline security verdict on every response.

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.

<CodeGroup>
  ```bash cURL theme={null}
  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!"}]}'
  ```

  ```python Python theme={null}
  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"]
  ```
</CodeGroup>

## 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. |

<Note>
  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.
</Note>

## Example response

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

```json theme={null}
{
  "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.

## Related

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Route your first request through the Guard Gateway.
  </Card>

  <Card title="Controls Catalog" icon="list-check" href="/concepts/controls-catalog">
    The controls that produce each verdict.
  </Card>

  <Card title="Policy Configuration" icon="sliders" href="/guides/policy-configuration">
    Set the thresholds and outcomes the gateway enforces.
  </Card>

  <Card title="How It Works" icon="diagram-project" href="/how-it-works">
    Where the gateway sits in your architecture.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.