Skip to main content

API Guide

The OwlSure WhatIf API is a REST API that powers the WhatIf Scenario Builder. It manages the full lifecycle of what-if analysis, from authentication and user administration through scenario execution, rate table modifications, KPI profiling, and results retrieval.

All endpoints return JSON and require a Bearer JWT token (except the auth endpoints used to obtain one).

Base URL: https://<your-environment>/api

Authentication​

All protected endpoints require the following header:

Authorization: Bearer <access_token>

Tokens are obtained via the Login endpoint and refreshed via Refresh Token.

API Areas​

AreaDescription
AuthenticationLogin, logout, token refresh, password management
AdministrationUsers, environments, settings
ScenariosCreate, run, and manage what-if scenarios
Books of BusinessManage policy books and filters
Rate TablesBrowse rate tables and save modifications
KPI ProfilesDefine and manage KPI dimension mappings
Report ConfigsConfigure analysis report structures
Dashboard & ResultsRetrieve scenario summaries and analytics
Fabric / Power BIToken acquisition and capacity management

Authentication Endpoints​

These endpoints do not require a Bearer token (except Change Password and Logout).

Login​

POST /api/auth/login

Authenticates a user by username or email and password. Returns an access token and a refresh token.

→ Login reference

Refresh Token​

POST /api/auth/refresh

Issues a new access token from a valid refresh token. The old refresh token is revoked on use (rotation). Call this before the access token expires to maintain a session without re-authenticating.

→ Refresh Token reference

Logout​

POST /api/auth/logout/{id}

Records a logout event for the specified user and invalidates the session server-side.

→ Logout reference

Forgot Password​

POST /api/auth/forgot-password

Initiates a password reset by sending a reset link to the user's registered email. Always returns 200 regardless of whether the email exists, to prevent user enumeration.

→ Forgot Password reference

Reset Password​

POST /api/auth/reset-password

Resets a user's password using a valid, unexpired reset token received via email.

→ Reset Password reference

Change Password​

POST /api/auth/change-password/{id}

Changes the password for an authenticated user after verifying the current password.

→ Change Password reference

Administration​

Admin endpoints manage users, environments, and application-wide settings. These are typically called by administrator roles only.

Users​

MethodEndpointDescription
GET/api/admin/usersList all users
POST/api/admin/usersCreate a user
GET/api/admin/users/{id}Get a user by ID
PUT/api/admin/users/{id}Update a user
DELETE/api/admin/users/{id}Delete a user

Environments​

Environments represent rating engine connections. Each scenario runs against a specific environment.

MethodEndpointDescription
GET/api/admin/environmentsList all environments
POST/api/admin/environmentsCreate an environment
GET/api/admin/environments/{id}Get an environment
PUT/api/admin/environments/{id}Update an environment
DELETE/api/admin/environments/{id}Delete an environment
POST/api/admin/environments/health-checkHealth Check (TCP)
POST/api/admin/environments/health-check-v2Health Check (HTTP)

Use the health check endpoints to verify connectivity to a rating engine before running scenarios. The TCP check tests raw port connectivity; the HTTP check calls the engine's /health endpoint.

Settings​

MethodEndpointDescription
GET/api/admin/settingsGet all settings
PUT/api/admin/settingsSave settings

Settings control application-wide configuration such as currency.

Scenarios​

Scenarios are the core resource of the WhatIf platform. A scenario defines a set of rate table modifications applied to a book of business, which the rating engine then executes to produce comparison results.

Lifecycle​

Create → Validate Name → Run (status: Pending → Running → Completed/Failed) → View Results

Endpoints​

MethodEndpointDescription
GET/api/ScenariosList scenarios, filter by user or book
POST/api/ScenariosCreate a scenario
GET/api/Scenarios/{id}Get a scenario
PUT/api/Scenarios/{id}Update a scenario
DELETE/api/Scenarios/{id}Delete a scenario
GET/api/Scenarios/validate-nameValidate scenario name
GET/api/Scenarios/{id}/statusGet scenario status
PUT/api/Scenarios/{id}/statusUpdate scenario status
GET/api/Scenarios/{id}/failed-policiesGet failed policies

