openapi: 3.2.0 info: title: CDR Energy Distributed Energy Resources API version: 1.36.0 description: Specifications for resource endpoints applicable to data holders in the Energy sector. contact: name: Data Standards Body email: contact@dsb.gov.au url: https://dsb.gov.au/ servers: - description: MTLS url: https://mtls.dh.example.com/cds-au/v1 tags: - name: Distributed Energy Resources x-shortName: Distributed Energy Resources description: Distributed Energy Resource endpoints paths: /energy/electricity/servicepoints/{servicePointId}/der: get: summary: Get DER For Service Point operationId: getElectricityDERForServicePoint description: Obtain a list of DER data from a particular service point. x-scopes: - energy:electricity.der:read tags: - Distributed Energy Resources x-version: '1' parameters: - $ref: '#/components/parameters/PathServicePointId' - $ref: '#/components/parameters/HeaderXV' - $ref: '#/components/parameters/HeaderXMinV' - $ref: '#/components/parameters/HeaderXFAPIInteractionId' - $ref: '#/components/parameters/HeaderXFAPIAuthDate' - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress' - $ref: '#/components/parameters/HeaderXCDSClientHeaders' responses: '200': $ref: '#/components/responses/GetElectricityDERForServicePoint200' '400': $ref: '#/components/responses/GetElectricityDERForServicePoint400' '404': $ref: '#/components/responses/GetElectricityDERForServicePoint404' '406': $ref: '#/components/responses/GetElectricityDERForServicePoint406' /energy/electricity/servicepoints/der: get: summary: Get Bulk DER operationId: listElectricityDERBulk description: Obtain DER data for all service points associated with the customer. x-scopes: - energy:electricity.der:read tags: - Distributed Energy Resources x-version: '1' parameters: - $ref: '#/components/parameters/QueryPage' - $ref: '#/components/parameters/QueryPageSize' - $ref: '#/components/parameters/HeaderXV' - $ref: '#/components/parameters/HeaderXMinV' - $ref: '#/components/parameters/HeaderXFAPIInteractionId' - $ref: '#/components/parameters/HeaderXFAPIAuthDate' - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress' - $ref: '#/components/parameters/HeaderXCDSClientHeaders' responses: '200': $ref: '#/components/responses/ListElectricityDERBulk200' '400': $ref: '#/components/responses/ListElectricityDERBulk400' '406': $ref: '#/components/responses/ListElectricityDERBulk406' '422': $ref: '#/components/responses/ListElectricityDERBulk422' post: summary: Get DER For Specific Service Points operationId: listElectricityDERForSpecificServicePoints description: Obtain DER data for a specific set of service points. x-scopes: - energy:electricity.der:read tags: - Distributed Energy Resources x-version: '1' parameters: - $ref: '#/components/parameters/QueryPage' - $ref: '#/components/parameters/QueryPageSize' - $ref: '#/components/parameters/HeaderXV' - $ref: '#/components/parameters/HeaderXMinV' - $ref: '#/components/parameters/HeaderXFAPIInteractionId' - $ref: '#/components/parameters/HeaderXFAPIAuthDate' - $ref: '#/components/parameters/HeaderXFAPICustomerIPAddress' - $ref: '#/components/parameters/HeaderXCDSClientHeaders' requestBody: $ref: '#/components/requestBodies/RequestServicePointIds' responses: '200': $ref: '#/components/responses/ListElectricityDERForSpecificServicePoints200' '400': $ref: '#/components/responses/ListElectricityDERForSpecificServicePoints400' '406': $ref: '#/components/responses/ListElectricityDERForSpecificServicePoints406' '422': $ref: '#/components/responses/ListElectricityDERForSpecificServicePoints422' components: parameters: HeaderXFAPIInteractionId: name: x-fapi-interaction-id description: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction. in: header schema: type: string HeaderXV: name: x-v description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers). in: header required: true schema: type: string HeaderXFAPICustomerIPAddress: name: x-fapi-customer-ip-address description: The customer's original IP address if the customer is currently logged in to the data recipient. The presence of this header indicates that the API is being called in a customer present context. Not to be included for unauthenticated calls. in: header schema: type: string QueryPageSize: name: page-size description: Page size to request. Default is 25 (standard pagination). in: query schema: type: integer default: '25' x-cds-type: PositiveInteger HeaderXCDSClientHeaders: name: x-cds-client-headers description: The customer's original standard http headers [Base64](#common-field-types) encoded, including the original User-Agent header, if the customer is currently logged in to the data recipient. Mandatory for customer present calls. Not required for unattended or unauthenticated calls. in: header x-conditional: true schema: type: string x-cds-type: Base64 HeaderXFAPIAuthDate: name: x-fapi-auth-date description: The time when the customer last logged in to the Data Recipient Software Product as described in **[[FAPI-1.0-Baseline]](#nref-FAPI-1-0-Baseline)**. Required for all resource calls (customer present and unattended). Not required for unauthenticated calls. in: header x-conditional: true schema: type: string PathServicePointId: name: servicePointId description: The _servicePointId_ to obtain data for. _servicePointId_ values are returned by service point list endpoints. Note that it is not a _nationalMeteringId_. in: path required: true schema: $ref: '#/components/schemas/EnergyServicePointId' QueryPage: name: page description: Page of results to request (standard pagination). in: query schema: type: integer default: '1' x-cds-type: PositiveInteger HeaderXMinV: name: x-min-v description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. in: header schema: type: string responses: GetElectricityDERForServicePoint400: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityDERForSpecificServicePoints200: description: Successful response headers: x-v: $ref: '#/components/headers/XV' x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/EnergyDerListResponse' GetElectricityDERForServicePoint200: description: Successful response headers: x-v: $ref: '#/components/headers/XV' x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/EnergyDerDetailResponse' GetElectricityDERForServicePoint404: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' GetElectricityDERForServicePoint406: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityDERBulk406: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityDERForSpecificServicePoints406: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityDERBulk422: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityDERForSpecificServicePoints422: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityDERBulk200: description: Successful response headers: x-v: $ref: '#/components/headers/XV' x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/EnergyDerListResponse' ListElectricityDERForSpecificServicePoints400: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' ListElectricityDERBulk400: description: The following error codes **MUST** be supported:
headers: x-fapi-interaction-id: $ref: '#/components/headers/XFAPIInteractionId' content: application/json: schema: $ref: '#/components/schemas/PrimaryResponseErrorListV1' schemas: LinksPaginated: type: object required: - self x-conditional: - first - prev - next - last properties: self: type: string description: Fully qualified link that generated the current response document. x-cds-type: URIString first: type: string description: URI to the first page of this set. Mandatory if this response is not the first page. x-cds-type: URIString prev: type: string description: URI to the previous page of this set. Mandatory if this response is not the first page. x-cds-type: URIString next: type: string description: URI to the next page of this set. Mandatory if this response is not the last page. x-cds-type: URIString last: type: string description: URI to the last page of this set. Mandatory if this response is not the last page. x-cds-type: URIString EnergyDerRecord: type: object required: - servicePointId - approvedCapacity - availablePhasesCount - installedPhasesCount - islandableInstallation - acConnections x-conditional: - protectionMode properties: servicePointId: description: Unique identifier for the service point. allOf: - $ref: '#/components/schemas/EnergyServicePointId' approvedCapacity: description: Approved small generating unit capacity as agreed with NSP in the connection agreement, expressed in kVA. Value of `0` indicates no DER record exists for the given _servicePointId_. type: number availablePhasesCount: description: The number of phases available for the installation of DER. Acceptable values are `0`, `1`, `2` or `3`. Value of `0` indicates no DER record exists for the given _servicePointId_. type: integer x-cds-type: NaturalNumber minimum: 0 maximum: 3 installedPhasesCount: description: The number of phases that DER is connected to. Acceptable values are `0`, `1`, `2` or `3`. Value of `0` indicates no DER record exists for the given _servicePointId_. type: integer x-cds-type: NaturalNumber minimum: 0 maximum: 3 islandableInstallation: description: For identification of small generating units designed with the ability to operate in an islanded mode. type: boolean hasCentralProtectionControl: description: For DER installations where NSPs specify the need for additional forms of protection above those inbuilt in an inverter. If absent then assumed to be `false`. type: boolean default: false protectionMode: description: Required only when the _hasCentralProtectionControl_ flag is set to `true`. One or more of the object fields will be provided to describe the protection modes in place. type: object properties: exportLimitKva: description: Maximum amount of power (kVA) that may be exported from a connection point to the grid, as monitored by a control/relay function. An absent value indicates no limit. type: number underFrequencyProtection: description: Protective function limit in Hz. type: number underFrequencyProtectionDelay: description: Trip delay time in seconds. type: number overFrequencyProtection: description: Protective function limit in Hz. type: number overFrequencyProtectionDelay: description: Trip delay time in seconds. type: number underVoltageProtection: description: Protective function limit in V. type: number underVoltageProtectionDelay: description: Trip delay time in seconds. type: number overVoltageProtection: description: Protective function limit in V. type: number overVoltageProtectionDelay: description: Trip delay time in seconds. type: number sustainedOverVoltage: description: Sustained over voltage. type: number sustainedOverVoltageDelay: description: Sustained Over voltage protection delay in seconds. type: number frequencyRateOfChange: description: Rate of change of frequency trip point (Hz/s). type: number voltageVectorShift: description: Trip angle in degrees. type: number interTripScheme: description: Description of the form of inter-trip (e.g., 'from local substation'). type: string neutralVoltageDisplacement: description: Trip voltage. type: number acConnections: type: array items: type: object required: - connectionIdentifier - count - commissioningDate - status - derDevices x-conditional: - manufacturerName - inverterSeries - inverterModelNumber - inverterDeviceCapacity properties: connectionIdentifier: description: AC Connection ID as defined in the DER register. Does not align with CDR ID permanence standards. type: number count: description: Number of AC Connections in the group. For the suite of AC Connections to be considered as a group, all of the AC Connections included must have the same attributes. type: integer x-cds-type: PositiveInteger equipmentType: description: Indicates whether the DER device is connected via an inverter (and what category of inverter it is) or not (e.g., rotating machine). If absent, assume equipment type to be `OTHER`. default: OTHER type: string enum: - INVERTER - OTHER manufacturerName: description: The name of the inverter manufacturer. Mandatory if _equipmentType_ is `INVERTER`. type: string inverterSeries: description: The inverter series. Mandatory if _equipmentType_ is `INVERTER`. type: string inverterModelNumber: description: The inverter model number. Mandatory if _equipmentType_ is `INVERTER`. type: string commissioningDate: description: The date that the DER installation is commissioned. type: string x-cds-type: DateString status: description: Code used to indicate the status of the Inverter. This will be used to identify if an inverter is active or inactive or decommissioned. type: string enum: - ACTIVE - INACTIVE - DECOMMISSIONED inverterDeviceCapacity: description: The rated AC output power that is listed in the product specified by the manufacturer. Mandatory if _equipmentType_ is `INVERTER`. Default is `0` if value not known. type: number derDevices: type: array items: type: object required: - deviceIdentifier - count - type - nominalRatedCapacity x-conditional: - nominalStorageCapacity properties: deviceIdentifier: description: Unique identifier for a single DER device or a group of DER devices with the same attributes. Does not align with CDR ID permanence standards. type: number count: description: Number of devices in the group of DER devices. type: integer x-cds-type: PositiveInteger manufacturer: description: The name of the device manufacturer. If absent then assumed to be "unknown". type: string modelNumber: description: The model number of the device. If absent then assumed to be "unknown". type: string status: description: Code used to indicate the status of the device. This will be used to identify if an inverter is active or inactive or decommissioned. type: string enum: - ACTIVE - INACTIVE - DECOMMISSIONED type: description: Used to indicate the primary technology used in the DER device. type: string enum: - FOSSIL - HYDRO - WIND - SOLAR_PV - RENEWABLE - GEOTHERMAL - STORAGE - OTHER subtype: description: Used to indicate the primary technology used in the DER device. This field is also used to record for example the battery chemistry, or the type of PV panel. It is also used to record if a battery is contained in an electric vehicle connected in a vehicle-to-grid arrangement. If absent then assumed to be "other". type: string nominalRatedCapacity: description: Maximum output in kVA that is listed in the product specification by the manufacturer. This refers to the capacity of each unit within the device group. Default is `0` if value not known. type: number nominalStorageCapacity: description: Maximum storage capacity in kVAh. This refers to the capacity of each storage module within the device group. Mandatory if type is equal to `STORAGE`. Default is `0` if value not known. type: number Meta: type: object EnergyServicePointId: type: string description: A unique identifier for an Energy service point, generated according to [CDR ID Permanence](#id-permanence) requirements. x-cds-type: ASCIIString PrimaryResponseErrorListV1: type: object required: - errors properties: errors: description: List of errors. type: array items: $ref: '#/components/schemas/PrimaryErrorV1' MetaPaginated: type: object required: - totalPages - totalRecords properties: totalRecords: type: integer description: The total number of records in the full set. See [pagination](#pagination). x-cds-type: NaturalNumber totalPages: type: integer description: The total number of pages in the full set. See [pagination](#pagination). x-cds-type: NaturalNumber Links: type: object required: - self properties: self: type: string description: Fully qualified link that generated the current response document. x-cds-type: URIString EnergyDerListResponse: type: object required: - data - links - meta properties: data: type: object required: - derRecords properties: derRecords: description: Array of meter reads. type: array items: $ref: '#/components/schemas/EnergyDerRecord' links: $ref: '#/components/schemas/LinksPaginated' meta: $ref: '#/components/schemas/MetaPaginated' PrimaryErrorV1: type: object allOf: - type: object properties: isSecondaryDataHolderError: type: boolean description: Indicates the error was propagated from a designated secondary data holder. default: false - $ref: '#/components/schemas/ErrorV2' ErrorV2: type: object required: - code - title - detail x-conditional: - meta properties: code: type: string description: The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the _meta_ object. Otherwise, the value is the error code URN. title: type: string description: A short, human-readable summary of the problem that **MUST NOT** change from occurrence to occurrence of the problem represented by the error code. detail: type: string description: A human-readable explanation specific to this occurrence of the problem. meta: type: object x-conditional: - urn description: Additional data for customised error codes. properties: urn: type: string description: The CDR error code URN which the application-specific error code extends. Mandatory if the error _code_ is an application-specific error rather than a standardised error code. RequestServicePointIdListV1: type: object required: - data properties: data: type: object required: - servicePointIds properties: servicePointIds: type: array description: Array of _servicePointId_ values to obtain data for. items: $ref: '#/components/schemas/EnergyServicePointId' meta: $ref: '#/components/schemas/Meta' EnergyDerDetailResponse: type: object required: - data - links properties: data: $ref: '#/components/schemas/EnergyDerRecord' links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/Meta' headers: XV: description: The [payload version](#response-headers) that the endpoint has responded with. required: true schema: type: string XFAPIInteractionId: description: An **[[RFC4122]](#nref-RFC4122)** UUID used as a correlation id. If provided, the data holder **MUST** play back this value in the _x-fapi-interaction-id_ response header. If not provided a **[[RFC4122]](#nref-RFC4122)** UUID value is required to be provided in the response header to track the interaction. required: true schema: type: string requestBodies: RequestServicePointIds: description: Request payload containing a list of _servicePointId_ values to obtain data for. content: application/json: schema: $ref: '#/components/schemas/RequestServicePointIdListV1' required: true