REST API

The Gravitas REST API is resource-oriented and predictable: resources like trades, positions, valuations, and reference data are addressed by URL, manipulated with standard HTTP verbs, and exchanged as JSON. Endpoints are versioned (for example /v1) so integrations stay stable across platform changes.

httpGET  /v1/positions?book=GAS-EU&asOf=2026-07-01   # list positions as-of a date
POST /v1/trades                                  # book a new trade
GET  /v1/valuations/{tradeId}                    # value a single trade
GET  /v1/curves/{curveId}?asOf=2026-07-01        # a versioned forward curve

Booking a trade is a POST with a JSON body; the response echoes the created resource with its server-assigned identifier and version. Everything the UI can do is available through the same call.

httpPOST /v1/trades HTTP/1.1
Host: api.gravitasetrm.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "book": "GAS-EU",
  "instrument": "TTF-MONTH",
  "buySell": "BUY",
  "quantity": 50000,
  "unit": "MWh",
  "price": 32.15,
  "deliveryPeriod": "2026-08",
  "counterparty": "ACME-ENERGY"
}

jsonHTTP/1.1 201 Created
Location: /v1/trades/TR-000184213
Content-Type: application/json

{
  "tradeId": "TR-000184213",
  "version": 1,
  "status": "captured",
  "book": "GAS-EU",
  "instrument": "TTF-MONTH",
  "buySell": "BUY",
  "quantity": 50000,
  "price": 32.15,
  "capturedAt": "2026-07-08T09:14:22Z"
}

Errors return standard HTTP status codes with a structured body describing the problem, so clients can handle them programmatically rather than parsing prose. A validation failure, for example, names the field and the reason.

jsonHTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "validation_failed",
  "message": "One or more fields are invalid.",
  "details": [
    { "field": "counterparty", "reason": "not_onboarded" },
    { "field": "deliveryPeriod", "reason": "outside_trading_calendar" }
  ]
}

Collection endpoints support filtering (by book, commodity, date) and cursor-based pagination, so large result sets are retrieved efficiently and deterministically. Follow the next cursor until it is null.

httpGET /v1/trades?book=GAS-EU&limit=100

{
  "data": [ /* up to 100 trades */ ],
  "paging": { "next": "eyJvZmZzZXQiOjEwMH0", "hasMore": true }
}

# fetch the next page:
GET /v1/trades?book=GAS-EU&limit=100&cursor=eyJvZmZzZXQiOjEwMH0

Because reference and market data are versioned bitemporally, many endpoints accept an asOf parameter to reproduce historically accurate results, the same mechanism behind the analytical marts. Ask for positions as they stood at a past close, valued on the curve that was live then, and the answer is exact rather than approximate.

The asOf parameter is what makes a REST result reproducible: the same call with the same asOf returns the same answer forever, because it resolves every input to its version on that date.