작업 생성 및 조회

배치 연동의 골격은 작업 생성 → 주기 조회(폴링) → 산출물 수거 세 단계입니다. 두 API 모두 동일한 API Key로 인증합니다.

작업 생성 API

POST https://bastion-guardian-api.starfort.io/v1/guard/s3

요청 헤더

헤더	필수	설명
`X-Starfort-Guard-Api-Key`	예	`sf_`로 시작하는 발급 키
`Content-Type`	예	`application/json`

요청 본문

{
  "src_s3_url": "s3://your-bucket/inbox/2026/contract-001.docx",
  "tgt_s3_url": "s3://your-bucket/deidentified/",
  "process_type": "INPUT",
  "options": { "on_pass": "copy_original" }
}

필드	필수	설명
`src_s3_url`	예	원본 파일 주소. `s3://<버킷>/<객체 키>` 형식으로 하나의 파일을 가리키며(1 작업 = 1 객체), Storage Connection의 읽기 허용 범위 안이어야 합니다.
`tgt_s3_url`	예	결과 저장 위치. `/`로 끝나면 폴더로 해석되어 원본 파일명 그대로 저장되고, 아니면 그 이름의 파일로 저장됩니다. 쓰기 허용 범위 안이어야 합니다.
`process_type`	예	어떤 정책 묶음으로 검사할지 정하는 처리 유형(예: `"INPUT"`)입니다. 해당 Guardian이 선언한 범위 내여야 하며, 대소문자를 구분하지 않습니다.
`options.on_pass`	아니오	PASS 판정 시 산출물 — `"copy_original"`(기본, 원본 사본 저장) / `"skip"`(저장 안 함).

배치 요청 본문은 snake_case(process_type)를 사용합니다 — 인라인 Guard API의 processType(camelCase)과 표기가 다릅니다.

응답 — 202 Accepted

{ "job_id": "cmd8h2xk10003abcdxyz01234", "status": "PENDING" }

job_id를 보관해 조회에 사용합니다. 검증 시점 — 접수 시점에는 인증 · Kill Switch · process_type · 허용 범위만 동기로 검증합니다(실패 시 작업이 만들어지지 않고 즉시 거부됩니다). 원본의 존재 · 크기 · 형식은 처리 시점에 검사되어, 문제가 있으면 작업이 FAILED로 확정됩니다. 배치 오류를 참고하세요. 재시도와 중복 — 멱등 토큰은 없습니다. 동일 요청을 재전송하면 각각 별개의 작업이 생성됩니다. 응답 유실 시 중복 접수될 수 있으나, 같은 입력·정책의 산출물이 같은 이름으로 원자적으로 덮어써지므로 tgt의 최종 상태는 동일합니다. 접수된 작업의 job_id를 잃었다면 아래 원본 주소 검색으로 복구하세요.

작업 조회 API

GET https://bastion-guardian-api.starfort.io/v1/guard/s3/jobs/{job_id}

응답 — 200

{
  "job_id": "cmd8h2xk10003abcdxyz01234",
  "status": "COMPLETED",
  "action": "MASK",
  "src_s3_url": "s3://your-bucket/inbox/2026/contract-001.docx",
  "tgt_s3_url": "s3://your-bucket/deidentified/contract-001.docx",
  "results": [
    {
      "policy_name": "개인정보 정책", "policy_type": "PII", "action": "MASK",
      "detected_items": [
        { "rule_type": "regex", "rule_name": "resident_number:_all_gender_with_separators", "action": "MASK", "confidence": 1.0, "mask_word": "RESIDENT_NUMBER_1", "alert_message": "resident number detected" }
      ]
    }
  ],
  "error": null,
  "created_at": "2026-07-23T09:00:00.000Z",
  "completed_at": "2026-07-23T09:00:41.000Z"
}

필드	설명
`status`	작업 상태 4종 — `PENDING` / `PROCESSING` / `COMPLETED` / `FAILED`. 배치 개요를 참고하세요.
`action`	`COMPLETED`일 때의 판정(`PASS` / `MASK` / `BLOCK`), 그 외에는 `null`. Actions를 참고하세요.
`tgt_s3_url`	실제 저장된 결과 파일의 확정 주소(폴더로 요청한 경우 파일명까지 포함). 저장된 파일이 없으면 `null`.
`results`	정책별 탐지 결과(걸린 정책 · 탐지 항목 · 마스킹 토큰 · 신뢰도) — Guard API 응답의 결과 구조와 동일하며, 산출물 본문은 포함하지 않습니다(본문은 버킷에만 있습니다).
`error`	`FAILED`일 때의 사유(`code` / `message` / `details`). 배치 오류를 참고하세요.
`created_at` / `completed_at`	접수 시각 / 확정 시각.

조회는 해당 작업을 생성한 프로젝트의 API Key로만 가능합니다.
Kill Switch 발동 중에는 작업 생성과 조회가 모두 거부됩니다.
작업 조회의 보존 기간은 운영 정책을 따르며, 지난 작업의 이력은 Opticon에서 확인합니다 — 각 작업의 트레이스에 접수 정보(src_s3_url · tgt_s3_url · process_type · job_id)와 판정 · 오류가 함께 기록됩니다.

원본 주소로 작업 검색

job_id를 잃은 경우 원본 주소로 최근 작업을 검색해 복구합니다:

GET /v1/guard/s3/jobs?src_s3_url=s3://your-bucket/inbox/2026/contract-001.docx

해당 원본 객체로 접수된 최근 작업 목록을 최신순으로 반환합니다(기본 최대 20건, results 미포함 — 상세는 job_id 단건 조회로 확인하세요).

{ "jobs": [ { "job_id": "cmd8h2xk10003abcdxyz01234", "status": "COMPLETED", "action": "MASK", "src_s3_url": "s3://your-bucket/inbox/2026/contract-001.docx", "tgt_s3_url": "s3://your-bucket/deidentified/contract-001.docx", "error": null, "created_at": "2026-07-23T09:00:00.000Z", "completed_at": "2026-07-23T09:00:41.000Z" } ] }

폴링 패턴

작업 생성

POST /v1/guard/s3를 호출하고 응답의 job_id를 보관합니다.

주기 조회

GET /v1/guard/s3/jobs/{job_id}를 주기적으로 호출합니다. status가 PENDING / PROCESSING이면 계속 대기합니다.

확정 상태 분기

COMPLETED이면 action으로 분기하고(PASS / MASK는 tgt_s3_url에서 산출물 수거, BLOCK은 산출물 없음 — 사유는 results), FAILED이면 error.code로 분기합니다.

curl -X POST https://bastion-guardian-api.starfort.io/v1/guard/s3 \
  -H "X-Starfort-Guard-Api-Key: sf_xxxx..." -H "Content-Type: application/json" \
  -d '{ "src_s3_url": "s3://your-bucket/inbox/customer-list.xlsx", "tgt_s3_url": "s3://your-bucket/deidentified/", "process_type": "INPUT" }'
# → 202 { "job_id": "cmd8h2xk1...", "status": "PENDING" }

curl https://bastion-guardian-api.starfort.io/v1/guard/s3/jobs/cmd8h2xk1... \
  -H "X-Starfort-Guard-Api-Key: sf_xxxx..."
# → 200 { "status": "COMPLETED", "action": "MASK", "tgt_s3_url": "s3://your-bucket/deidentified/customer-list.xlsx", ... }

​작업 생성 API

​작업 조회 API

​원본 주소로 작업 검색

​폴링 패턴

작업 생성 API

작업 조회 API

원본 주소로 작업 검색

폴링 패턴