Fraud API¶
Documentation status
Last verified: 26 Sep 2026. Endpoint inventory: generated endpoint map. Status labels: status vocabulary. Confirm deployed bases with MasteryHive.
Mental model¶
Stream services expose HTTP predict APIs that partners (or the platform on their behalf) call with JWT + tenant header. Report completion is delivered to your backend via the report callback. Baseline/report pipeline HTTP endpoints are platform-operated — not a general partner API.
Partner-facing scoring routes¶
Canonical path list (generated from OpenAPI): Fraud partner endpoint map.
| Service | Path | Required headers |
|---|---|---|
| ML prediction | POST /call-and-predict |
Authorization: ApiKey <jwt>, x-tenant-id |
| Rule engine | POST /rule_based_engine |
same |
| Case management rule engine | POST /case_management_rule_engine |
same |
Mint JWTs with iss=software-service, aud=ai-service — Auth tutorial.
Static schema: Fraud OpenAPI. Quickstart: Fraud quickstart.
Report → dashboard¶
Provisional policy
Dashboard decision / escalations come from fraud-decision-v1 (provisional / non-production). See Fraud output contract.
Score / tier handoff
ML scoring and report compose currently use different tier labels and score boundaries. Some predictions never become reports until owners align policy. See output contract — Risk tier mapping.
Reading responses: HTTP 200 is not always success¶
| Route | What a 200 means | What to inspect |
|---|---|---|
POST /call-and-predict |
Scoring finished. It does not guarantee that a dashboard report will follow: Critical Risk results and scores just above 0.66 or 0.30 are currently rejected by the report step (details) |
prediction.predicted_level (string), prediction.probability_score (float, 0 to 1). Reconcile scored transactions against received reports by transactionId |
POST /rule_based_engine, POST /case_management_rule_engine |
Rules were evaluated | prediction.flagged (bool: true means at least one rule matched), prediction.score (float, 0 to 1). A rule-engine error returns 500, not a 200 with an error field |
Other statuses: 401 means a missing or invalid token; 422 means the body does not match the schema or x-tenant-id is missing; 400 (rule service) or 500 (ML service, and rule-engine internal errors) means a processing error. See the error catalogue.
Platform-operated baseline trigger¶
POST /batch_check on the checks service starts baseline computation. It is operated by the platform, not called by partners. It publishes one message per customer to the messaging topic named in the request field topic. If topic is omitted, the service uses a hard-coded development-default topic name (it does not derive the topic from the current environment). Always send the topic MasteryHive specifies for your environment. A 200 can still report status: partial_failure with failed_ids, or count: 0 when the tenant has no customers.
Cold start¶
Customers with insufficient history may skip behavioural profile persistence. Prefer the rule service for those customers. Thresholds are environment-specific — values are issued with your programme setup (base URLs / access).
Contract errors¶
Mixed ML+rule identity keys → AMBIGUOUS_PREDICTION_CONTRACT. Score/tier conflicts → ML_SCORE_TIER_CONFLICT. Do not retry the same invalid body — error catalogue.