Elhub Substation API

openapi: 3.2.0
info:
  title: Flexibility Information System Grid Substation API
  description: Norwegian Flexibility Information System Grid API
  contact:
    name: Elhub AS
    url: https://elhub.no
    email: post@elhub.no
  version: '0'
servers:
- url: https://test.flex.internal:6443/grid/v0
  description: Development
tags:
- name: substation
  description: Substation
paths:
  /substation:
    summary: Substation
    description: ''
    get:
      operationId: list_substation
      summary: List Substation
      tags:
      - substation
      parameters:
      - in: query
        schema:
          type: string
          pattern: ^eq\.[0-9]+$
        example: eq.55
        description: Unique surrogate identifier.
        name: id
      - in: query
        name: name
        schema:
          type: string
        example: eq.somename
        description: The name of the substation.
      - in: query
        name: business_id
        schema:
          type: string
        example: eq.somebusiness_id
        description: The business identifier (mRID) of the substation.
      - in: query
        name: business_id_type
        schema:
          type: string
        example: eq.somebusiness_id_type
      - in: query
        name: kind
        schema:
          type: string
        example: eq.somekind
      - in: query
        name: primary_concessionaire
        schema:
          type: string
        example: eq.someprimary_concessionaire
        description: The name of the primary grid concessionaire responsible for this substation.
      - in: query
        schema:
          type: string
          pattern: ^eq\.[0-9]+$
        example: eq.55
        description: The substation cluster this substation belongs to.
        name: substation_cluster_id
      - in: query
        name: status
        schema:
          type: string
        example: eq.somestatus
      - description: Filtering Columns
        in: query
        name: select
        schema:
          type: string
      - description: Ordering
        in: query
        name: order
        schema:
          type: string
      - description: Limiting and Pagination
        in: query
        name: offset
        schema:
          type: string
      - description: Limiting and Pagination
        in: query
        name: limit
        schema:
          type: string
      - in: query
        name: embed
        schema:
          type: string
        description: Comma-separated list of related resources to embed in the response.
      - $ref: '#/components/parameters/ApiVersion'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/substation_response'
                type: array
          description: OK
        '206':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/substation_response'
                type: array
          description: Partial Content
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error_message'
                - $ref: '#/components/schemas/empty_object'
          description: Not Found
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Not Acceptable
        '416':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Range Not Satisfiable
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Internal Server Error
      security:
      - bearerAuth:
        - read:grid:substation
      - {}
  /substation/{id}:
    summary: Substation - single
    description: ''
    parameters:
    - in: path
      name: id
      required: true
      schema:
        format: bigint
        type: integer
      example: 14
    get:
      operationId: read_substation
      summary: Read Substation
      tags:
      - substation
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/substation_response'
          description: OK
          links:
            substation_cluster_id:
              operationId: read_substation_cluster
              parameters:
                path.id: $response.body#/substation_cluster_id
              description: The `substation_cluster_id` value returned in the response can be used as the `id` parameter in `GET /substation_cluster/{id}`.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/error_message'
                - $ref: '#/components/schemas/empty_object'
          description: Not Found
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Not Acceptable
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
          description: Internal Server Error
      security:
      - bearerAuth:
        - read:grid:substation
      - {}
      parameters:
      - in: query
        name: embed
        schema:
          type: string
        description: Comma-separated list of related resources to embed in the response.
      - $ref: '#/components/parameters/ApiVersion'
