Create & poll jobs

A batch integration is three steps: create a job → poll → collect the output. Both APIs authenticate with the same API key.

Job creation API

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

Request headers

Header	Required	Description
`X-Starfort-Guard-Api-Key`	Yes	Your issued `sf_`-prefixed key
`Content-Type`	Yes	`application/json`

Request body

{
  "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" }
}

Field	Required	Description
`src_s3_url`	Yes	The source file’s address. `s3://<bucket>/<object key>`, pointing at one file (1 job = 1 object), and inside the Storage Connection’s allowed read scope.
`tgt_s3_url`	Yes	Where to write the result. A trailing `/` is interpreted as a folder (the output keeps the source file name); otherwise it’s written as a file with that name. Must be inside the allowed write scope.
`process_type`	Yes	The processing type that picks which policy set to inspect with (e.g. `"INPUT"`). Must be within what the Guardian declares; case-insensitive.
`options.on_pass`	No	The output on a PASS verdict — `"copy_original"` (default, writes a copy of the original) / `"skip"` (writes nothing).

The batch request body uses snake_case (process_type) — unlike the inline Guard API’s processType (camelCase).

Response — 202 Accepted

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

Keep the job_id for polling. When things are validated — at intake, only authentication, the Kill Switch, process_type, and the allowed scopes are validated synchronously (on failure, no job is created — the request is rejected immediately). The source’s existence, size, and format are checked at processing time; problems there finalize the job as FAILED. See Batch errors. Retries and duplicates — there is no idempotency token. Re-sending the same request creates a separate job each time. A lost response can lead to a duplicate submission, but the output for the same input and policy is written atomically under the same name, so tgt ends up in the same final state. If you’ve lost an accepted job’s job_id, recover it with the source-address search below.

Job status API

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

Response — 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": "ssn:_us_social_security_number", "action": "MASK", "confidence": 1.0, "mask_word": "SSN_1", "alert_message": "social security number detected" }
      ]
    }
  ],
  "error": null,
  "created_at": "2026-07-23T09:00:00.000Z",
  "completed_at": "2026-07-23T09:00:41.000Z"
}

Field	Description
`status`	One of the four job states — `PENDING` / `PROCESSING` / `COMPLETED` / `FAILED`. See the batch overview.
`action`	The verdict when `COMPLETED` (`PASS` / `MASK` / `BLOCK`); otherwise `null`. See Actions.
`tgt_s3_url`	The confirmed address of the result file actually written (including the file name when you requested a folder). `null` if no file was written.
`results`	Per-policy detections (which policies fired, detected items, mask tokens, confidence) — the same result structure as the Guard API response, but never the output content itself (the content lives only in the bucket).
`error`	The reason when `FAILED` (`code` / `message` / `details`). See Batch errors.
`created_at` / `completed_at`	Intake time / finalization time.

A job can be queried only with an API key from the project that created it.
While a Kill Switch is active, both job creation and status queries are rejected.
Job-record retention follows operational policy; for past jobs, the place to look is Opticon — each job’s trace records the intake details (src_s3_url · tgt_s3_url · process_type · job_id) together with the verdict and any error.

Search jobs by source address

If you’ve lost a job_id, recover it by searching recent jobs by source address:

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

Returns the recent jobs submitted for that source object, newest first (up to 20 by default, results omitted — get the details from the single-job query with the 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" } ] }

The polling pattern

Create the job

Call POST /v1/guard/s3 and keep the job_id from the response.

Poll

Call GET /v1/guard/s3/jobs/{job_id} periodically. While status is PENDING / PROCESSING, keep waiting.

Branch on the final state

On COMPLETED, branch on action (PASS / MASK: collect the output from tgt_s3_url; BLOCK: no output — the reason is in results). On FAILED, branch on 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", ... }

​Job creation API

​Job status API

​Search jobs by source address

​The polling pattern

Job creation API

Job status API

Search jobs by source address

The polling pattern