Skip to main content

​
Pagination

All list endpoints support cursor-based pagination using two parameters:
ParameterTypeDescription
limitintegerMax items per page (default: 10, max: 100)
afterstringCursor for the next page — pass the next_cursor value from the previous response
Paginated responses include a pagination object with a next_cursor field: 
{
  "contracts": [ ... ],
  "pagination": {
    "limit": 10,
    "has_more": true,
    "next_cursor": "con_a1b2c3d4"
  }
}
When has_more is true, pass the next_cursor value as the after parameter to fetch the next page. When there are no more pages, next_cursor is null. Example flow:
  1. GET /v1/transactions?limit=10 — returns records 1–10, "next_cursor": "txn_abc123"
  2. GET /v1/transactions?limit=10&after=txn_abc123 — returns records 11–20, "next_cursor": "txn_xyz789"
  3. GET /v1/transactions?limit=10&after=txn_xyz789 — returns records 21–25, "has_more": false, "next_cursor": null
The collection key in the response mirrors the resource name (e.g., "contracts", "transactions", "nominations", "customers").

​
Timestamps

All timestamps are ISO 8601 in UTC: 
2025-07-15T14:30:00Z

​
Delivery Periods

Energy delivery uses the standard PTU (Programme Time Unit) convention with 15-minute intervals: 
{
  "delivery_date": "2025-07-15",
  "period_from": "2025-07-15T14:00:00Z",
  "period_to": "2025-07-15T14:15:00Z"
}
Each delivery day typically has 96 quarter-hour slots (numbered 1–96). On DST transition days, this may be 92 or 100 slots. Slot-based filtering is available on transaction and nomination endpoints via the slot_number_from and slot_number_to parameters.

​
Error Responses

All errors follow RFC 9457 — Problem Details for HTTP APIs and are returned with Content-Type: application/problem+json: 
{
  "type": "https://brp.otark.team/errors/balance_group_tso_not_enabled",
  "title": "Balance Group TSO Not Enabled",
  "status": 400,
  "detail": "The requested TSO is not enabled for this balance group.",
  "instance": "/v1/customers/cust_r8s9t0u1"
}
Validation errors include a field-level errors array: 
{
  "type": "https://brp.otark.team/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "instance": "/v1/customers/cust_r8s9t0u1",
  "errors": [
    {
      "field": "balance_group.tso",
      "code": "invalid_enum_value",
      "message": "Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ'"
    }
  ]
}
Field-level error codes: unknown_field, read_only_field, required, invalid_type, invalid_enum_value, invalid_format, invalid_literal, value_too_small, value_too_large, validation_failed. Standard HTTP status codes are used:
CodeDescription
400Bad request — validation error or business rule violation
401Unauthorized — missing or invalid API key
403Forbidden — API key lacks required scopes
404Not found — resource does not exist or caller has no access
409Conflict — operation cannot be completed in the current state
429Too many requests — rate limit exceeded
500Internal server error

​
Rate Limiting

API requests are rate-limited to 300 requests per 60-second window. Every response includes the following headers:
HeaderExampleDescription
x-ratelimit-limit300Maximum requests allowed per window
x-ratelimit-remaining299Remaining requests in the current window
x-ratelimit-reset60Seconds until the window resets
When the limit is exceeded, the API returns 429 Too Many Requests.