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

# Request format

> The Guard API request body: messages, processType, additionalData, and optional Opticon tracing.

`POST https://bastion-guardian-api.starfort.io/v1/guard/api` with `Content-Type: application/json`.

```json theme={null}
{
  "messages": [
    { "role": "user", "content": "Please share John Smith's number 010-1234-5678." }
  ],
  "processType": "input",
  "additionalData": {},
  "opticon": {
    "trace_id": "your-trace-id",
    "session_id": "your-session-id",
    "user_id": "end-user-id",
    "metadata": { "any": "value" },
    "tags": ["your-tag"]
  }
}
```

## Fields

| Field            | Type   | Required | Notes                                                                                                                     |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `messages`       | array  | yes      | OpenAI Chat Completions-style messages.                                                                                   |
| `processType`    | string | yes      | A label the **Guardian declares** (commonly `input` / `output`). **Case-insensitive.** Must be one the Guardian supports. |
| `additionalData` | object | no       | Extra per-call data, when a process type expects it.                                                                      |
| `opticon`        | object | no       | Tracing hints. Omit entirely if you don't need tracing.                                                                   |

<Note>
  The request uses **camelCase** (`processType`, `additionalData`). These are the field names the production API expects.
</Note>

### `processType`

`processType` is a **free-form label the Guardian defines** — not a fixed enum. Most Guardians declare `input` (guard a request on the way in) and `output` (guard a model response on the way out), but a Guardian can declare any names it supports.

* **Case-insensitive** — the value is trimmed and lowercased before matching, so `"input"`, `"INPUT"`, and `" Input "` are the same call.
* The value **must be one the called Guardian supports.** If it isn't, the call is rejected during pre-validation and the error message lists the supported process types. See [Errors & states](/en/v1.2/api/errors).
* Some process types are **policy-not-required** (the Guardian declares no compatible policy types for them). Those run with no Guard Policy and are driven entirely by `additionalData`.

### `additionalData`

`additionalData` is the standard slot for extra input a process type needs. Starfort **merges** the values configured on the Guardian with the values you send — **your values win** on a key conflict — and passes the result to the Guardian unchanged. It is free-form JSON (only JSON validity is checked). For example, a policy-not-required process type might take `{ "check_criteria": [...] }` as its evaluation basis.

## Message roles — only `user` is inspected

Each message has a `role`. The Guardian inspects **only `user` messages**; the rest are kept for context but never masked or blocked.

| Role                               | Behavior                                                                                          |
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
| `user`                             | **Inspected.** Each content part may be masked or blocked. Put the content you want guarded here. |
| `assistant`                        | Kept as multi-turn context; not inspected, never masked.                                          |
| `system`                           | Treated as operator instructions; skipped entirely.                                               |
| any other (`tool`, `developer`, …) | Kept in the payload but not inspected.                                                            |

A request with **no `user` message** passes through unchecked — always send the content you want guarded with role `user`.

## Opticon tracing (optional)

The `opticon` object attaches tracing metadata to the [trace](/en/v1.2/admin/monitoring-opticon) Starfort records for the call:

| Field        | Purpose                                                    |
| ------------ | ---------------------------------------------------------- |
| `trace_id`   | Your own trace identifier (auto-generated if omitted).     |
| `session_id` | Groups related calls into a session.                       |
| `user_id`    | End-user identifier.                                       |
| `metadata`   | Arbitrary key/values.                                      |
| `tags`       | Your tags; Starfort also auto-adds action and policy tags. |

Alongside your fields, Starfort enriches each trace automatically: the trace **name** is the Project Guardian's name; the root `action`, each `policy_type:action` / `policy_name:action`, and the **API key's name** are added as **tags**; `processType`, the masked API-key identifier, and the resolved Model Configuration go to **metadata**; and per-policy detection counts are recorded as **scores**. On a key conflict the system value wins. Tracing is best-effort and never blocks the call. See [Opticon monitoring](/en/v1.2/admin/monitoring-opticon).

For multimodal content (images, audio, files, video) inside `messages`, see [Multimodal inputs](/en/v1.2/api/multimodal).