# Vuln Explorer API (Md.XI draft)

> Status: DRAFT — depends on GRAP0101 contract and console/CLI payload samples. Publish only after schemas freeze and hashes recorded.

## Scope
- Describe public Explorer API endpoints, query schema, grouping, errors, and rate limits.
- Include deterministic examples with hashed request/response payloads.

## Prerequisites
- GRAP0101 contract (final field names, query params).
- Payload samples from console/CLI asset drop (due 2025-12-09).
- Current architecture reference: `docs/modules/vuln-explorer/architecture.md`.

## Endpoints (to finalize)
- `GET /v1/findings` — list with filters (tenant, advisory, status, reachability, VEX, priority, owner); pagination & sorting.
- `GET /v1/findings/{id}` — detail (policy context, explain trace, attachments, history).
- `POST /v1/findings/{id}/actions` — create action (assign, comment, status change, remediation, ticket link) with DSSE optional.
- `POST /v1/reports` — create report; returns manifest + location.
- `GET /v1/reports/{id}` — fetch report metadata/download.
- `GET /v1/exports/offline` — download deterministic bundle (JSONL + manifests + signatures).
- `POST /v1/vex-decisions` / `PATCH /v1/vex-decisions/{id}` / `GET /v1/vex-decisions` — decision lifecycle (aligns with `vex-decision.schema.json`).

## Query Schema (draft)
- Filters: `tenant`, `advisoryId`, `vexStatus`, `reachability`, `priority`, `status`, `owner`, `artifactId`, `sbomComponentId`.
- Pagination: `page`, `pageSize` (cap tbd per GRAP0101).
- Sorting: `sort` (supports multi-field, stable order; default `priority desc, updatedAt desc`).
- Projection: `fields` allowlist to shrink payloads; defaults tbd.
- ETag/If-None-Match for cache-aware clients (confirm in GRAP0101).

## Errors & Rate Limits
- Standard error envelope (status, code, message, correlationId); attach `hint` when policy gate blocks action.
- Rate limits: per-tenant and per-service-account quotas; retry after header; offline bundles exempt.

## Determinism & Offline
- All example payloads must be fixed fixtures; record hashes in `docs/assets/vuln-explorer/SHA256SUMS`.
- Use canonical ordering for list responses; include sample `ETag` and manifest hash where relevant.

### Fixtures to Capture (when assets drop)
- `assets/vuln-explorer/api-findings-list.json` (filtered list response)
- `assets/vuln-explorer/api-finding-detail.json` (detail with history/actions)
- `assets/vuln-explorer/api-action-post.json` (action request/response)
- `assets/vuln-explorer/api-report-create.json` (report creation + manifest)
- `assets/vuln-explorer/api-vex-decision.json` (create/list payloads)

## Open Items
- Fill in finalized parameter names, limits, and error codes from GRAP0101.
- Add example requests/responses once asset drop is delivered; include hashes.
- Confirm DSSE optional flag shape for `actions` endpoint.

_Last updated: 2025-12-05 (UTC)_