openapi: 3.0.3
info:
  title: Balancing Services REST API
  version: 1.5.1
  description: REST API for balancing services data
  contact:
    name: Balancing Services Team

servers:
  - url: https://api.balancing.services/v1
    description: Production API server

security:
  - BearerAuth: []

paths:
  /imbalance/prices:
    get:
      summary: Get imbalance prices for an area
      description: Returns imbalance prices for the specified area within the given time period
      operationId: getImbalancePrices
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImbalancePricesResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

  /imbalance/total-volumes:
    get:
      summary: Get total imbalance volumes for an area
      description: Returns total aggregated imbalance volumes for the specified area within the given time period. Volumes are expressed as average power in MW.
      operationId: getImbalanceTotalVolumes
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImbalanceTotalVolumesResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

  /balancing/energy/activated-volumes:
    get:
      summary: Get activated balancing energy volumes
      description: Returns activated balancing energy volumes for the specified area within the given time period. Volumes are expressed as (average) power in MW.
      operationId: getBalancingEnergyActivatedVolumes
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
        - name: reserve-type
          in: query
          description: Filter by reserve type
          required: true
          schema:
            $ref: '#/components/schemas/ReserveType'
          example: 'aFRR'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancingEnergyVolumesResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

  /balancing/energy/prices:
    get:
      summary: Get balancing energy prices
      description: Returns balancing energy prices for the specified area and reserve type within the given time period
      operationId: getBalancingEnergyPrices
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
        - name: reserve-type
          in: query
          description: Filter by reserve type
          required: true
          schema:
            $ref: '#/components/schemas/ReserveType'
          example: 'aFRR'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancingEnergyPricesResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

  /balancing/energy/bids:
    get:
      summary: Get balancing energy bids
      description: Returns balancing energy bids for the specified area within the given time period. Supports cursor-based pagination for large result sets.
      operationId: getBalancingEnergyBids
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
        - name: reserve-type
          in: query
          description: Filter by reserve type
          required: true
          schema:
            $ref: '#/components/schemas/ReserveType'
          example: 'aFRR'
        - name: cursor
          in: query
          description: Pagination cursor from previous response. Omit to start from the beginning.
          required: false
          schema:
            type: string
            example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
        - name: limit
          in: query
          description: Maximum number of results to return (default 100, max 1000)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            example: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancingEnergyBidsResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

  /balancing/capacity/bids:
    get:
      summary: Get balancing capacity bids
      description: Returns balancing capacity bids for the specified area within the given time period. Supports cursor-based pagination for large result sets.
      operationId: getBalancingCapacityBids
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
        - name: reserve-type
          in: query
          description: Filter by reserve type
          required: true
          schema:
            $ref: '#/components/schemas/ReserveType'
          example: 'aFRR'
        - name: cursor
          in: query
          description: Pagination cursor from previous response. Omit to start from the beginning.
          required: false
          schema:
            type: string
            example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
        - name: limit
          in: query
          description: Maximum number of results to return (default 100, max 1000)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            example: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancingCapacityBidsResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

  /balancing/capacity/prices:
    get:
      summary: Get balancing capacity prices
      description: Returns balancing capacity prices for the specified area and reserve type within the given time period. Only paid prices are returned.
      operationId: getBalancingCapacityPrices
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
        - name: reserve-type
          in: query
          description: Filter by reserve type
          required: true
          schema:
            $ref: '#/components/schemas/ReserveType'
          example: 'aFRR'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancingCapacityPricesResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

  /balancing/capacity/procured-volumes:
    get:
      summary: Get procured balancing capacity volumes
      description: Returns procured balancing capacity volumes for the specified area and reserve type within the given time period. Volumes are expressed in MW.
      operationId: getBalancingCapacityProcuredVolumes
      parameters:
        - name: area
          in: query
          description: The area for which to retrieve data
          required: true
          schema:
            $ref: '#/components/schemas/Area'
          example: 'EE'
        - name: period-start-at
          in: query
          description: Start of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-01T00:00:00Z'
        - name: period-end-at
          in: query
          description: End of the time period (UTC)
          required: true
          schema:
            type: string
            format: date-time
            example: '2025-01-02T00:00:00Z'
        - name: reserve-type
          in: query
          description: Filter by reserve type
          required: true
          schema:
            $ref: '#/components/schemas/ReserveType'
          example: 'aFRR'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancingCapacityVolumesResponse'
        '400':
          description: Bad request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                invalid-parameter:
                  $ref: '#/components/examples/problem-invalid-parameter'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                unauthorized:
                  $ref: '#/components/examples/problem-unauthorized'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                forbidden:
                  $ref: '#/components/examples/problem-forbidden'
        '404':
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-found:
                  $ref: '#/components/examples/problem-not-found'
        '429':
          description: Too many requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                rate-limited:
                  $ref: '#/components/examples/problem-rate-limited'
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                internal-error:
                  $ref: '#/components/examples/problem-internal-error'
        '501':
          description: Not implemented
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              examples:
                not-implemented:
                  $ref: '#/components/examples/problem-not-implemented'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API token

  examples:
    problem-missing-parameter:
      summary: Missing required parameter
      value:
        type: missing-parameter
        title: Missing Parameter
        status: 400
        detail: Required parameter 'area' is missing
    problem-invalid-parameter:
      summary: Invalid parameter value
      value:
        type: invalid-parameter
        title: Invalid Parameter
        status: 400
        detail: The area parameter value is not valid
    problem-unauthorized:
      summary: Missing or invalid authentication
      value:
        type: unauthorized
        title: Unauthorized
        status: 401
        detail: Valid API token required
    problem-forbidden:
      summary: Insufficient permissions
      value:
        type: forbidden
        title: Forbidden
        status: 403
        detail: Access to this resource is not allowed
    problem-not-found:
      summary: Resource not found
      value:
        type: not-found
        title: Not Found
        status: 404
        detail: The requested resource was not found
    problem-not-implemented:
      summary: Feature not yet implemented
      value:
        type: not-implemented
        title: Not Implemented
        status: 501
        detail: This feature is not yet available
    problem-rate-limited:
      summary: Too many requests
      value:
        type: rate-limited
        title: Rate Limited
        status: 429
        detail: Request limit exceeded. Please try again later
    problem-internal-error:
      summary: Server error
      value:
        type: internal-error
        title: Internal Server Error
        status: 500
        detail: An unexpected error occurred while processing the request

  schemas:
    ImbalancePricesResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImbalancePrices'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: true

    ImbalancePrices:
      type: object
      required:
        - area
        - eicCode
        - currency
        - direction
        - prices
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        currency:
          $ref: '#/components/schemas/Currency'
        direction:
          $ref: '#/components/schemas/ImbalanceDirection'
        prices:
          type: array
          items:
            $ref: '#/components/schemas/ImbalancePrice'

    ImbalancePrice:
      type: object
      required:
        - period
        - price
      properties:
        period:
          $ref: '#/components/schemas/Period'
        price:
          type: number
          description: Price per MWh in the specified currency
          example: 45.50

    ImbalanceTotalVolumesResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImbalanceTotalVolumes'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: false

    ImbalanceTotalVolumes:
      type: object
      required:
        - area
        - eicCode
        - volumes
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        volumes:
          type: array
          items:
            $ref: '#/components/schemas/TotalImbalanceVolume'
          description: Array of total imbalance volumes for each period, direction can vary per period

    TotalImbalanceVolume:
      type: object
      required:
        - period
        - averagePowerMW
        - direction
      properties:
        period:
          $ref: '#/components/schemas/Period'
        averagePowerMW:
          type: number
          description: Average power in MW during the period
          example: 60.5
        direction:
          $ref: '#/components/schemas/TotalImbalanceDirection'

    BalancingEnergyVolumesResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BalancingEnergyVolumes'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: true

    BalancingEnergyVolumes:
      type: object
      required:
        - area
        - eicCode
        - reserveType
        - direction
        - activationType
        - standardProduct
        - volumes
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        reserveType:
          $ref: '#/components/schemas/ReserveType'
        direction:
          $ref: '#/components/schemas/Direction'
        activationType:
          $ref: '#/components/schemas/ActivationType'
        standardProduct:
          type: boolean
          description: Indicates if this is a European standard balancing product
          example: true
        volumes:
          type: array
          items:
            $ref: '#/components/schemas/BalancingEnergyVolume'

    BalancingEnergyVolume:
      type: object
      required:
        - period
        - volume
      properties:
        period:
          $ref: '#/components/schemas/Period'
        volume:
          type: number
          description: Volume in MWh
          example: 250.5

    BalancingEnergyPricesResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BalancingEnergyPrices'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: false

    BalancingEnergyPrices:
      type: object
      required:
        - area
        - eicCode
        - reserveType
        - direction
        - activationType
        - currency
        - standardProduct
        - prices
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        reserveType:
          $ref: '#/components/schemas/ReserveType'
        direction:
          $ref: '#/components/schemas/Direction'
        activationType:
          $ref: '#/components/schemas/ActivationType'
        currency:
          $ref: '#/components/schemas/Currency'
        standardProduct:
          type: boolean
          description: Indicates if this is a European standard balancing product
          example: true
        prices:
          type: array
          items:
            $ref: '#/components/schemas/BalancingEnergyPrice'

    BalancingEnergyPrice:
      type: object
      required:
        - period
        - price
      properties:
        period:
          $ref: '#/components/schemas/Period'
        price:
          type: number
          description: Price per MWh in the specified currency
          example: 45.50

    BalancingEnergyBidsResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BalancingEnergyBids'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: true

    BalancingEnergyBids:
      type: object
      required:
        - area
        - eicCode
        - reserveType
        - direction
        - currency
        - standardProduct
        - bids
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        reserveType:
          $ref: '#/components/schemas/ReserveType'
        direction:
          $ref: '#/components/schemas/Direction'
        currency:
          $ref: '#/components/schemas/Currency'
        standardProduct:
          type: boolean
          description: Indicates if this is a European standard balancing product
          example: true
        bids:
          type: array
          items:
            $ref: '#/components/schemas/EnergyBid'

    EnergyBid:
      type: object
      required:
        - period
        - volume
        - price
      properties:
        period:
          $ref: '#/components/schemas/Period'
        volume:
          type: number
          description: Bid volume in MW
          example: 100
        price:
          type: number
          description: Bid price per MWh in the specified currency
          example: 55.25

    BalancingCapacityBidsResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BalancingCapacityBids'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: true

    BalancingCapacityBids:
      type: object
      required:
        - area
        - eicCode
        - reserveType
        - direction
        - currency
        - bids
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        reserveType:
          $ref: '#/components/schemas/ReserveType'
        direction:
          $ref: '#/components/schemas/Direction'
        currency:
          $ref: '#/components/schemas/Currency'
        bids:
          type: array
          items:
            $ref: '#/components/schemas/CapacityBid'

    CapacityBid:
      type: object
      required:
        - period
        - capacity
        - price
        - status
      properties:
        period:
          $ref: '#/components/schemas/Period'
        capacity:
          type: number
          description: Bid capacity in MW
          example: 50
        price:
          type: number
          description: Bid price per MW per hour in the specified currency
          example: 12.50
        status:
          $ref: '#/components/schemas/BidStatus'

    BalancingCapacityPricesResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BalancingCapacityPrices'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: false

    BalancingCapacityPrices:
      type: object
      required:
        - area
        - eicCode
        - reserveType
        - direction
        - currency
        - prices
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        reserveType:
          $ref: '#/components/schemas/ReserveType'
        direction:
          $ref: '#/components/schemas/Direction'
        currency:
          $ref: '#/components/schemas/Currency'
        procuredAt:
          type: string
          format: date-time
          nullable: true
          description: |
            **EXPERIMENTAL**: Timestamp when the capacity was procured (allocation time or gate closure time).
            Used to distinguish different auctions (e.g., yearly vs hourly, or multiple procurement rounds).
            This field is experimental and may be changed or removed without a deprecation period.
          example: "2024-08-15T14:30:00Z"
          x-experimental: true
        prices:
          type: array
          items:
            $ref: '#/components/schemas/BalancingCapacityPrice'

    BalancingCapacityPrice:
      type: object
      required:
        - period
        - price
      properties:
        period:
          $ref: '#/components/schemas/Period'
        price:
          type: number
          description: Price per MW per hour in the specified currency
          example: 12.50

    BalancingCapacityVolumesResponse:
      type: object
      required:
        - queriedPeriod
        - data
        - hasMore
      properties:
        queriedPeriod:
          $ref: '#/components/schemas/Period'
        data:
          type: array
          items:
            $ref: '#/components/schemas/BalancingCapacityVolumes'
        nextCursor:
          type: string
          description: Cursor to fetch the next page of results. Null if no more results.
          example: 'v1:AAAAAYwBAgMEBQYHCAkKCw=='
          nullable: true
        hasMore:
          type: boolean
          description: Indicates whether there are more results available
          example: false

    BalancingCapacityVolumes:
      type: object
      required:
        - area
        - eicCode
        - reserveType
        - direction
        - volumes
      properties:
        area:
          $ref: '#/components/schemas/Area'
        eicCode:
          $ref: '#/components/schemas/EicCode'
        reserveType:
          $ref: '#/components/schemas/ReserveType'
        direction:
          $ref: '#/components/schemas/Direction'
        procuredAt:
          type: string
          format: date-time
          nullable: true
          description: |
            **EXPERIMENTAL**: Timestamp when the capacity was procured (allocation time or gate closure time).
            Used to distinguish different auctions (e.g., yearly vs hourly, or multiple procurement rounds).
            This field is experimental and may be changed or removed without a deprecation period.
          example: "2024-08-15T14:30:00Z"
          x-experimental: true
        volumes:
          type: array
          items:
            $ref: '#/components/schemas/BalancingCapacityVolume'

    BalancingCapacityVolume:
      type: object
      required:
        - period
        - volume
      properties:
        period:
          $ref: '#/components/schemas/Period'
        volume:
          type: number
          description: Volume in MW
          example: 50.0

    Period:
      type: object
      required:
        - startAt
        - endAt
      properties:
        startAt:
          type: string
          format: date-time
          description: Start of the period (UTC)
          example: '2025-01-01T00:00:00Z'
        endAt:
          type: string
          format: date-time
          description: End of the period (UTC)
          example: '2025-01-01T01:00:00Z'

    Area:
      type: string
      description: Area code
      enum:
        - AT
        - BE
        - BG
        - CH
        - CZ
        - DE
        - DE_50HERTZ
        - DE_AMPRION
        - DE_TENNET
        - DE_TRANSNETBW
        - DK1
        - DK2
        - EE
        - ES
        - FI
        - FR
        - GR
        - HR
        - HU
        - IT_NORTH
        - IT_CENTER_NORTH
        - IT_CENTER_SOUTH
        - IT_SOUTH
        - IT_CALABRIA
        - IT_SICILY
        - IT_SARDINIA
        - LT
        - LV
        - NL
        - NO1
        - NO2
        - NO3
        - NO4
        - NO5
        - PL
        - PT
        - RO
        - RS
        - SE1
        - SE2
        - SE3
        - SE4
        - SI
        - SK

    EicCode:
      type: string
      description: Energy Identification Code (EIC)
      enum:
        - 10YAT-APG------L
        - 10YBE----------2
        - 10YCA-BULGARIA-R
        - 10YCH-SWISSGRIDZ
        - 10YCZ-CEPS-----N
        - 10Y1001A1001A83F
        - 10YDE-VE-------2
        - 10YDE-RWENET---I
        - 10YDE-EON------1
        - 10YDE-ENBW-----N
        - 10YDK-1--------W
        - 10YDK-2--------M
        - 10Y1001A1001A39I
        - 10YES-REE------0
        - 10YFI-1--------U
        - 10YFR-RTE------C
        - 10YGR-HTSO-----Y
        - 10YHR-HEP------M
        - 10YHU-MAVIR----U
        - 10Y1001A1001A73I
        - 10Y1001A1001A70O
        - 10Y1001A1001A71M
        - 10Y1001A1001A788
        - 10Y1001C--00096J
        - 10Y1001A1001A75E
        - 10Y1001A1001A74G
        - 10YLT-1001A0008Q
        - 10YLV-1001A00074
        - 10YNL----------L
        - 10YNO-1--------2
        - 10YNO-2--------T
        - 10YNO-3--------J
        - 10YNO-4--------9
        - 10Y1001A1001A48H
        - 10YPL-AREA-----S
        - 10YPT-REN------W
        - 10YRO-TEL------P
        - 10YCS-SERBIATSOV
        - 10Y1001A1001A44P
        - 10Y1001A1001A45N
        - 10Y1001A1001A46L
        - 10Y1001A1001A47J
        - 10YSI-ELES-----O
        - 10YSK-SEPS-----K

    ReserveType:
      type: string
      description: Reserve type
      enum:
        - FCR
        - aFRR
        - mFRR
        - RR

    Direction:
      type: string
      description: Balancing direction
      enum:
        - up
        - symmetric
        - down

    ImbalanceDirection:
      type: string
      description: Imbalance direction
      enum:
        - positive
        - symmetric
        - negative

    TotalImbalanceDirection:
      type: string
      description: |
        Total imbalance volume direction (ENTSO-E regulatory terminology):
        - surplus: Generation exceeds consumption (D > 0, positive imbalance)
        - deficit: Consumption exceeds generation (D < 0, negative imbalance)
        - balanced: Generation equals consumption (D = 0)
      enum:
        - surplus
        - deficit
        - balanced

    Currency:
      type: string
      description: Currency code
      enum:
        - BGN
        - EUR
        - HUF
        - PLN
        - RON

    ActivationType:
      type: string
      description: Activation type (only applicable for mFRR)
      enum:
        - direct
        - scheduled
        - not_applicable

    BidStatus:
      type: string
      description: |
        Status of a capacity bid:
        - offered: Bid was offered but not accepted
        - accepted: Bid was accepted (at least partially accepted)
      enum:
        - offered
        - accepted

    Problem:
      type: object
      required:
        - type
        - status
        - title
      properties:
        type:
          type: string
          enum:
            - missing-parameter
            - invalid-parameter
            - unauthorized
            - forbidden
            - not-implemented
            - rate-limited
            - internal-error
          description: Problem type identifier
        title:
          type: string
          description: Short, human-readable summary of the problem type
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
