# Risk API (draft outline)

> Draft scaffold; populate once 67-001 explainability outputs and API publishing workflow are available. Keep examples deterministic; include ETags and error payloads when provided.

## Purpose
- Document risk-related endpoints for profile management, simulation, scoring results, explainability retrieval, and export.

## Scope & Audience
- Audience: API consumers, SDK authors, platform integrators.
- In scope: endpoint list, methods, request/response schemas, auth/tenancy headers, rate limits, feature flags, error model.
- Out of scope: console/UI workflow details (see `explainability.md`).

## Endpoint Outline (placeholders)
- `GET /api/risk/profiles` — list profiles (filters by tenant, status).
- `POST /api/risk/profiles` — create/update; includes DSSE/attestation fields.
- `POST /api/risk/simulations` — run simulation with fixture set; supports dry-run.
- `GET /api/risk/results/{id}` — retrieve scored results + explainability link.
- `GET /api/risk/explain/{id}` — fetch explainability payload.
- `GET /api/risk/export/{id}` — export bundle (JSON/CSV) with hash manifest.
- Feature flags: `<pending>`

## Auth & Tenancy
- Required headers: `X-Stella-Tenant`, `X-Stella-Scope`, auth tokens (PAT/OAuth2) — confirm once schema published.
- Imposed rule reminder must be present on every page.

## Error Model (pending)
- Standard error envelope: code, message, correlation_id, severity, remediation.
- Rate limit headers and retry guidance.

## Determinism & Offline Posture
- Provide sample requests/responses under `docs/risk/samples/`; include SHA256 table.
- No live dependencies; use frozen fixtures.

## Open Items
- API publishing workflow outputs
- Final endpoint list and field names
- Error/code catalog
- SDK generator targets and examples

## References
- `docs/risk/overview.md`
- `docs/risk/profiles.md`
- `docs/risk/factors.md`
- `docs/risk/formulas.md`
- `docs/risk/explainability.md`