REST API Reference
Sentinel exposes roughly 50 endpoints across 14 router modules. Full OpenAPI documentation is auto-generated by FastAPI at /docs. Every endpoint requires a JWT bearer token and respects role-based access control.
A selection of the most important endpoints below.
Authentication
| Endpoint | Method | Description |
|---|
/auth/login | POST | Email + password → JWT bearer token |
/auth/me | GET | Current authenticated user |
Scoring
| Endpoint | Method | Description |
|---|
/score | POST | Score a single transaction, returns score + SHAP top features |
/score/batch | POST | Score up to 1000 transactions in one request |
Analyst workflow
| Endpoint | Method | Description |
|---|
/queue | GET | Paginated fraud queue with risk and decision filters |
/transactions/{id} | GET | Full transaction detail with explanation and audit trail |
/transactions/{id}/feedback | POST | Record analyst decision (confirmed_fraud, false_positive, escalated) |
/entities/{account_id} | GET | Account profile with history and counterparties |
/investigate | GET | Multi-criteria search with stats and pagination |
/investigate/export.csv | GET | Filtered CSV export, capped at 10K rows |
Dashboard
| Endpoint | Method | Description |
|---|
/dashboard/kpis | GET | Open cases, blocked amount, throughput, average score |
/dashboard/geo/world | GET | Per-country transaction and fraud-rate aggregates |
Case management
| Endpoint | Method | Description |
|---|
/cases | GET, POST | Case list with stats, and case creation |
/cases/{id} | GET, PATCH | Full case detail; update status, priority, assignee, outcome |
/cases/{id}/notes | POST | Add analyst note to case timeline |
Watchlists and upload
| Endpoint | Method | Description |
|---|
/watchlists | GET, POST, DELETE | Blocked/trusted account management |
/upload/transactions | POST | Multipart CSV upload, hardened and audited |
/upload/audits | GET | Upload audit trail for the current tenant |
MLOps surface
| Endpoint | Method | Description |
|---|
/models | GET | All model versions for the current tenant |
/models/{id}/threshold | PATCH | Admin-only threshold update |
/drift | GET | Overall PSI, per-feature drift, score distribution |
/tuner | GET | Precomputed precision/recall/net-savings curves |
Real-time
| Endpoint | Method | Description |
|---|
/replay/start | POST | Start the streaming replay engine |
/replay/status | GET | Live replay counters (transactions_replayed, fraud_detected) |
Health
| Endpoint | Method | Description |
|---|
/health | GET | Liveness check |
/ready | GET | Readiness check (DB + model loaded) |
Design notes
JWT bearer tokens, not sessions. Stateless auth means the API scales horizontally without sticky sessions. The token carries tenant_id, user_id, and role — every protected handler validates via a FastAPI dependency before running.
Multi-tenant by construction. Every query is automatically scoped by the authenticated user's tenant. There's no endpoint that can return another tenant's data — not because of handler-level checks, but because the SQLAlchemy session is pre-filtered.
OpenAPI for free. FastAPI generates the full OpenAPI spec from Pydantic schemas and type hints. The /docs endpoint renders the interactive Swagger UI, and /redoc renders a cleaner reference style. Both are live at runtime without any manual maintenance.
Cursor-based pagination on heavy endpoints. /queue, /investigate, and /cases use cursor pagination instead of offset to handle large result sets efficiently. Offset pagination is O(n) for large offsets; cursor pagination is O(1).