Content-Type: application/json과 함께 POST https://bastion-guardian-api.starfort.io/v1/guard/api를 호출합니다.
{
"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 | 아니오 | 트레이싱 힌트입니다. 트레이싱이 필요 없으면 전체를 생략하세요. |
요청은 camelCase(processType, additionalData)를 사용합니다. 이는 프로덕션 API가 기대하는 필드 이름입니다.
processType
processType는 Guardian이 정의하는 자유 형식 레이블이며 고정된 enum이 아닙니다. 대부분의 Guardian은 input(들어오는 요청을 보호)과 output(나가는 모델 응답을 보호)을 선언하지만, Guardian은 자신이 지원하는 어떤 이름이든 선언할 수 있습니다.
- 대소문자 구분 없음 — 값은 매칭 전에 트리밍되고 소문자로 변환되므로
"input", "INPUT", " Input "은 모두 동일한 호출입니다.
- 값은 호출 대상 Guardian이 지원하는 것이어야 합니다. 그렇지 않으면 사전 검증 단계에서 호출이 거부되며, 오류 메시지에 지원되는 프로세스 타입이 나열됩니다. 오류 및 상태를 참고하세요.
- 일부 프로세스 타입은 **정책 불필요(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가 해당 호출에 대해 기록하는 트레이스에 트레이싱 메타데이터를 첨부합니다:
| 필드 | 용도 |
|---|
trace_id | 사용자가 지정하는 트레이스 식별자입니다(생략 시 자동 생성). |
session_id | 관련 호출을 하나의 세션으로 묶습니다. |
user_id | 최종 사용자 식별자입니다. |
metadata | 임의의 키/값입니다. |
tags | 사용자가 지정하는 태그입니다. Starfort는 action 및 정책 태그도 자동으로 추가합니다. |
action, 각 policy_type:action / policy_name:action, 그리고 API 키의 이름이 태그로 추가됩니다. processType, 마스킹된 API 키 식별자, 그리고 확정된 Model Configuration은 metadata에, 정책별 탐지 건수는 scores로 기록됩니다. 키가 충돌하면 시스템 값이 우선합니다. 트레이싱은 best-effort 방식이며 호출을 절대 차단하지 않습니다. Opticon 모니터링을 참고하세요.
messages 내부의 멀티모달 콘텐츠(이미지, 오디오, 파일, 비디오)에 대해서는 멀티모달 입력을 참고하세요.
