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

# 요청 형식

> Starfort Guard API 요청 본문. messages 배열, processType, additionalData, Opticon 트레이싱을 입력 타입별 예시로 설명합니다 (Starfort v1.4 문서)

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

```json theme={"dark"}
{
  "messages": [
    { "role": "user", "content": "Please share John Smith's number 010-1234-5678." }
  ],
  "processType": "input",
  "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이 지원하는 값이어야 합니다. |
| `opticon`     | object | 아니오 | 트레이싱 힌트입니다. 트레이싱이 필요 없으면 전체를 생략하세요.                                                                |

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

### `processType`

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

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

## 메시지 role — 모든 메시지가 검사됨

Guardian은 **`role`에 관계없이 보낸 내용 전부**를 평가합니다. PII 규칙은 모든 메시지(`user`, `assistant`, `system` 및 그 외 어떤 role이든)의 각 콘텐츠 파트에 대해 실행되므로, assistant 응답이나 system 프롬프트에 담긴 민감 정보도 사용자 입력과 똑같이 마스킹되거나 차단됩니다. Topic 정책은 `system` 메시지를 포함해 병합된 대화 전체를 대상으로 요청을 **한 번에** 평가합니다.

검사를 건너뛰는 role은 없습니다. 보호하려는 대화를 그대로 보내세요.

## 검사 한도 — Guardian이 단일 지점에서 강제

프로젝트에 설정된 검사 한도(텍스트 길이 · 파일 크기)는 v1.4부터 **Guardian이 단일 지점에서 강제**합니다. 게이트웨이는 프로젝트가 정한 한도 값을 Guardian에 전달만 하고, Guardian이 요청의 최상위 입력뿐 아니라 **파일에서 추출된 텍스트, 아카이브 내부 멤버까지** 자신이 보는 모든 콘텐츠에 같은 한도를 적용합니다. 따라서 한도 위반은 어느 단계에서 걸리든 일관된 Guardian 거부로 나타나며, 위반 시 요청은 [오류](/ko/v1.4/api/errors)로 거부됩니다.

이와 별개로 게이트웨이에는 어떤 설정과도 무관한 플랫폼 **입력 수신 상한**(요청 본문 크기의 인프라 보호선)이 있습니다 — 프로젝트의 검사 한도는 그 이하에서 자유롭게 설정됩니다.

## Opticon 트레이싱(선택)

`opticon` 객체는 Starfort가 해당 호출에 대해 기록하는 [트레이스](/ko/v1.4/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 키 식별자, 그리고 확정된 모델 구성은 **metadata**에, 정책별 탐지 건수는 **scores**로 기록됩니다. 키가 충돌하면 시스템 값이 우선합니다. 트레이싱은 best-effort 방식이며 호출을 절대 차단하지 않습니다. [Opticon 모니터링](/ko/v1.4/admin/monitoring-opticon)을 참고하세요.

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