Overview

The Revos APIs let you manage accounts, contracts, catalog services, priceable attributes, rate cards, pricing logic, payments, and wallets, submit usage for realtime rating, and read invoices (JSON and PDF) and rated transactions.

A common pattern is to model an LLM model as a service (for example gpt-4o), with priceable attributes Input_Tokens and Output_Tokens, list-price rate cards per token type, and pricing logic formulas that call Price(Input_Tokens, …). See Services.

Base URL

https://{your-tenant-host}/api/v1/external

Use your Monetize360 tenant API host — the same host used for Mbrix workflow and MObject APIs.

Authentication

All requests require a Bearer token (JWT or access key) and the tenant-wide ADMIN role. Users who are only TENANTADMIN are authenticated but receive 403 on these catalog endpoints.

Assign ADMIN to the caller in Users & Roles, then request a new token so the JWT roles claim includes ADMIN.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://YOUR_TENANT_HOST/api/v1/external/services?page=0&size=20"

Concepts

Service ──► priceable attributes (PRICEABLE) e.g. Input_Tokens, Output_Tokens
         ├──► input attributes (INPUT) e.g. Prompt_Tokens
         ├──► rate cards (list price, one per currency)
         └──► pricing logic (Price(Input_Tokens, Qty) steps)

Contract ──► contract services
                ├──► priceable attributes (copied from catalog if omitted)
                └──► rate cards (optional exception; empty = catalog fallback)

Account ──► addresses (billing AccountAddress)
Payment ──► accountId → Account
Wallet  ──► accountId → Account
Invoice ──► accountId → Account; items; stored PDF
UsageEvent ──► realtime rating ──► RatedTransaction
RatedTransaction ──► accountId → Account; dimensions

Endpoint groups

Pagination and list/GET shape

List endpoints accept page (0-based) and size. Default size is 20; the server caps size at 20 on billing lists. Reference-data lists (countries, currencies) default to 100.

Every list and GET-by-id (except nested rate cards and pricing logic) is wrapped in ApiResponse. List data is a Spring Page. Rows keep lookup UUIDs on the field and a sibling __r object with the display name. Keys are PascalCase. There are no {k,v,fv} cells and no *Obj companions.

{
  "requestId": "8f1c2a3b-4d5e-6f70-8192-a3b4c5d6e7f8",
  "success": true,
  "status": 200,
  "errors": [],
  "data": {
    "content": [
      {
        "__type__": "Contract",
        "Id": "68cc8e84-cf43-423b-888b-a76af162e2e0",
        "Name": "Test Contract A",
        "ApprovalStatus": "fe07e71d-cba4-4316-9c7c-4935c3adec34",
        "ApprovalStatus__r": { "Name": "Approved" }
      }
    ],
    "pageable": {
      "pageNumber": 0,
      "pageSize": 20,
      "sort": { "empty": true, "sorted": false, "unsorted": true },
      "offset": 0,
      "paged": true,
      "unpaged": false
    },
    "last": true,
    "totalElements": 1,
    "totalPages": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": { "empty": true, "sorted": false, "unsorted": true },
    "numberOfElements": 1,
    "empty": false
  }
}

GET-by-id uses the same PascalCase row object inside data (no content page). Extra MObject and system fields on the row are returned as PascalCase and are not omitted.

These GET records also attach nested collections under PascalCase keys. Nested items keep the camelCase write-DTO field names (id, name, currency, …):

Contract-service list rows include ExceptionPricing. Other lists stay headers only.

Create/update still return camelCase DTO bodies (no ApiResponse envelope). Nested rate-card and pricing-logic endpoints still return PageResponse / DTO bodies.

Optional q on a list endpoint does a case-insensitive contains match. The fields it searches differ per resource and are documented on each page.

Priceable attribute body

{
  "name": "Usage",
  "label": "Usage",
  "dimensionDataType": "Number",
  "isContractInput": false,
  "isMeterDimension": false,
  "isProration": null,
  "meterResetFrequency": null,
  "dimValues": [{ "label": "US", "value": "US" }]
}

name and dimensionDataType are required. Contract-service attributes may also include dimensionValText.

Composite create order

1. Persist the parent (service, or contract / contract service).
2. Persist priceable attributes.
3. Persist rate cards (resolve priceDimName to id).

On PUT, omit a nested array to leave that collection unchanged. If both priceableAttributes and rateCards are sent, existing rate cards are removed first so new attributes can be referenced.

Errors

{
  "status": 400,
  "error": "Validation Error",
  "message": "Service name is required",
  "path": "uri=/api/v1/external/services"
}