# Risk API

> Based on `CONTRACT-RISK-SCORING-002` (2025-12-05). Examples are frozen in `docs/risk/samples/api/risk-api-samples.json` with hashes in `SHA256SUMS`. Keep ETags and error payloads deterministic.

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

## Endpoints (v1)
- `POST /api/v1/risk/jobs` — submit scoring job (body: job request); returns `202` with `job_id` and `status` (`queued`). Sample: `risk-api-samples.json#submit_job_request`.
- `GET /api/v1/risk/jobs/{job_id}` — job status + results array (sample: `get_job_status`).
- `GET /api/v1/risk/explain/{job_id}` — explainability payload (sample references `../explain/explain-trace.json`).
- `GET /api/v1/risk/profiles` — list profiles (tenant-filtered); include `profile_hash`, `version`, `etag`.
- `POST /api/v1/risk/profiles` — create/update profile with DSSE/attestation metadata; returns `201` with `etag`.
- `POST /api/v1/risk/simulations` — dry-run scoring with fixtures; returns explain + contributions without persisting results.
- `GET /api/v1/risk/export/{job_id}` — export bundle (JSON + CSV + manifest) for auditors.
- Feature flags: `risk.jobs`, `risk.explain`, `risk.simulations`, `risk.export` (toggle exposure per tenant).

## Auth & Tenancy
- Required headers: `X-Stella-Tenant`, `Authorization: Bearer <token>`, optional `X-Stella-Scope` for imposed rule reminders.
- Imposed rule reminder must be present in responses where tenant-bound resources are returned.

## Error Model
- Envelope: `code`, `message`, `correlation_id`, `severity`, `remediation`.
- Rate-limit headers: `Retry-After`, `X-RateLimit-Remaining` (document values in SDKs).

## Determinism & Offline Posture
- Samples: `docs/risk/samples/api/risk-api-samples.json` (hashes in `SHA256SUMS`); explain sample reused via relative reference.
- No live dependencies; use frozen fixtures. Keep ordering of fields stable in docs and samples.

## Open Items
- Add ETag examples for profile list/create once generators emit them.
- Populate error/code catalog and SDK targets once available.
- Align feature flag names with deployment config.

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