@epilot/metering-client

{ "openapi": "3.0.3", "info": { "title": "Metering API", "version": "1.0.0" }, "tags": [ { "name": "ECP", "description": "APIs defined for a portal user" }, { "name": "ECP Admin", "description": "APIs defined for a ECP Admin" }, { "name": "meter_schema", "x-displayName": "Meter", "description": "<SchemaDefinition schemaRef=\"#/components/schemas/Meter\" />\n" }, { "name": "meter_counter_schema", "x-displayName": "Meter Counter", "description": "<SchemaDefinition schemaRef=\"#/components/schemas/MeterCounter\" />\n" } ], "x-tagGroups": [ { "name": "APIs", "tags": [ "ECP", "ECP Admin" ] }, { "name": "Schemas", "tags": [ "meter_schema", "meter_counter_schema" ] } ], "security": [ { "EpilotAuth": [] }, { "PortalAuth": [] }, { "EitherAuth": [] } ], "paths": { "/v1/metering/meter": { "get": { "operationId": "getCustomerMeters", "summary": "Get Customer Meters", "description": "Retrieves all meters related to a customer.", "tags": [ "ECP" ], "security": [ { "PortalAuth": [] } ], "responses": { "200": { "description": "Customer meters retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Meter" }, { "type": "object", "properties": { "journey_actions": { "$ref": "#/components/schemas/JourneyActions" } } }, { "type": "object", "properties": { "last_reading": { "type": "string", "example": "2022-10-10T00:00:00.000Z", "description": "The timestamp of the last reading" }, "current_consumption": { "type": "number", "example": 100.5, "description": "The current consumption of the meter" } } } ] } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/contract/meters/{contract_id}": { "get": { "operationId": "getMetersByContractId", "summary": "getMetersByContractId", "description": "Retrieves all meters related to a contract.", "tags": [ "ECP" ], "security": [ { "PortalAuth": [] } ], "parameters": [ { "in": "path", "name": "contract_id", "schema": { "$ref": "#/components/schemas/EntityId" }, "required": true, "description": "The ID of the Contract." } ], "responses": { "200": { "description": "Meters related to the contract retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Meter" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/meter/{id}": { "patch": { "operationId": "updateMeter", "summary": "Update Meter", "description": "Updates the details of a meter.", "tags": [ "ECP" ], "security": [ { "PortalAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "$ref": "#/components/schemas/EntityId" }, "required": true, "description": "The ID of the meter." } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "responses": { "200": { "description": "Meter updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Meter" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestUpdateMeter" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "getMeter", "summary": "Get Meter", "description": "Retrieves the details of a meter.", "tags": [ "ECP" ], "security": [ { "PortalAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "schema": { "$ref": "#/components/schemas/EntityId" }, "required": true, "description": "The ID of the meter." } ], "responses": { "200": { "description": "Meter retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "entity": { "$ref": "#/components/schemas/Meter" }, "journey_actions": { "$ref": "#/components/schemas/JourneyActions" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/EntityItem" } } } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/counter": { "get": { "operationId": "getMeterCounters", "summary": "Get Meter Counters", "description": "Retrieves all counters for a given meter.", "tags": [ "ECP" ], "security": [ { "PortalAuth": [] } ], "parameters": [ { "in": "query", "name": "meter_id", "required": true, "schema": { "$ref": "#/components/schemas/EntityId" } } ], "responses": { "200": { "description": "Counters retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeterCounter" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/counter/{counter_id}": { "get": { "operationId": "getCounterDetails", "summary": "Get Counter Details", "description": "Retrieves the details of a meter counter.", "tags": [ "ECP" ], "security": [ { "PortalAuth": [] } ], "parameters": [ { "in": "path", "name": "counter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the counter." } ], "responses": { "200": { "description": "Counter details retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeterCounter" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/reading": { "post": { "operationId": "createMeterReading", "summary": "Create Meter Reading", "description": "Inserts a new meter reading.", "tags": [ "ECP Admin", "ECP" ], "security": [ { "EitherAuth": [] } ], "requestBody": { "description": "Meter reading payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterReading" } } } }, "responses": { "200": { "description": "Meter reading created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeterReading" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestCreateMeterReading" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/readings": { "post": { "operationId": "createMeterReadings", "summary": "Create Meter Readings", "description": "Inserts multiple meter readings at once. Limited to 100 readings per request.", "tags": [ "ECP Admin" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "in": "query", "name": "async", "description": "Don't wait for the reading to become available in GetReadings API. Useful for large migrations", "required": false, "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/ActivityIdQueryParam" }, { "$ref": "#/components/parameters/SkipValidationQueryParam" } ], "requestBody": { "description": "Meter readings payload. Limited to 100 readings per request.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "readings": { "type": "array", "items": { "$ref": "#/components/schemas/MeterReading" } } } } } } }, "responses": { "200": { "description": "Meter readings created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeterReading" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestCreateMeterReadings" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/metering/readings": { "post": { "operationId": "batchWriteMeterReadings", "summary": "Batch Write Readings", "description": "Upserts/Deletes multiple meter readings at once. Limited to 100 readings per request.", "tags": [ "ECP Admin" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "in": "query", "name": "async", "description": "Don't wait for the reading to become available in GetReadings API. Useful for large migrations", "required": false, "schema": { "type": "boolean", "default": true } }, { "$ref": "#/components/parameters/SkipValidationQueryParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" } ], "requestBody": { "description": "Meter readings payload. Limited to 100 readings per request.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "readings": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/MeterReading" }, { "properties": { "operation": { "type": "string", "enum": [ "create", "update", "delete" ], "default": "create" } } } ] } } } } } } }, "responses": { "200": { "description": "Meter readings created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MeterReading" } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestCreateMeterReadings" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/reading/submission": { "post": { "operationId": "createMeterReadingFromSubmission", "summary": "Create Meter Reading from Submission", "description": "Creates a reading from a journey submission.", "tags": [ "ECP Admin" ], "security": [ { "EpilotAuth": [] } ], "requestBody": { "description": "Meter reading payload.", "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "org_id": { "type": "string", "example": "123", "description": "ID of the organization" }, "entity": { "type": "object", "additionalProperties": true, "properties": { "_org": { "type": "string", "example": "123", "description": "ID of the organization" }, "meterReadings": { "type": "array", "items": { "$ref": "#/components/schemas/SubmissionMeterReading" } } } } } } } } }, "responses": { "200": { "description": "Meter reading created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Successfully Processed" ] } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestCreateMeterReadingFromSubmission" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/allowed/reading/{meter_id}": { "get": { "operationId": "getAllowedReadingForMeter", "summary": "getAllowedReadingForMeter", "description": "Get allowed reading for the given meter", "tags": [ "ECP Admin", "ECP" ], "security": [ { "EitherAuth": [] } ], "parameters": [ { "in": "path", "name": "meter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the meter." }, { "in": "query", "name": "timestamp", "required": false, "description": "If not provided, the system will default to now.", "schema": { "type": "string", "example": "2022-10-01T10:10:00.000Z" } } ], "responses": { "200": { "description": "Recent reading for the meter fetched successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "counter_id": { "$ref": "#/components/schemas/Id" }, "min_value": { "type": "number", "description": "Minimum allowed reading value for the meter" }, "max_value": { "type": "number", "description": "Maximum allowed reading value for the meter" } } } } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/reading/with-meter": { "post": { "operationId": "createReadingWithMeter", "summary": "Create Reading with Meter", "description": "Creates a reading along with a meter.", "tags": [ "ECP Admin" ], "security": [ { "EpilotAuth": [] } ], "requestBody": { "description": "Meter reading payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadingWithMeter" } } } }, "responses": { "200": { "description": "Reading with meter created successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeterReading" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestCreateReadingWithMeter" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/metering/reading/{meter_id}/{counter_id}": { "get": { "operationId": "getReadingsByInterval", "summary": "Get Readings by Interval", "description": "Retrieves all readings specified in an interval.\nIf the start_date and end_date are equal, then it returns the readings of the specified date.\nThe start_date should be less than or equal to the end_date.\n", "tags": [ "ECP Admin", "ECP" ], "security": [ { "EitherAuth": [] } ], "parameters": [ { "in": "path", "name": "meter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the meter." }, { "in": "path", "name": "counter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the counter." }, { "in": "query", "name": "start_date", "required": false, "description": "If not provided, the system will default to 2000-01-01.", "schema": { "type": "string", "example": "2022-10-01" } }, { "in": "query", "name": "end_date", "required": false, "description": "If not provided, the system will default to today's date.", "schema": { "type": "string", "example": "2022-10-10" } }, { "in": "query", "name": "direction", "required": false, "schema": { "$ref": "#/components/schemas/Direction" } }, { "in": "query", "name": "size", "description": "Returns the first n results after the specified offset (from).\nIf this value is provided as -1, then it returns all results at once.\n", "required": false, "schema": { "type": "number", "example": 20, "default": 20 } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "number", "example": 0, "default": 0 } }, { "in": "query", "name": "type", "required": true, "description": "Since meter readings are cumulative, users may need to request actual consumptions, which are the difference between consecutive measurements.\nIf this value is provided as \"cumulative\", then actual readings will be returned.\nIf this value is provided as \"relative\", then actual consumption will be returned.\n", "schema": { "type": "string", "default": "cumulative", "enum": [ "cumulative", "relative" ] } }, { "in": "query", "name": "sort", "required": false, "schema": { "type": "string", "default": "asc", "enum": [ "asc", "desc" ] }, "description": "If this value is provided as \"asc\", then the results will be sorted by the timestamp field in ascending order.\nIf this value is provided as \"desc\", then the results will be sorted by the timestamp field in descending order.\n" } ], "responses": { "200": { "description": "Readings retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/MeterReading" } }, "hits": { "type": "number", "example": 120 }, "firstRecordCreatedAt": { "type": "string", "example": "2022-10-01T20:00:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateMeterReading", "summary": "Update Meter Reading", "description": "Updates a meter reading.", "tags": [ "ECP Admin" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "in": "path", "name": "meter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the meter entity." }, { "in": "path", "name": "counter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the counter entity." }, { "in": "query", "name": "timestamp", "required": true, "description": "The timestamp when the reading was created.", "schema": { "type": "string", "example": "2022-10-01T20:00:00.000Z" } } ], "requestBody": { "description": "Update meter reading payload.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeterReading" } } } }, "responses": { "200": { "description": "Meter reading updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MeterReading" } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequestUpdateMeterReading" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteMeterReading", "summary": "Delete Meter Reading", "description": "Deletes a meter reading.", "tags": [ "ECP Admin" ], "security": [ { "EpilotAuth": [] } ], "parameters": [ { "in": "path", "name": "meter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the meter entity." }, { "in": "path", "name": "counter_id", "schema": { "$ref": "#/components/schemas/Id" }, "required": true, "description": "The ID of the counter entity." }, { "in": "query", "name": "timestamp", "required": true, "description": "The timestamp when the reading was created.", "schema": { "type": "string", "example": "2022-10-01T20:00:00.000Z" } } ], "responses": { "200": { "description": "Meter reading deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "meterId": { "$ref": "#/components/schemas/Id" }, "counterId": { "$ref": "#/components/schemas/Id" }, "timestamp": { "type": "string", "example": "2022-10-01T20:00:00.000Z" } } }