up

docs/09_API_CLI_REFERENCE.md

@@ -158,6 +158,90 @@ Client then generates SBOM **only** for the `missing` layers and re‑posts `/sc
 | `POST` | `/policy/validate` | Lint only; returns 400 on error      |
 | `GET`  | `/policy/history`  | Paginated change log (audit trail)   |
 
+### 2.4 Scanner – Queue a Scan Job *(SP9 milestone)*
+
+```
+POST /api/v1/scans
+Authorization: Bearer <token with scanner.scans.enqueue>
+Content-Type: application/json
+```
+
+```json
+{
+  "image": {
+    "reference": "registry.example.com/acme/app:1.2.3"
+  },
+  "force": false,
+  "clientRequestId": "ci-build-1845",
+  "metadata": {
+    "pipeline": "github",
+    "trigger": "pull-request"
+  }
+}
+```
+
+| Field               | Required | Notes                                                                                           |
+| ------------------- | -------- | ------------------------------------------------------------------------------------------------ |
+| `image.reference`   | no\*     | Full repo/tag (`registry/repo:tag`). Provide **either** `reference` or `digest` (sha256:…).      |
+| `image.digest`      | no\*     | OCI digest (e.g. `sha256:…`).                                                                   |
+| `force`             | no       | `true` forces a re-run even if an identical scan (`scanId`) already exists. Default **false**.  |
+| `clientRequestId`   | no       | Free-form string surfaced in audit logs.                                                        |
+| `metadata`          | no       | Optional string map stored with the job and surfaced in observability feeds.                    |
+
+\* At least one of `image.reference` or `image.digest` must be supplied.
+
+**Response 202** – job accepted (idempotent):
+
+```http
+HTTP/1.1 202 Accepted
+Location: /api/v1/scans/2f6c17f9b3f548e2a28b9c412f4d63f8
+```
+
+```json
+{
+  "scanId": "2f6c17f9b3f548e2a28b9c412f4d63f8",
+  "status": "Pending",
+  "location": "/api/v1/scans/2f6c17f9b3f548e2a28b9c412f4d63f8",
+  "created": true
+}
+```
+
+- `scanId` is deterministic – resubmitting an identical payload returns the same identifier with `"created": false`.
+- API is cancellation-aware; aborting the HTTP request cancels the submission attempt.
+- Required scope: **`scanner.scans.enqueue`**.
+
+**Response 400** – validation problem (`Content-Type: application/problem+json`) when both `image.reference` and `image.digest` are blank.
+
+### 2.5 Scanner – Fetch Scan Status
+
+```
+GET /api/v1/scans/{scanId}
+Authorization: Bearer <token with scanner.scans.read>
+Accept: application/json
+```
+
+**Response 200**:
+
+```json
+{
+  "scanId": "2f6c17f9b3f548e2a28b9c412f4d63f8",
+  "status": "Pending",
+  "image": {
+    "reference": "registry.example.com/acme/app:1.2.3",
+    "digest": null
+  },
+  "createdAt": "2025-10-18T20:15:12.482Z",
+  "updatedAt": "2025-10-18T20:15:12.482Z",
+  "failureReason": null
+}
+```
+
+Statuses: `Pending`, `Running`, `Succeeded`, `Failed`, `Cancelled`.
+
+**Response 404** – `application/problem+json` payload with type `https://stellaops.org/problems/not-found` when the scan identifier is unknown.
+
+> **Tip** – poll `Location` from the submission call until `status` transitions away from `Pending`/`Running`.
+
 ```yaml
 # Example import payload (YAML)
 version: "1.0"
@@ -181,6 +265,23 @@ Validation errors come back as:
 }
 ```
 
+```json
+# Preview response excerpt
+{
+  "success": true,
+  "policyDigest": "9c5e...",
+  "revisionId": "rev-12",
+  "changed": 1,
+  "diffs": [
+    {
+      "baseline": {"findingId": "finding-1", "status": "pass"},
+      "projected": {"findingId": "finding-1", "status": "blocked", "ruleName": "Block Critical"},
+      "changed": true
+    }
+  ]
+}
+```
+
 ---
 
 ### 2.4 Attestation (Planned – Q1‑2026)