API conventions¶
Shared HTTP/JSON conventions across MasteryHive partner APIs. Product pages override only where stated.
JSON¶
| Convention | Expectation |
|---|---|
| Content-Type | application/json on POST bodies |
| Field naming | Mix of camelCase (dashboard/report payloads) and snake_case (many recon/Fraud internal-facing fields). Do not rename fields to “normalize” — match the schema for that route |
| Nulls | Optional fields may be omitted or null per OpenAPI; do not send empty strings where UUIDs are required |
| Extra fields | May be ignored or rejected depending on service — prefer exact schemas |
Timestamps¶
| Pattern | Where used |
|---|---|
YYYY-MM-DD + HH:MM:SS (separate fields) |
Fraud transaction date / time |
YYYY-MM-DD HH:MM:SS string |
Some Fraud prediction timestamps |
| ISO-8601 | Prefer when a schema says date-time; recon periods use explicit date fields on requests |
Always send the format the route schema shows. Do not invent timezones unless the field documents one.
Identifiers¶
| Id | Product | Notes |
|---|---|---|
transaction.id / transaction_id |
Fraud | UUID string preferred |
userId / user.user_id |
KYC / Fraud | Stable per end customer |
session_id |
Reconciliation | Caller-minted per run |
resolution_request_id |
Recon exceptions | Idempotency key |
x-tenant-id / tenant_id / partner_id |
See multi-tenancy | Scope — not proof of auth alone |
Enums¶
Send exact enum strings from OpenAPI / contracts (case-sensitive). Invalid enums → 422 (or documented business error). Examples: Fraud decision (approve|pend|block); recon decision (approved|rejected|…).
Headers¶
| Header | Products | Required? |
|---|---|---|
Authorization: ApiKey <jwt> |
Fraud scoring | Yes on scoring routes |
x-tenant-id |
Fraud scoring | Yes (missing → 422) |
Content-Type: application/json |
All POST JSON | Yes |
| Partner correlation header | All | Not a guaranteed platform standard — use product ids |
HTTP semantics¶
| Status | Meaning (typical) |
|---|---|
| 200 | Success with body |
| 202 | Accepted for async work (when documented) |
| 400 | Handler/business rejection |
| 401 | Auth failure (Fraud JWT) |
| 409 | Conflict (e.g. recon period lock / active session) |
| 422 | Validation / missing required header or field |
| 5xx | Server/dependency failure — see retry |
Pagination¶
No universal partner pagination convention across products. If a route paginates, it will say so in that service’s OpenAPI. Do not invent page/cursor parameters.
Correlation¶
Log and support with: transaction_id, session_id, tenant_id / x-tenant-id, partner_id, userId, resolution_request_id. See errors / retries.
Compatibility¶
- Prefer additive, non-breaking field additions.
- Breaking changes require notice per versioning decision proposal (no org-wide policy yet).
- Track changes in the API changelog.
- When static OpenAPI and live
/openapi.jsondisagree, prefer the live revision you are calling, then file a docs drift issue.