# Risk API

Purpose
- Expose risk jobs, profiles, simulations, explainability, and exports.

Endpoints (v1)
- POST /api/v1/risk/jobs: submit scoring job.
- GET /api/v1/risk/jobs/{job_id}: job status and results.
- GET /api/v1/risk/explain/{job_id}: explainability payload.
- GET /api/v1/risk/profiles: list profiles with hashes and versions.
- POST /api/v1/risk/profiles: create or update profiles with DSSE metadata.
- POST /api/v1/risk/simulations: dry-run scoring with fixtures.
- GET /api/v1/risk/export/{job_id}: export bundle for audit.

Auth and tenancy
- Headers: X-Stella-Tenant, Authorization Bearer token.
- Optional X-Stella-Scope for imposed rule reminders.

Error model
- Envelope: code, message, correlation_id, severity, remediation.
- Rate-limit headers: Retry-After, X-RateLimit-Remaining.
- ETag headers for profile and explain responses.

Feature flags
- risk.jobs, risk.explain, risk.simulations, risk.export.

Determinism and offline
- Samples in docs/risk/samples/api/ with SHA256SUMS.
- Stable field ordering and UTC timestamps.

Related references
- risk/overview.md
- risk/profiles.md
- risk/factors.md
- risk/formulas.md
- risk/explainability.md