Checking Execution Status​

Poll GET /api/Scenarios/{id}/status after triggering a run. Possible status values include Pending, Running, Completed, and Failed.

Failed Policies​

If a scenario completes with errors, GET /api/Scenarios/{id}/failed-policies returns the list of policies that failed rating during the last execution. Use this to diagnose data or configuration issues.

Books of Business​

A book of business is a filtered snapshot of policies used as the input data for a scenario.

MethodEndpointDescription
GET/api/BooksList books, filter by LOB, owner, or state
POST/api/BooksCreate a book
DELETE/api/Books/{id}Delete a book
POST/api/book-filtersGet book filters

Book Filters​

POST /api/book-filters returns the distinct policy field values (e.g. states, coverage types) available for a given line of business and effective date range. Use this to populate filter dropdowns in the UI before creating a book.

Rate Tables​

Rate tables define the pricing factors used by the rating engine. The WhatIf platform lets you apply modifications to these tables per scenario without changing the underlying production data.

MethodEndpointDescription
GET/api/RateTablesList all rate tables
GET/api/RateTables/modifications/{scenarioId}Get modifications for a scenario
POST/api/RateTables/modificationsSave modifications for a scenario

How Modifications Work​

Modifications are stored per scenario. When the rating engine executes a scenario, it applies the saved modifications on top of the base rate tables. Saving new modifications replaces the previous set for that scenario.

KPI Profiles​

KPI profiles define which dimensions (risk attributes) are used to aggregate and display results in reports. Each profile maps report types to specific data dimensions.

MethodEndpointDescription
GET/api/KpiProfilesList all KPI profiles
POST/api/KpiProfilesCreate a KPI profile
GET/api/KpiProfiles/by-config/{configId}Get profiles by report config
PUT/api/KpiProfiles/{id}Update a KPI profile
DELETE/api/KpiProfiles/{id}Delete a KPI profile

Report Configs​

Report configurations define the structure of analysis reports, which risks, coverages, and segments are included. A report config is linked to a scenario and drives how results are presented.

MethodEndpointDescription
GET/api/ReportConfigsList report configs
POST/api/ReportConfigsCreate a report config
GET/api/ReportConfigs/{id}Get a report config
PUT/api/ReportConfigs/{id}Update a report config
DELETE/api/ReportConfigs/{id}Delete a report config

Dashboard & Results​

Dashboard Summary​

GET /api/Dashboard/latest-scenario-summary

Returns the latest scenario run summary cards for a user's dashboard, including premium metrics, execution status, and comparison highlights.

→ Get Dashboard Summary reference

User Scenarios​

GET /api/Dashboard/user-scenarios

Returns the scenarios associated with a specific user, used to populate the dashboard scenario list.

→ Get User Scenarios reference

Warm Up​

POST /api/Dashboard/warm-up

Opens Lakehouse connections to warm up the connection pool. Called fire-and-forget after login so subsequent dashboard queries are fast. No response body is expected.

→ Warm Up reference

Fabric / Power BI​

These endpoints manage the integration with Microsoft Fabric and Power BI for embedded analytics.

Get Fabric Token​

POST /api/fabric/token

Acquires an OAuth2 client-credentials token scoped to the Fabric/Power BI API. The token is used client-side to embed Power BI reports.

→ Get Fabric Token reference

Ensure Capacities​

POST /api/fabric/ensure-capacities

Checks each resolved Fabric capacity and resumes any that are in a Paused state. Call this before rendering embedded reports to avoid cold-start delays.

→ Ensure Capacities reference

Error Responses​

All endpoints return standard HTTP status codes. Error responses follow the ProblemDetails schema (RFC 7807):

{
  "type": "https://tools.ietf.org/html/rfc7807",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found."
}
StatusMeaning
200Success
201Created
204No Content (success with no body)
400Bad Request, invalid input
401Unauthorized, missing or invalid token
404Not Found, resource does not exist
409Conflict, duplicate resource
500Internal Server Error