up

docs/api/vuln.md

@@ -0,0 +1,29 @@
+# Vulnerability API (placeholder)
+
+Status: Draft (2025-11-26) — awaiting Vuln Explorer v1 surface. This doc reserves the path and headers to align with upcoming releases.
+
+## Base URL
+`<gateway>/api/vuln` (subject to final routing via API gateway).
+
+## Common headers
+- `X-Stella-Tenant` (required)
+- `Authorization: Bearer <token>`
+- `X-Stella-Scopes`: expect `vuln:read` (TBD) and/or `graph:read` when graph-backed queries are invoked.
+- `Content-Type: application/json`
+
+## Planned endpoints (subject to change)
+- `POST /vuln/search` — filter vulnerabilities by component (purl/digest), advisory id, status, exploitability (OpenVEX).
+- `POST /vuln/impact` — compute impacted assets using Graph overlays; may proxy to Graph API internally.
+- `GET /vuln/{id}` — details with references, VEX status, nearest safe version.
+- `GET /vuln/{id}/evidence` — raw evidence (SBOM snapshot refs, observations).
+- `GET /vuln/kev` — Known Exploited Vulnerabilities view (cached).
+
+## Error envelope
+Follows Graph/Platform standard:
+```json
+{ "error": "VULN_VALIDATION_FAILED", "message": "details", "requestId": "optional" }
+```
+
+## Notes
+- This placeholder will be updated once Vuln Explorer API is finalized. Keep gateway clients tolerant to minor shape changes until status flips to READY.
+- For current graph-backed queries, use `/graph/search` or `/graph/query` (see `docs/api/graph.md`).