# 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`).