BRP API: Conventions

Pagination

All list endpoints support cursor-based pagination using two parameters:

Parameter	Type	Description
`limit`	integer	Max items per page (default: 10, max: 100)
`after`	string	Cursor 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:

GET /v1/transactions?limit=10 — returns records 1–10, "next_cursor": "txn_abc123"
GET /v1/transactions?limit=10&after=txn_abc123 — returns records 11–20, "next_cursor": "txn_xyz789"
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:

Code	Description
`400`	Bad request — validation error or business rule violation
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — API key lacks required scopes
`404`	Not found — resource does not exist or caller has no access
`409`	Conflict — operation cannot be completed in the current state
`429`	Too many requests — rate limit exceeded
`500`	Internal server error

Rate Limiting

API requests are rate-limited to 300 requests per 60-second window. Every response includes the following headers:

Header	Example	Description
`x-ratelimit-limit`	`300`	Maximum requests allowed per window
`x-ratelimit-remaining`	`299`	Remaining requests in the current window
`x-ratelimit-reset`	`60`	Seconds until the window resets

When the limit is exceeded, the API returns 429 Too Many Requests.

BRP Connect

SFTP

Webhooks

BRP API

Contracts

Transactions

Nominations

Customers

BRP API: Conventions

Timestamps

Delivery Periods

Error Responses

Rate Limiting

​Pagination

​Timestamps

​Delivery Periods

​Error Responses

​Rate Limiting

Pagination

Timestamps

Delivery Periods

Error Responses

Rate Limiting