Skip to content

Conventions

These apply across the whole API. Learn them once and every operation reads the same way.

Base URL & versioning

Every path is under /api/v1. The version lives in the path, not a header. The retail (customer) surface is a sub-tree at /api/v1/retail, and the AI agent gateway is at /api/v1/mcp.

https://api.cortexbanking.com/api/v1/…

Hosts are a deployment concern

The generated contract lists only a localhost development server. Production hosts (such as api.cortexbanking.com) come from your deployment, not from openapi.json.

Money

Money is always an object, never a bare number, an amount paired with its currency:

{ "amount": 250.00, "currency": "USD" }
  • amount is a decimal number backed by arbitrary-precision decimal on the server (a BigDecimal). Parse and hold it as an exact decimal, never as a binary float, or you will lose cents.
  • currency is an ISO 4217 alphabetic code.
  • The two always travel together. There is no implicit "default currency".

For clients in a language with a JSON float default

Configure your JSON library to read numbers as arbitrary-precision decimals (for example BigDecimal in Java, Decimal in Python, decimal.js in JavaScript) for money fields, so round-tripping is exact.

Dates & times

  • Business and value dates are calendar dates in ISO-8601 YYYY-MM-DD.
  • Timestamps are ISO-8601 date-times.

Cortex distinguishes three notions of "when", and it is worth keeping them straight:

Field Meaning
businessDate The logical accounting date the institution is operating on (rolled at start-of-day).
valueDate When a movement is economically effective.
postedAt The wall-clock time the record was written.

Filtering

List endpoints filter by domain-specific query parameters rather than a generic scheme. The common ones:

Parameter Use
from / to A date range.
asOf A point-in-time (balances as at a date).
status Filter by lifecycle status.
currency Filter by currency.
businessDate Records for a specific business date.

There is no platform-wide pagination

The REST surface does not define a uniform page / size / offset / cursor convention. List endpoints generally return the full or recent set for the filter you give. Constrain results with from / to / status / currency rather than expecting a page cursor. Design your client to pull bounded ranges.