ジョブの作成と照会

バッチ連携の骨格は、ジョブの作成 → 定期照会（ポーリング）→ 成果物の回収という 3 ステップです。どちらの 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 ジョブ = 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": "PII Masking Policy", "policy_type": "PII", "action": "MASK",
      "detected_items": [
        { "rule_type": "regex", "rule_name": "my_number:_japan_individual_number", "action": "MASK", "confidence": 1.0, "mask_word": "MY_NUMBER_1", "alert_message": "マイナンバーを検知しました" }
      ]
    }
  ],
  "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`。アクションを参照してください。
`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

原本アドレスによるジョブ検索

ポーリングパターン