> ## Documentation Index > Fetch the complete documentation index at: https://docs.otark.com/llms.txt > Use this file to discover all available pages before exploring further. # List nominations > List nominations accessible to the authenticated BRP. Required scope: `nominations:read` ## OpenAPI ````yaml get /v1/nominations openapi: 3.0.0 info: title: Otark BRP API description: >- API for Balancing Responsible Parties (BRPs) to manage contracts, transactions, nominations, and customers on the Otark platform. version: 1.0.0 contact: {} servers: - url: https://api.otark.energy description: Production security: [] tags: - name: Contracts description: Manage energy contracts (PPA, day-ahead, etc.) - name: Transactions description: Contractual energy volumes between buyer and seller - name: Nominations description: Net saldo aggregated by balance group - name: Customers description: Manage customers assigned to the BRP paths: /v1/nominations: get: tags: - Nominations summary: List nominations description: |- List nominations accessible to the authenticated BRP. Required scope: `nominations:read` operationId: listNominations parameters: - name: status in: query description: Filter by nomination status schema: type: string enum: - pending - partial_match - match - superseded - name: eic in: query description: Filter by customer EIC code schema: type: string example: 11YWINDPARKNO--A - $ref: '#/components/parameters/DeliveryDateParam' - $ref: '#/components/parameters/DeliveryStartParam' - $ref: '#/components/parameters/DeliveryEndParam' - $ref: '#/components/parameters/SlotNumberFromParam' - $ref: '#/components/parameters/SlotNumberToParam' - name: include_slots in: query description: >- Include the `slots` array in the response (default false). When false, the slots field is omitted. schema: type: string enum: - 'true' - 'false' default: 'false' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/AfterParam' responses: '200': description: Nominations list headers: x-ratelimit-limit: $ref: '#/components/headers/X-RateLimit-Limit' x-ratelimit-remaining: $ref: '#/components/headers/X-RateLimit-Remaining' x-ratelimit-reset: $ref: '#/components/headers/X-RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/NominationList' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' security: - ApiKeyAuth: [] components: parameters: DeliveryDateParam: name: delivery_date in: query description: Filter by delivery date (shorthand for full-day range) schema: type: string format: date example: '2026-01-15' DeliveryStartParam: name: delivery_start in: query description: 'Filter: delivery start >= this value (ISO 8601)' schema: type: string format: date-time example: '2026-01-01T00:00:00Z' DeliveryEndParam: name: delivery_end in: query description: 'Filter: delivery end <= this value (ISO 8601)' schema: type: string format: date-time example: '2026-03-31T23:45:00Z' SlotNumberFromParam: name: slot_number_from in: query description: 'Filter: slot number >= this value (1–100)' schema: type: integer minimum: 1 maximum: 100 SlotNumberToParam: name: slot_number_to in: query description: 'Filter: slot number <= this value (1–100)' schema: type: integer minimum: 1 maximum: 100 LimitParam: name: limit in: query description: Maximum number of items per page schema: type: integer minimum: 1 maximum: 100 default: 10 AfterParam: name: after in: query description: >- Cursor for the next page — pass the `next_cursor` value from the previous response schema: type: string example: con_a1b2c3d4 headers: X-RateLimit-Limit: description: Maximum number of requests allowed per window schema: type: integer example: 300 X-RateLimit-Remaining: description: Remaining requests in the current window schema: type: integer example: 299 X-RateLimit-Reset: description: Seconds until the rate limit window resets schema: type: integer example: 60 schemas: NominationList: type: object properties: nominations: type: array description: List of nominations items: $ref: '#/components/schemas/Nomination' pagination: $ref: '#/components/schemas/Pagination' required: - nominations - pagination Nomination: type: object description: >- The net saldo of valid transactions, aggregated by balance group and delivery period. Nominations are immutable — corrections produce a new version. properties: id: type: string description: Unique nomination identifier example: nom_t4u5v6w7x8 status: type: string description: Nomination status enum: - pending - partial_match - match - superseded example: match version: type: integer description: Version number (starts at 1, increments on correction) example: 1 previous_nomination_id: type: string nullable: true description: ID of the nomination this version supersedes example: null gate_closure: type: string format: date-time nullable: true description: ISO 8601 gate closure deadline example: '2026-01-14T14:30:00Z' confirmed_at: type: string format: date-time nullable: true description: ISO 8601 timestamp when the nomination was confirmed example: '2026-01-14T15:00:00Z' direction: type: string description: Energy direction from the BRP's perspective enum: - out - in example: out eic: type: string description: EIC code (balance group) of the BRP example: 11YWINDPARKNO--A tso: type: string description: BRP's TSO enum: - DE_AMPRION - DE_TENNET - DE_TRANSNET_BW - DE_50HERTZ example: DE_TENNET sent_at: type: string format: date-time nullable: true description: ISO 8601 timestamp when sent to the TSO example: '2026-01-14T14:35:00Z' counterparty: $ref: '#/components/schemas/NominationCounterparty' slots: type: array description: >- Delivery time slots with volumes (only present when `include_slots=true` on list endpoint; always present on detail/bulk/history endpoints) items: $ref: '#/components/schemas/NominationSlot' created_at: type: string format: date-time description: ISO 8601 creation timestamp example: '2026-01-14T14:30:00Z' required: - id - status - version - gate_closure - direction - eic - tso - counterparty - created_at Pagination: type: object properties: limit: type: integer description: Maximum items per page example: 10 has_more: type: boolean description: Whether more records exist after the last returned record example: true next_cursor: type: string nullable: true description: >- Cursor to pass as the `after` query parameter to fetch the next page. Null when there are no more pages. example: txn_k8m2p4q7r1 required: - limit - has_more - next_cursor Problem: type: object description: >- Error response following [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457). properties: type: type: string format: uri description: Absolute URI identifying the problem class example: https://brp.otark.team/errors/balance_group_tso_not_enabled title: type: string description: >- Short human-readable label (stable across occurrences of the same type) example: Balance Group TSO Not Enabled status: type: integer description: HTTP status code example: 400 detail: type: string description: Human-readable explanation for this specific occurrence example: >- The requested TSO is not enabled for this balance group. Enable it via the balance group settings first. instance: type: string description: URI identifying the specific request example: /v1/customers/cust_r8s9t0u1 errors: type: array description: Field-level validation errors (present on validation failures) items: $ref: '#/components/schemas/ProblemFieldError' required: - type - title - status NominationCounterparty: type: object description: The counterparty in a nomination (Otark acts as intermediary) properties: name: type: string description: Counterparty name example: Otark eic: type: string description: EIC code example: 11YOTARK------Z required: - name - eic NominationSlot: type: object description: A delivery time slot within a nomination properties: delivery_start: type: string format: date-time description: ISO 8601 slot start (UTC) example: '2026-01-15T14:00:00Z' delivery_end: type: string format: date-time description: ISO 8601 slot end (UTC) example: '2026-01-15T14:15:00Z' slot_number: type: integer description: >- Quarter-hour slot number within the delivery day (1–96, or up to 100 on DST days) minimum: 1 maximum: 100 example: 57 amount: type: number description: Nominated energy volume in MWh (3 decimal places) example: 12.5 matched_amount: type: number nullable: true description: Confirmed/matched volume in MWh (null until matched) example: 12.5 required: - delivery_start - delivery_end - slot_number - amount ProblemFieldError: type: object description: A single field-level validation error properties: field: type: string description: JSON path of the field that caused the error example: balance_group.tso code: type: string description: >- Machine-readable error code: `unknown_field`, `read_only_field`, `required`, `invalid_type`, `invalid_enum_value`, `invalid_format`, `invalid_literal`, `value_too_small`, `value_too_large`, or `validation_failed` example: invalid_enum_value message: type: string description: Human-readable description of the issue example: >- Invalid enum value. Expected 'DE_AMPRION' | 'DE_TENNET' | 'DE_TRANSNET_BW' | 'DE_50HERTZ', received 'INVALID' required: - code - message responses: BadRequest: description: Invalid request — validation error or business rule violation content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: 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', received 'INVALID' Unauthorized: description: Missing or invalid API key content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://brp.otark.team/errors/invalid_api_key title: Invalid API Key status: 401 Forbidden: description: API key lacks required scopes content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://brp.otark.team/errors/insufficient_scopes title: Insufficient API Key Scopes status: 403 detail: >- Missing scope: customers:write. Please create a new API key with the required scopes. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key ````