openapi: 3.2.0 info: title: Reposit Power Market Power Station API description: 'Documentation for the Reposit Power Market API. Used by fleet.repositpower.com and related services. Please review our [versioning and support policy](https://gist.github.com/mleonard87/d5ed0a82760ceb75adc7df0d62bf9c31) before using the API. ' contact: url: https://www.repositpower.com/ email: api@repositpower.com version: 1.0.0 servers: - url: https://marketapi.repositpower.com/ tags: - name: Power Station description: API end-points related to powerstations. paths: /api/powerstations: get: tags: - Power Station summary: All Power Stations description: Returns a list of power stations associated with the currently authenticated user's organisation. parameters: - name: includePredictions in: query description: Optional. Set to `true` to include powerstation predictions in the response. schema: type: string enum: - 'true' responses: 200: description: OK content: application/json: schema: type: object example: data: - id: e7430ccb21644d7b9e0a443933f25c7f name: New Powerstation on dmarket namePlate: capacity: 17.1 power: 13 nodes: - d4c58e243e694bba9e57cbdf42970faf - 5320123eac5e4fd5baaea0bf442659bb - description: A sample powerstation for dispatches id: 3561817084be49c0b77d7d65903792ff name: Sample One namePlate: batteryCapacity: 29.0 batteryPower: 16.3 inverterPower: 18.5 nodes: - 5320123eac5e4fd5baaea0bf442659bb - e720e221204149ec9fa172583bcf4258 - d4c58e243e694bba9e57cbdf42970faf status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error security: - AccessToken: [] post: tags: - Power Station summary: Create Power Station description: Creates a new powerstation and returns its details. requestBody: description: The powerstation to create. content: application/json: schema: required: - name - nodes type: object properties: name: type: string description: A recognisable name to give this powerstation. description: type: string description: An option description of this powerstation type: type: string description: The type of powerstation, either STATIC for a specified list of node IDs or DYNAMIC to suply a filter. When using DYNAMIC ans supplying a filter the powerstation will automatically add any nodes that match the filter criteria. default: STATIC enum: - STATIC - DYNAMIC nodes: type: array description: An array of node IDs that belong to this powerstation if the powerstation type is STATIC. Otherwise this must be null items: type: string filters: type: object properties: postcodes: type: array description: An array of postcodes that a node can be in for it to be included in this powerstation. items: type: string state: type: string description: The state or territory that a node must be in for it to be included in this powerstation. enum: - ACT - NSW - NT - QLD - SA - TAS - VIC - WA description: When specifying a DYNAMIC powerstation type you must also supply the filters that this powerstation is built from. example: name: My First Powerstation nodes: - f7b05c5632334403ac0895959f8d00e7 - 4f0cf230c728478da0822aa7f2d1f9ef - 56af6a12ae9049298aaa38cde5781145 required: false responses: 200: description: OK content: application/json: schema: type: object properties: data: type: object properties: description: type: string id: type: string name: type: string namePlate: type: object properties: batteryCapacity: type: number batteryPower: type: number inverterPower: type: number nodes: type: array description: A list of nodes IDs that make up this powerstation. items: type: string status: type: string example: data: id: e7430ccb21644d7b9e0a443933f25c7f name: My First Powerstation namePlate: batteryCapacity: 17.1 batteryPower: 11 inverterPower: 13 nodes: - f7b05c5632334403ac0895959f8d00e7 - 4f0cf230c728478da0822aa7f2d1f9ef - 56af6a12ae9049298aaa38cde5781145 status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error security: - AccessToken: [] x-codegen-request-body-name: powerstation /api/powerstations/{powerstationId}: get: tags: - Power Station summary: Get Single Power Station description: Returns the details of the power station with the supplied UID. parameters: - name: powerstationId in: path description: The ID of the power station. required: true schema: type: string responses: 200: description: OK content: application/json: schema: type: object properties: data: type: object properties: description: type: string id: type: string name: type: string namePlate: type: object properties: capacity: type: number power: type: number nodes: type: array items: type: string status: type: string example: data: id: e7430ccb21644d7b9e0a443933f25c7f name: New Powerstation on dmarket namePlate: capacity: 17.1 power: 13 nodes: - d4c58e243e694bba9e57cbdf42970faf - 5320123eac5e4fd5baaea0bf442659bb status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error 404: description: Invalid powerstation UID specified. content: application/json: schema: type: object example: error: Powerstation e7430ccb21644d7b9e0a443933f25c7f not found status: ERROR security: - AccessToken: [] put: tags: - Power Station summary: Update Power Station description: Updates an existing powerstation specified by its id and returns its details. parameters: - name: powerstationId in: path description: The ID of the power station. required: true schema: type: string requestBody: description: The powerstation to update. content: application/json: schema: required: - name - nodes type: object properties: name: type: string description: type: string description: An option description of this powerstation nodes: type: array description: A list of nodes IDs that make up this powerstation. items: type: string example: name: My First Powerstation nodes: - f7b05c5632334403ac0895959f8d00e7 - 4f0cf230c728478da0822aa7f2d1f9ef - 56af6a12ae9049298aaa38cde5781145 required: false responses: 200: description: OK content: application/json: schema: type: object properties: data: type: object properties: description: type: string id: type: string name: type: string namePlate: type: object properties: capacity: type: number power: type: number nodes: type: array items: type: string status: type: string example: data: id: e7430ccb21644d7b9e0a443933f25c7f name: My First Powerstation namePlate: capacity: 17.1 power: 13 nodes: - f7b05c5632334403ac0895959f8d00e7 - 4f0cf230c728478da0822aa7f2d1f9ef - 56af6a12ae9049298aaa38cde5781145 status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error 404: description: Invalid powerstation ID specified. content: application/json: schema: type: object example: error: Powerstation e7430ccb21644d7b9e0a443933f25c7f not found status: ERROR security: - AccessToken: [] x-codegen-request-body-name: powerstation delete: tags: - Power Station summary: Delete Power Station description: Deletes a powerstation with with the supplied ID. parameters: - name: powerstationId in: path description: The ID of the power station. required: true schema: type: string responses: 200: description: OK content: application/json: schema: type: object properties: status: type: string example: status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error 404: description: Invalid powerstation ID specified. content: application/json: schema: type: object example: error: Powerstation e7430ccb21644d7b9e0a443933f25c7f not found status: ERROR security: - AccessToken: [] /api/powerstations/{powerstationId}/data: get: tags: - Power Station summary: Data - Downsampled description: Return stored metrics for this powerstation or its nodes by downsampling. parameters: - name: powerstationId in: path description: The ID of the power station. required: true schema: type: string - name: metrics in: query description: 'This returns downsampled data of metrics for this powerstation. Timestamps in the response refer to the start of the period. The metrics to retreive as a comma separated list of any combination of the following: - meterVoltage - The average voltage (V) across all phases as measured at the meter/grid - meterFrequence - The average frequency (Hz) across all phases as measured at the meter/grid - meterPower - The total (sum) real power (kW) across all phases as measured at the meter/grid - meterReactivePower - The total (sum) reactive power (var) across all phases as measure at the meter/grid - solarPower - The total (sum) real power (kW) across all solar phases being generated by the PV array - solarReactivePower - The total (sum) reactive power (var) across all solar phases being generated by the PV array - remainingCharge - The total (sum) remaining charge (W) of the all batteries attached to this system - batteryPower - The total (sum) real power (kW) measured at the battery of all batteries attached to this system - inverterReactivePower - The total (sum) reactive power (var) measured at the inverter - inverterApparentPower - The total (sum) apparent power (kW) measured at the inverter - meterCurrent - The total (sum) current (Amp) measured at the meter/grid All real power measurements follow a sink convention, while all reactive power measurements follow a source convention. Apparent power is always positive. If ?format=nodes is specified then you may also request the data to be split by phases by adding a phase letter after the metric name, for example `meterVoltage{a}`. These can be combined to request multiple phases, for example `meterVoltage{a|b}`. Or you can request all phases with an asterix, for example `meterVoltage{*}`. Note that `meterVoltage{*}` is equivalent to `meterVoltage{a|b|c}`. If a phase is specified the above average/sum aggregation will not be applied and instead you will get back the value for just the specified phase(s). Phase suffixes may be used on the following metrics: meterVoltage, meterFrequency, meterPower, meterReactivePower, solarPower, solarReactivePower. Please note that phases are currently arbitrary - we cannot determine which phase is red/white/blue. For all single phase installations the data will be available on phase a. ' required: true schema: type: string - name: start in: query description: The start timestamp of the period of data you wish to retreive schema: type: integer - name: end in: query description: The end timestamp of the period of data you wish to retreive schema: type: integer - name: interval in: query description: The downsampling interval in seconds schema: type: integer - name: format in: query description: The format you wish to retrieve the results, either `powerstation` or `nodes`. When using nodes, requests are limited to a 6 hour window of data; for powerstation, requests are limited to a 1 week window of data. schema: type: string default: powerstation enum: - powerstation - nodes - name: fill in: query description: The fill policy to use for empty values. By default any empty values for a deployment (i.e. a missing chuck of data) are ommitted. Specify `fill=null` to return all times with null values if the data is missing. Only `null` is supported. schema: type: string enum: - null responses: 200: description: OK content: application/json: schema: type: object By powerstation: example: data: - meterPower{a}: 1505109600: 0.3857383972607584 1505111400: 0.3806250010513597 - meterPower{b}: 1505109600: 0.3849693243306107 1505111400: 0.3857383972607584 - meterVoltage: 1505109600: 244.3849693243306 1505111400: 245.38573839726075 status: OK By nodes: example: data: - meterPower{a}: d4c58e243e694bba9e57cbdf42970faf: 1505109600: 0.3857383972607584 1505111400: 0.3806250010513597 e720e221204149ec9fa172583bcf4258: 1505109600: 0.3849693243306107 1505111400: 0.3580208346247673 - meterPower{b}: d4c58e243e694bba9e57cbdf42970faf: 1505109600: 0.3857383972607584 1505111400: 0.3806250010513597 e720e221204149ec9fa172583bcf4258: 1505109600: 0.3849693243306107 1505111400: 0.3580208346247673 - meterVoltage: d4c58e243e694bba9e57cbdf42970faf: 1505109600: 244.38573839726075 1505111400: 244.38062500105136 e720e221204149ec9fa172583bcf4258: 1505109600: 245.3849693243306 1505111400: 245.35802083462477 status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error security: - AccessToken: [] /api/powerstations/{powerstationId}/data/raw: get: tags: - Power Station summary: Data - Raw description: Return stored metrics for this powerstation or its nodes without applying any downsampling. parameters: - name: powerstationId in: path description: The ID of the power station. required: true schema: type: string - name: metrics in: query description: 'This returns raw data of metrics for this powerstation as collected by each device. Timestamps in the response refer to the time at which the data was sampled. No guarantees can be made about aligned data. e.g. meterPower may be collected at slightly different times per phases, and meterPower might be collected at a different time than meterVoltage. The metrics to retreive as a comma separated list of any combination of the following: - meterVoltage - The average voltage (V) across all phases as measured at the meter/grid - meterFrequence - The average frequency (Hz) across all phases as measured at the meter/grid - meterPower - The total (sum) real power (kW) across all phases as measured at the meter/grid - meterReactivePower - The total (sum) reactive power (var) across all phases as measure at the meter/grid - solarPower - The total (sum) real power (kW) across all solar phases being generated by the PV array - solarReactivePower - The total (sum) reactive power (var) across all solar phases being generated by the PV array - remainingCharge - The total (sum) remaining charge (W) of the all batteries attached to this system - batteryPower - The total (sum) real power (kW) measured at the battery of all batteries attached to this system - inverterReactivePower - The total (sum) reactive power (var) measured at the inverter - inverterApparentPower - The total (sum) apparent power (kW) measured at the inverter - meterCurrent - The total (sum) current (Amp) measured at the meter/grid All real power measurements follow a sink convention, while all reactive power measurements follow a source convention. Apparent power is always positive. If ?format=nodes is specified then you may also request the data to be split by phases by adding a phase letter after the metric name, for example `meterVoltage{a}`. These can be combined to request multiple phases, for example `meterVoltage{a|b}`. Or you can request all phases with an asterix, for example `meterVoltage{*}`. Note that `meterVoltage{*}` is equivalent to `meterVoltage{a|b|c}`. If a phase is specified the above average/sum aggregation will not be applied and instead you will get back the value for just the specified phase(s). Phase suffixes may be used on the following metrics: meterVoltage, meterFrequency, meterPower, meterReactivePower, solarPower, solarReactivePower. Please note that phases are currently arbitrary - we cannot determine which phase is red/white/blue. For all single phase installations the data will be available on phase a. ' required: true schema: type: string - name: start in: query description: The start timestamp of the period of data you wish to retreive schema: type: integer - name: end in: query description: The end timestamp of the period of data you wish to retreive schema: type: integer - name: format in: query description: The format you which to retreive the results, either `powerstation` or `nodes` schema: type: string default: powerstation enum: - powerstation - nodes responses: 200: description: OK content: application/json: schema: type: object By powerstation: example: data: - meterPower{a}: 1505108933: 0.3857383972607584 1505108937: 0.3806250010513597 - meterPower{b}: 1505108944: 0.3849693243306107 - meterVoltage: 1505108933: 243.3849693243306 1505108937: 244.3849693243306 1505108941: 245.38573839726075 status: OK By nodes: example: data: - meterPower{a}: d4c58e243e694bba9e57cbdf42970faf: 1505108933: 0.3857383972607584 1505108937: 0.3806250010513597 e720e221204149ec9fa172583bcf4258: 1505108934: 0.3849693243306107 1505108938: 0.3580208346247673 - meterPower{b}: d4c58e243e694bba9e57cbdf42970faf: 1505108933: 0.3857383972607584 1505108937: 0.3806250010513597 1505108941: 0.3806250010513597 1505108943: 0.3806250010513597 e720e221204149ec9fa172583bcf4258: 1505108934: 0.3849693243306107 1505108936: 0.3580208346247673 1505108939: 0.3580208346247673 - meterVoltage: d4c58e243e694bba9e57cbdf42970faf: 1505108937: 244.38573839726075 1505108940: 244.38062500105136 e720e221204149ec9fa172583bcf4258: 1505108937: 245.3849693243306 status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error security: - AccessToken: [] /api/powerstations/{powerstationId}/data/latest: get: tags: - Power Station summary: Data - Latest description: Returns the latest value of the metrics for the powerstation or nodes up to a maximum age of data. parameters: - name: powerstationId in: path description: The ID of the power station. required: true schema: type: string - name: metrics in: query description: 'This returns the single, most recent (up to a given max age) data point we have for each metric. No timestamps are given for this data but you can be sure that no data point will be older than the maxAge query parameter. If you require specific timestamps please consider using the `/data` or `/data/raw` end points. The metrics to retreive as a comma separated list of any combination of the following: - meterVoltage - The average voltage (V) across all phases as measured at the meter/grid - meterFrequence - The average frequency (Hz) across all phases as measured at the meter/grid - meterPower - The total (sum) real power (kW) across all phases as measured at the meter/grid - meterReactivePower - The total (sum) reactive power (var) across all phases as measure at the meter/grid - solarPower - The total (sum) real power (kW) across all solar phases being generated by the PV array - solarReactivePower - The total (sum) reactive power (var) across all solar phases being generated by the PV array - remainingCharge - The total (sum) remaining charge (W) of the all batteries attached to this system - batteryPower - The total (sum) real power (kW) measured at the battery of all batteries attached to this system - inverterReactivePower - The total (sum) reactive power (var) measured at the inverter - inverterApparentPower - The total (sum) apparent power (kW) measured at the inverter - meterCurrent - The total (sum) current (Amp) measured at the meter/grid All real power measurements follow a sink convention, while all reactive power measurements follow a source convention. Apparent power is always positive. If ?format=nodes is specified then you may also request the data to be split by phases by adding a phase letter after the metric name, for example `meterVoltage{a}`. These can be combined to request multiple phases, for example `meterVoltage{a|b}`. Or you can request all phases with an asterix, for example `meterVoltage{*}`. Note that `meterVoltage{*}` is equivalent to `meterVoltage{a|b|c}`. If a phase is specified the above average/sum aggregation will not be applied and instead you will get back the value for just the specified phase(s). Phase suffixes may be used on the following metrics: meterVoltage, meterFrequency, meterPower, meterReactivePower, solarPower, solarReactivePower. Please note that phases are currently arbitrary - we cannot determine which phase is red/white/blue. For all single phase installations the data will be available on phase a. ' required: true schema: type: string - name: maxAge in: query description: The maximum age of the data that should be considered "latest" in seconds schema: type: integer default: 30 - name: format in: query description: The format you which to retreive the results, either `powerstation` or `nodes` schema: type: string default: powerstation enum: - powerstation - nodes responses: 200: description: OK content: application/json: schema: type: object By powerstation: example: data: - meterPower{a}: 0.3806250010513597 - meterPower{b}: 0.3849693243306107 - meterVoltage: 245.38573839726075 status: OK By nodes: example: data: - meterPower{a}: d4c58e243e694bba9e57cbdf42970faf: 0.3857383972607584 e720e221204149ec9fa172583bcf4258: 0.3580208346247673 - meterPower{b}: d4c58e243e694bba9e57cbdf42970faf: 0.3806250010513597 e720e221204149ec9fa172583bcf4258: 0.3580208346247673 - meterVoltage: d4c58e243e694bba9e57cbdf42970faf: 244.38062500105136 e720e221204149ec9fa172583bcf4258: 245.3849693243306 status: OK 401: description: Invalid access token. If the error code in the returned JSON is `expired_token`, it means you need to request a new access token through the `/auth/login/` route using your username and password. content: application/json: schema: type: object example: error: expired_token message: The token you provided has expired. status: error security: - AccessToken: [] components: securitySchemes: AccessToken: type: apiKey description: 'To authenticate you need to generate an API Key using Reposit Fleet. API Keys can be limited to whitelisted origin IP addresses for security and do not expire making them more suitable to server-to-server comms. API keys may also be revoked via Reposit Fleet. ### Creating an API Key API keys for the Reposit Market API can be generated by first logging in to [Reposit Fleet](https://fleet.repositpower.com). Once you have logged in click your username at the top right and then select "[User Settings](https://fleet.repositpower.com/user/settings)" Within the section labelled "API Keys" click the "Add API Key" button. Within the dialog that appears you will be able to name the key you are generating and specify a whitelist of IP addresses that this token is valid for. You will also need to confirm your password. When you have configured your keys settings click "Add" and your newly created key will be displayed - the key itself is not stored by Reposit and therefore this is your only opportunity to save the key securely. **Note**: The generated key authenticates as the account that you are currently logged in to Reposit Fleet for and as such will carry the same permissions. If you require a locked down account it is recommend that you create a new account for Reposit Fleet and generate the API Key for this account. ### Using an API Key Simply add `Bearer ` followed by the API key in the `Authorization` header of any request to Market API. e.g.: `Authorization: Bearer A2YWQiLCJpc3...` ### Revoking an API Key If an API Key becomes lost or is no longer required then the API Key can be revoked. Login to Reposit Fleet as the user for which you wish to revoke the API Key and proceed to [User Settings](https://fleet.repositpower.com/user/settings). From within the "API Keys" you will be able to see a table of all issued API Keys, find the API Key you wish to revoke and select the "Remove" link in the table. Once an API Key is removed it will cease to work immediately and can not be recovered or reinstated. ' name: Bearer in: header