git.stella-ops.org/docs/api/gateway/advisories.md

Advisory Gateway Contract (draft v0.1)

Scope: proxy Advisory surfaces through the Web gateway with tenant scoping, deterministic responses, ETag caching, and offline-friendly pagination.

Security / headers

• Authorization: Bearer <token> (or DPoP where configured)
• X-Stella-Tenant: <tenantId> (required; see docs/api/gateway/tenant-auth.md)
• X-Stella-Project: <projectId> (optional)
• X-Stella-Trace-Id: <traceId> (optional; clients SHOULD send one)
• Scopes: advisory:read

Endpoints

• GET /advisories — list advisories (tenant-scoped).
  • Query params: search, severity, sortBy, sortOrder, limit, continuationToken
  • Response: AdvisoryListResponse (see sample)
• GET /advisories/{advisoryId} — advisory detail (tenant-scoped).

Caching & pagination

• limit max: 200.
• Cursor/paging uses continuationToken (opaque string).
• ETag MUST be a stable hash over a sorted payload; clients MAY send If-None-Match.
• Recommended headers: Cache-Control: private, max-age=60, stale-if-error=300.

Determinism rules

• Ordering: items sorted by (advisoryId asc) unless sortBy is supplied; ties break by advisoryId.
• Timestamps: ISO-8601 UTC.

Samples

• docs/api/gateway/samples/advisories-list.json
• docs/api/gateway/samples/advisory-detail.json