components:
  schemas:
    line_business_id_type:
      description: The type of the business identifier.
      format: text
      type: string
      readOnly: true
      enum:
      - uuid
      example: uuid
    substation_business_id_type:
      description: The type of the business identifier.
      format: text
      type: string
      readOnly: true
      enum:
      - uuid
      example: uuid
    substation_status:
      description: The status of the substation.
      format: text
      type: string
      readOnly: true
      enum:
      - active
      - inactive
      example: active
    error_message:
      description: Error message returned from the API.
      type: object
      properties:
        code:
          type: string
          pattern: ^[A-Z0-9]+$
          description: The error code.
          example: PT418
        details:
          type:
          - string
          - 'null'
          description: Detailed information about the error.
        hint:
          type:
          - string
          - 'null'
          description: A hint to help resolve the error.
        message:
          type: string
          description: The error message.
          example: error
      required:
      - code
      - message
    substation_cluster_business_id_type:
      description: The type of the business identifier.
      format: text
      type: string
      readOnly: true
      enum:
      - uuid
      example: uuid
    substation_kind:
      description: The type of substation.
      format: text
      type: string
      readOnly: true
      enum:
      - coupling
      - junction
      - power
      - transformer
      example: transformer
    substation_response:
      summary: Response - Substation
      description: Response schema - A substation in the common grid model (Nemo), representing a node in the electricity grid.
      type: object
      properties:
        id:
          description: Unique surrogate identifier.
          format: bigint
          type: integer
          readOnly: true
          example: 1
        name:
          description: The name of the substation.
          format: text
          type: string
          readOnly: true
          example: Snilldal 1 KRA
        business_id:
          description: The business identifier (mRID) of the substation.
          format: text
          type: string
          readOnly: true
          example: 6f3a1b9e-2c4d-4e5f-8a7b-9c0d1e2f3a4b
        business_id_type:
          $ref: '#/components/schemas/substation_business_id_type'
          readOnly: true
        kind:
          $ref: '#/components/schemas/substation_kind'
          readOnly: true
        primary_concessionaire:
          description: The name of the primary grid concessionaire responsible for this substation.
          format: text
          type: string
          readOnly: true
          example: Statnett SF
        substation_cluster_id:
          description: The substation cluster this substation belongs to.
          format: bigint
          type: integer
          readOnly: true
          example: 1
        voltage_levels:
          description: List of nominal voltage levels present at the substation, in kilovolt (kV).
          type: array
          readOnly: true
          items:
            type: number
          example:
          - 22.0
          - 132.0
        position:
          description: Geographic position of the substation (WGS84), as a GeoJSON point object.
          readOnly: true
          type: object
          oneOf:
          - $ref: '#/components/schemas/geojson_point'
          example:
            type: Point
            coordinates:
            - 10.757933
            - 59.911491
        status:
          $ref: '#/components/schemas/substation_status'
          readOnly: true
        recorded_at:
          description: When the resource was recorded (created or updated) in the system.
          format: date-time
          type: string
          readOnly: true
          example: '2023-12-31T23:59:00+00:00'
        recorded_by:
          description: The identity that recorded the resource.
          format: bigint
          type: integer
          readOnly: true
          example: 145
        substation_cluster:
          description: Embedded substation_cluster
          oneOf:
          - $ref: '#/components/schemas/substation_cluster_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - name
      - business_id
      - business_id_type
      - kind
      - primary_concessionaire
      - substation_cluster_id
      - voltage_levels
      - position
      - status
      - recorded_at
      - recorded_by
    geojson_polygon:
      type: object
      properties:
        type:
          type: string
          enum:
          - Polygon
        coordinates:
          type: array
          description: Array of linear rings (WGS84). First ring is the exterior boundary.
          items:
            type: array
            items:
              type: array
              items:
                type: number
              minItems: 2
              maxItems: 2
      required:
      - type
      - coordinates
    substation_cluster_status:
      description: The status of the substation cluster.
      format: text
      type: string
      readOnly: true
      enum:
      - active
      - inactive
      example: active
    geojson_linestring:
      type: object
      properties:
        type:
          type: string
          enum:
          - LineString
        coordinates:
          type: array
          description: Array of [longitude, latitude] positions in decimal degrees (WGS84)
          items:
            type: array
            items:
              type: number
            minItems: 2
            maxItems: 2
          minItems: 2
      required:
      - type
      - coordinates
    empty_object:
      description: An empty object
      type: object
      properties: {}
      additionalProperties: false
    line_status:
      description: The status of the line.
      format: text
      type: string
      readOnly: true
      enum:
      - active
      - inactive
      example: active
    line_response:
      summary: Response - Line
      description: Response schema - A transmission or distribution line in the common grid model (Nemo), connecting two substation clusters.
      type: object
      properties:
        id:
          description: Unique surrogate identifier.
          format: bigint
          type: integer
          readOnly: true
          example: 1
        name:
          description: The name of the line.
          format: text
          type: string
          readOnly: true
          example: Snilldal - Trollheim
        business_id:
          description: The business identifier (mRID) of the line.
          format: text
          type: string
          readOnly: true
          example: a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d
        business_id_type:
          $ref: '#/components/schemas/line_business_id_type'
          readOnly: true
        from_substation_cluster_id:
          description: The substation cluster at the start of the line.
          format: bigint
          type: integer
          readOnly: true
          example: 1
        to_substation_cluster_id:
          description: The substation cluster at the end of the line.
          format: bigint
          type: integer
          readOnly: true
          example: 2
        line:
          description: Geographic path of the line (WGS84), as a GeoJSON linestring object.
          readOnly: true
          type: object
          oneOf:
          - $ref: '#/components/schemas/geojson_linestring'
          example:
            type: LineString
            coordinates:
            - - 10.757933
              - 59.911491
            - - 10.858933
              - 59.951491
        status:
          $ref: '#/components/schemas/line_status'
          readOnly: true
        recorded_at:
          description: When the resource was recorded (created or updated) in the system.
          format: date-time
          type: string
          readOnly: true
          example: '2023-12-31T23:59:00+00:00'
        recorded_by:
          description: The identity that recorded the resource.
          format: bigint
          type: integer
          readOnly: true
          example: 145
        from_substation_cluster:
          description: Embedded substation_cluster
          oneOf:
          - $ref: '#/components/schemas/substation_cluster_response'
          - type: 'null'
          nullable: true
        to_substation_cluster:
          description: Embedded substation_cluster
          oneOf:
          - $ref: '#/components/schemas/substation_cluster_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - name
      - business_id
      - business_id_type
      - from_substation_cluster_id
      - to_substation_cluster_id
      - line
      - status
      - recorded_at
      - recorded_by
    substation_cluster_response:
      summary: Response - Substation Cluster
      description: Response schema - A cluster of substations in the common grid model (Nemo), representing a group of electrically related substations in a geographic area.
      type: object
      properties:
        id:
          description: Unique surrogate identifier.
          format: bigint
          type: integer
          readOnly: true
          example: 1
        name:
          description: The name of the substation cluster.
          format: text
          type: string
          readOnly: true
          example: Snilldal
        business_id:
          description: The business identifier (mRID) of the substation cluster.
          format: text
          type: string
          readOnly: true
          example: 53919b79-876f-4dad-8bde-b29368367604
        business_id_type:
          $ref: '#/components/schemas/substation_cluster_business_id_type'
          readOnly: true
        averaged_position:
          description: Averaged geographic position of the substation cluster (WGS84), as a GeoJSON point object.
          readOnly: true
          type: object
          oneOf:
          - $ref: '#/components/schemas/geojson_point'
          example:
            type: Point
            coordinates:
            - 10.757933
            - 59.911491
        area:
          description: Geographic area covered by the substation cluster (WGS84), as a GeoJSON polygon object.
          readOnly: true
          type: object
          oneOf:
          - $ref: '#/components/schemas/geojson_polygon'
          example:
            type: Polygon
            coordinates:
            - - - 10.757933
                - 59.911491
              - - 10.758933
                - 59.911491
              - - 10.758933
                - 59.912491
              - - 10.757933
                - 59.912491
              - - 10.757933
                - 59.911491
        status:
          $ref: '#/components/schemas/substation_cluster_status'
          readOnly: true
        recorded_at:
          description: When the resource was recorded (created or updated) in the system.
          format: date-time
          type: string
          readOnly: true
          example: '2023-12-31T23:59:00+00:00'
        recorded_by:
          description: The identity that recorded the resource.
          format: bigint
          type: integer
          readOnly: true
          example: 145
        substation:
          description: Embedded substation
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/substation_response'
          - type: 'null'
          nullable: true
        line:
          description: Embedded line
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/line_response'
          - type: 'null'
          nullable: true
      required:
      - id
      - name
      - business_id
      - business_id_type
      - averaged_position
      - area
      - status
      - recorded_at
      - recorded_by
    geojson_point:
      type: object
      properties:
        type:
          type: string
          enum:
          - Point
        coordinates:
          type: array
          description: '[longitude, latitude] in decimal degrees (WGS84)'
          items:
            type: number
          minItems: 2
          maxItems: 2
      required:
      - type
      - coordinates
  parameters:
    ApiVersion:
      name: Api-Version
      in: header
      required: true
      description: 'The API version to use. Must be a supported version date. See the [changelog](https://elhub.github.io/flex-information-system/changelog/) for available versions.

        '
      schema:
        type: string
        enum:
        - '2026-06-08'
        example: '2026-06-08'
  securitySchemes:
    bearerAuth:
      description: Bearer token using a JWT
      type: http
      scheme: Bearer
      bearerFormat: JWT
externalDocs:
  description: API Changelog
  url: https://elhub.github.io/flex-information-system/changelog/