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

# 요청 형식

> Guard API 요청 본문: messages, processType, additionalData 및 선택적 Opticon 트레이싱.

`Content-Type: application/json`과 함께 `POST https://bastion-guardian-api.starfort.io/v1/guard/api`를 호출합니다.

```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"]
  }
}
```

## 필드

| 필드               | 타입     | 필수  | 설명                                                                                                 |
| ---------------- | ------ | --- | -------------------------------------------------------------------------------------------------- |
| `messages`       | array  | 예   | OpenAI Chat Completions 형식의 메시지입니다.                                                                |
| `processType`    | string | 예   | **Guardian이 선언하는** 레이블입니다(일반적으로 `input` / `output`). **대소문자를 구분하지 않습니다.** Guardian이 지원하는 값이어야 합니다. |
| `additionalData` | object | 아니오 | 프로세스 타입이 요구할 때 사용하는 호출별 추가 데이터입니다.                                                                 |
| `opticon`        | object | 아니오 | 트레이싱 힌트입니다. 트레이싱이 필요 없으면 전체를 생략하세요.                                                                |

<Note>
  요청은 **camelCase**(`processType`, `additionalData`)를 사용합니다. 이는 프로덕션 API가 기대하는 필드 이름입니다.
</Note>

### `processType`

`processType`는 **Guardian이 정의하는 자유 형식 레이블**이며 고정된 enum이 아닙니다. 대부분의 Guardian은 `input`(들어오는 요청을 보호)과 `output`(나가는 모델 응답을 보호)을 선언하지만, Guardian은 자신이 지원하는 어떤 이름이든 선언할 수 있습니다.

* **대소문자 구분 없음** — 값은 매칭 전에 트리밍되고 소문자로 변환되므로 `"input"`, `"INPUT"`, `" Input "`은 모두 동일한 호출입니다.
* 값은 **호출 대상 Guardian이 지원하는 것이어야 합니다.** 그렇지 않으면 사전 검증 단계에서 호출이 거부되며, 오류 메시지에 지원되는 프로세스 타입이 나열됩니다. [오류 및 상태](/ko/v1.2/api/errors)를 참고하세요.
* 일부 프로세스 타입은 \*\*정책 불필요(policy-not-required)\*\*입니다(Guardian이 해당 타입에 호환되는 정책 타입을 선언하지 않음). 이러한 타입은 Guard Policy 없이 실행되며 전적으로 `additionalData`로 구동됩니다.

### `additionalData`

`additionalData`는 프로세스 타입이 필요로 하는 추가 입력을 위한 표준 슬롯입니다. Starfort는 Guardian에 구성된 값과 사용자가 보낸 값을 **병합**하며 — 키가 충돌하면 **사용자 값이 우선합니다** — 그 결과를 변경 없이 Guardian에 전달합니다. 자유 형식 JSON이며(JSON 유효성만 검사됨), 예를 들어 정책 불필요 프로세스 타입은 평가 기준으로 `{ "check_criteria": [...] }`를 받을 수 있습니다.

## 메시지 role — `user`만 검사됨

각 메시지에는 `role`이 있습니다. Guardian은 **`user` 메시지만 검사하며**, 나머지는 컨텍스트로 유지되지만 절대 마스킹하거나 차단하지 않습니다.

| Role                       | 동작                                                        |
| -------------------------- | --------------------------------------------------------- |
| `user`                     | **검사됨.** 각 콘텐츠 파트가 마스킹되거나 차단될 수 있습니다. 보호하려는 내용을 여기에 넣으세요. |
| `assistant`                | 멀티턴 컨텍스트로 유지됩니다. 검사되지 않으며 절대 마스킹되지 않습니다.                  |
| `system`                   | 운영자 지시로 취급되어 완전히 건너뜁니다.                                   |
| 기타(`tool`, `developer`, …) | 페이로드에 유지되지만 검사되지 않습니다.                                    |

**`user` 메시지가 없는** 요청은 검사 없이 통과합니다 — 보호하려는 내용은 항상 `user` role로 보내세요.

## Opticon 트레이싱(선택)

`opticon` 객체는 Starfort가 해당 호출에 대해 기록하는 [트레이스](/ko/v1.2/admin/monitoring-opticon)에 트레이싱 메타데이터를 첨부합니다:

| 필드           | 용도                                                     |
| ------------ | ------------------------------------------------------ |
| `trace_id`   | 사용자가 지정하는 트레이스 식별자입니다(생략 시 자동 생성).                     |
| `session_id` | 관련 호출을 하나의 세션으로 묶습니다.                                  |
| `user_id`    | 최종 사용자 식별자입니다.                                         |
| `metadata`   | 임의의 키/값입니다.                                            |
| `tags`       | 사용자가 지정하는 태그입니다. Starfort는 action 및 정책 태그도 자동으로 추가합니다. |

사용자가 보낸 필드와 함께 Starfort는 각 트레이스를 자동으로 보강합니다: 트레이스 **이름**은 Project Guardian의 이름이고, 루트 `action`, 각 `policy_type:action` / `policy_name:action`, 그리고 **API 키의 이름**이 **태그**로 추가됩니다. `processType`, 마스킹된 API 키 식별자, 그리고 확정된 Model Configuration은 **metadata**에, 정책별 탐지 건수는 **scores**로 기록됩니다. 키가 충돌하면 시스템 값이 우선합니다. 트레이싱은 best-effort 방식이며 호출을 절대 차단하지 않습니다. [Opticon 모니터링](/ko/v1.2/admin/monitoring-opticon)을 참고하세요.

`messages` 내부의 멀티모달 콘텐츠(이미지, 오디오, 파일, 비디오)에 대해서는 [멀티모달 입력](/ko/v1.2/api/multimodal)을 참고하세요.