openapi: 3.1.0 info: title: redHator API version: 0.1.0 summary: API to monitor and operate gHator devices. description: | redHator platform API. This reference describes the operations of the public API to query gHator devices, their sensors and actuators, their latest state and their historical data. Other operations of the platform are not covered. All requests are authenticated with a bearer token (see the `bearerAuth` security scheme). Responses are JSON. Successful responses include `"status": "ok"` and `"code": "0"`; errors follow the `ErrorResponse` schema. Conventions: - A property listed as required is always present in the response; `null` means that no value is available. - Decimal values are serialized as strings to preserve precision. - Timestamps are UTC, ISO 8601. # Authentication Every request must send a credential of a redHator user account in the `Authorization` HTTP header, with the Bearer scheme: ``` Authorization: Bearer ``` - **API keys are the recommended credential for integrations.** A user creates them in the redHator web application (*Settings*, *API keys*). An API key starts with `tkn_`, does not expire automatically and is revoked by deleting it. The guide *Getting started with the redHator API* (see *Guides*) explains how to obtain and use one. - The API also accepts the JSON Web Tokens (JWT) that redHator issues to its users, in the same header. They expire 7 days after they are issued and are not the recommended credential for integrations. - The user identified by the credential must be active and not blocked. An invalid, expired or revoked credential, or an inactive user, results in `401` (`code` "1", `msg_code` "1"). # Permissions Permissions are evaluated for the authenticated user on each gHator. Depending on the state of the gHator and of the accounts involved, they are granted to the owner of the gHator, to users to whom the owner has delegated access, and to its installer. Each operation on a gHator requires a permission on it, stated in its description (for example `view` to read its information and `historic` for its historical data). Without it the operation returns `403` (`code` "5", `msg_code` "12"). The permissions of the user on the gHator are returned in `user_permissions` of `GET /api/v2/ghator`. # Historical data Sensors and actuators keep historical samples, queried by whole months. The guide *Working with historical data* (see *Guides*) explains the structure of the responses, their UTC times and how to convert them. servers: - url: https://www.redhator.com description: redHator API. security: - bearerAuth: [] tags: - name: gHator management description: Query gHator devices, their sensors, actuators and latest state. - name: Historical data description: Historical samples of sensors and actuators. paths: /api/v2/ghators: get: operationId: getGhators summary: List the gHators of a profile of the user tags: - gHator management description: | Returns basic information of the active gHators related to the requesting user through one profile: | `profile` | gHators returned | |---|---| | `gamo` | gHators owned by the user | | `delg` | gHators on which the owner has granted the user permissions that are still in force | | `inst` | gHators installed by the user | Use it to build lists or maps of gHators. A user can have several profiles on the same gHator (for example, an owner who also installed it): to list all the gHators of a user, call the operation once per profile and merge the results by `ghatorid`. **Behavior.** - The information is read from the last state stored in redHator; no order is sent to the gHators and the response is immediate. - The list depends only on the relationship between the user and the gHator. Being listed does not mean that the user currently has permissions on the gHator: they are evaluated by each operation, and returned in `user_permissions` of `GET /api/v2/ghator`. - `ghatorid` is a number in this response, while `GET /api/v2/ghator` and other operations return or expect it as a string. - `ghators` is `null`, not an empty array, for the `gamo` profile when the user owns no gHator. **Authentication.** Send the header `Authorization: Bearer ` (see *Authentication*). No permission on a gHator is required. **Errors** (`code` / `msg_code`): | Status | code | msg_code | Cause | |---|---|---|---| | 503 | 10 | 36 | Maintenance mode | | 401 | 1 | 1 | Invalid or expired token, or inactive user | | 400 | 3 | 3 | `profile` missing or empty | | 400 | 3 | 11 | `profile` is not a valid value | security: - bearerAuth: [] parameters: - name: profile in: query required: true description: Profile of the user that determines which gHators are returned (see the table above). schema: anyOf: - type: string enum: - gamo - delg - inst example: gamo responses: '200': description: gHators of the profile. content: application/json: schema: $ref: '#/components/schemas/GhatorsResponse' examples: owner: $ref: '#/components/examples/GhatorsOwner' noOwnedGhators: $ref: '#/components/examples/GhatorsNone' '400': description: '`profile` missing or empty (`code` "3", `msg_code` "3"), or not a valid value (`code` "3", `msg_code` "11").' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameters: $ref: '#/components/examples/MissingParameters' badParameters: $ref: '#/components/examples/BadParameters' '401': $ref: '#/components/responses/Unauthorized' '503': $ref: '#/components/responses/ServiceUnavailable' /api/v2/ghator: get: operationId: getGhator summary: Get the complete information of a gHator tags: - gHator management description: | Returns all the operational information of a gHator: device state, sensors, actuators, programs, rules and the permissions of the requesting user on the gHator. Use it when you need the state of a gHator at a given moment together with the configuration of its sensors, actuators, programs and rules. The operation is served directly by redHator from the last state received from the device; it does not send any order to the gHator and the response is immediate. **Authentication.** Send the header `Authorization: Bearer ` (see *Authentication*). **Permissions.** The user must have the `view` permission on the gHator. An owner who has not confirmed the registration of the gHator yet (`user_discharge` false) receives a reduced object instead of a 403 error. **Errors** (`code` / `msg_code`): | Status | code | msg_code | Cause | |---|---|---|---| | 400 | 3 | 3 | `ghatorid` or `ghatorserial` missing | | 401 | 1 | 1 | Invalid or expired token, or inactive user | | 403 | 5 | 12 | No `view` permission on the gHator | | 404 | 4 | 10 | `ghatorid` and `ghatorserial` do not identify the same gHator | | 424 | 6 | 14 | The gHator has no valid board version assigned | | 503 | 10 | 36 | Maintenance mode | security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/GhatorId' - $ref: '#/components/parameters/GhatorSerial' responses: '200': description: gHator information. `ghator` is the complete object, or the reduced object for an owner who has not confirmed the registration yet. content: application/json: schema: $ref: '#/components/schemas/GhatorResponse' examples: complete: $ref: '#/components/examples/GhatorFull' pendingDischarge: $ref: '#/components/examples/GhatorPendingDischarge' '400': description: '`ghatorid` or `ghatorserial` missing (`code` "3", `msg_code` "3").' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameters: $ref: '#/components/examples/GhatorMissingParameters' '401': $ref: '#/components/responses/Unauthorized' '403': description: The user has no `view` permission on the gHator (`code` "5", `msg_code` "12"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: $ref: '#/components/examples/GhatorForbidden' '404': description: '`ghatorid` and `ghatorserial` do not identify the same gHator (`code` "4", `msg_code` "10").' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: $ref: '#/components/examples/GhatorNotFound' '424': description: The gHator has no valid board version assigned (`code` "6", `msg_code` "14"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidBoardVersion: $ref: '#/components/examples/GhatorInvalidBoardVersion' '503': $ref: '#/components/responses/ServiceUnavailable' /api/v2/ghatorinf: get: operationId: getGhatorInformation summary: Get the administrative information of a gHator tags: - gHator management description: | Returns the administrative information of a gHator: its name and location, and the name, brand, model and kind of its sensors and actuators. This information is managed by redHator, not by the device. Use it to show or review the descriptive data of the installation. The operational state (values, alerts, programs, rules) is returned by `GET /api/v2/ghator`. The operation reads the information stored in redHator; it does not send any order to the gHator and the response is immediate. **Authentication.** Send the header `Authorization: Bearer ` (see *Authentication*). **Permissions.** The user must have the `view` permission on the gHator. **Errors** (`code` / `msg_code`): | Status | code | msg_code | Cause | |---|---|---|---| | 503 | 10 | 36 | Maintenance mode | | 401 | 1 | 1 | Invalid or expired token, or inactive user | | 400 | 3 | 3 | `ghatorid` or `ghatorserial` missing | | 404 | 4 | 10 | `ghatorid` and `ghatorserial` do not identify the same gHator | | 403 | 5 | 12 | No `view` permission on the gHator | security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/GhatorId' - $ref: '#/components/parameters/GhatorSerial' responses: '200': description: Administrative information of the gHator. content: application/json: schema: $ref: '#/components/schemas/GhatorInformationResponse' examples: ghatorInformation: $ref: '#/components/examples/GhatorInformation' '400': description: '`ghatorid` or `ghatorserial` missing (`code` "3", `msg_code` "3").' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameters: $ref: '#/components/examples/GhatorMissingParameters' '401': $ref: '#/components/responses/Unauthorized' '403': description: The user has no `view` permission on the gHator (`code` "5", `msg_code` "12"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: $ref: '#/components/examples/GhatorForbidden' '404': description: '`ghatorid` and `ghatorserial` do not identify the same gHator (`code` "4", `msg_code` "10").' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: $ref: '#/components/examples/GhatorNotFound' '503': $ref: '#/components/responses/ServiceUnavailable' /api/v2/confighatorpg: get: operationId: getGhatorConfiguration summary: Get the general configuration of a gHator tags: - gHator management description: | Returns the current general configuration of a gHator (time zone, working mode, network technology, batteries, sleep and check times) and the values that can be used to configure it. The operation reads the configuration stored in redHator; it does not send any order to the gHator and the response is immediate. **Behavior.** - The settings that the gHator applies (`wkmode`, `tsleep`, `tio`) are returned as reported by the device, and those sent in the last configuration as `modeup`, `tsleepup` and `tioup`. They differ while a configuration is pending (`inicialized` false). - `ghatorid` is a number in this response. - `utc_gap` of `tz_options` is the offset at the time of the request. **Authentication.** Send the header `Authorization: Bearer ` (see *Authentication*). **Permissions.** The user must have the `edit` permission on the gHator. **Errors** (`code` / `msg_code`): | Status | code | msg_code | Cause | |---|---|---|---| | 503 | 10 | 36 | Maintenance mode | | 401 | 1 | 1 | Invalid or expired token, or inactive user | | 400 | 3 | 3 | `ghatorid` or `ghatorserial` missing | | 404 | 4 | 10 | `ghatorid` and `ghatorserial` do not identify the same gHator, or the gHator is not installed, active and not suspended | | 403 | 5 | 12 | No `edit` permission on the gHator | | 424 | 6 | 14 | The gHator has no valid board version assigned | security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/GhatorId' - $ref: '#/components/parameters/GhatorSerial' responses: '200': description: General configuration of the gHator. content: application/json: schema: $ref: '#/components/schemas/GhatorConfigurationResponse' examples: configuration: $ref: '#/components/examples/GhatorConfiguration' '400': description: '`ghatorid` or `ghatorserial` missing (`code` "3", `msg_code` "3").' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameters: $ref: '#/components/examples/GhatorMissingParameters' '401': $ref: '#/components/responses/Unauthorized' '403': description: The user has no `edit` permission on the gHator (`code` "5", `msg_code` "12"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: $ref: '#/components/examples/GhatorEditForbidden' '404': description: '`ghatorid` and `ghatorserial` do not identify the same gHator, or the gHator is not available for edition (`code` "4", `msg_code` "10").' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: $ref: '#/components/examples/GhatorNotFound' notAvailable: $ref: '#/components/examples/GhatorNotAvailableForEdition' '424': description: The gHator has no valid board version assigned (`code` "6", `msg_code` "14"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidBoardVersion: $ref: '#/components/examples/GhatorInvalidBoardVersion' '503': $ref: '#/components/responses/ServiceUnavailable' /api/v2/sensorhistorical: get: operationId: getSensorHistorical summary: Get the historical samples of a sensor tags: - Historical data description: | Returns the samples stored by redHator for a sensor during a period of whole months, for example to build charts. See the guide *Working with historical data*. **Behavior.** - The period is given in UTC months: `initdate` and `enddate` (`YYYY-MM`) are both included. Months without samples are omitted from `historical`. - `historical` is grouped by month, day and time, all in UTC. The time of a sample is when redHator processed the state received from the gHator. - `ghator_offset_seconds` is the current UTC offset of the gHator. It is not valid for samples of another daylight saving period (see the guide). - Each sample is an array; its elements depend on the kind of sensor (see `SensorSample`). - `first_historical_date` and `last_historical_date` give the first and last days with samples of the sensor, also outside the requested period. - If `initdate` is later than `enddate`, the response is `200` with no samples. - The operation does not send any order to the gHator. The response time grows with the number of samples requested: request the months you need. **Authentication.** Send the header `Authorization: Bearer ` (see *Authentication*). **Permissions.** The user must have the `historic` permission on the gHator of the sensor. **Errors** (`code` / `msg_code`): | Status | code | msg_code | Cause | |---|---|---|---| | 503 | 10 | 36 | Maintenance mode | | 401 | 1 | 1 | Invalid or expired token, or inactive user | | 400 | 3 | 3 | `idsensor`, `initdate` or `enddate` missing | | 404 | 4 | 10 | The sensor does not exist, or is not installed in a gHator | | 403 | 5 | 12 | No `historic` permission on the gHator of the sensor | | 400 | 3 | 11 | `initdate` or `enddate` is not a valid `YYYY-MM` month | | 500 | | | The time zone configured for the gHator is not valid (see the `500` response) | security: - bearerAuth: [] parameters: - name: idsensor in: query required: true description: Sensor identifier (`idsensor` in `GET /api/v2/ghator`). schema: type: string pattern: ^[0-9]+$ example: '2001' - $ref: '#/components/parameters/HistoricalInitDate' - $ref: '#/components/parameters/HistoricalEndDate' responses: '200': description: Samples of the sensor in the requested months. content: application/json: schema: $ref: '#/components/schemas/SensorHistoricalResponse' examples: flowMeter: $ref: '#/components/examples/SensorHistoricalFlowMeter' digital: $ref: '#/components/examples/SensorHistoricalDigital' '400': description: A parameter is missing (`code` "3", `msg_code` "3"), or `initdate` or `enddate` is not a valid month (`code` "3", `msg_code` "11"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameters: $ref: '#/components/examples/MissingParameters' badParameters: $ref: '#/components/examples/BadParameters' '401': $ref: '#/components/responses/Unauthorized' '403': description: No `historic` permission on the gHator of the sensor (`code` "5", `msg_code` "12"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: $ref: '#/components/examples/SensorHistoricalForbidden' '404': description: The sensor does not exist or is not installed in a gHator (`code` "4", `msg_code` "10"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: $ref: '#/components/examples/SensorNotFound' '500': description: 'The time zone configured for the gHator is not valid. The error is not handled by the operation: the body is not part of this contract.' '503': $ref: '#/components/responses/ServiceUnavailable' /api/v2/actuatorhistorical: get: operationId: getActuatorHistorical summary: Get the historical samples of an actuator tags: - Historical data description: | Returns the samples stored by redHator for an actuator during a period of whole months, for example to build charts. See the guide *Working with historical data*. **Behavior.** - The period is given in UTC months: `initdate` and `enddate` (`YYYY-MM`) are both included. Months without samples are omitted from `historical`. - `historical` is grouped by month, day and time, all in UTC. The time of a sample is when redHator processed the state received from the gHator. - `ghator_offset_seconds` is the current UTC offset of the gHator. It is not valid for samples of another daylight saving period (see the guide). - Each sample is an array; its elements depend on the kind of actuator (see `ActuatorSample`). - `first_historical_date` and `last_historical_date` give the first and last days with samples of the actuator, also outside the requested period. - If `initdate` is later than `enddate`, the response is `200` with no samples. - The operation does not send any order to the gHator. The response time grows with the number of samples requested: request the months you need. **Authentication.** Send the header `Authorization: Bearer ` (see *Authentication*). **Permissions.** The user must have the `historic` permission on the gHator of the actuator. **Errors** (`code` / `msg_code`): | Status | code | msg_code | Cause | |---|---|---|---| | 503 | 10 | 36 | Maintenance mode | | 401 | 1 | 1 | Invalid or expired token, or inactive user | | 400 | 3 | 3 | `idactuator`, `initdate` or `enddate` missing | | 404 | 4 | 10 | The actuator does not exist, or is not installed in a gHator | | 403 | 5 | 12 | No `historic` permission on the gHator of the actuator | | 400 | 3 | 11 | `initdate` or `enddate` is not a valid `YYYY-MM` month | | 500 | | | The time zone configured for the gHator is not valid (see the `500` response) | security: - bearerAuth: [] parameters: - name: idactuator in: query required: true description: Actuator identifier (`idactuator` in `GET /api/v2/ghator`). schema: type: string pattern: ^[0-9]+$ example: '3001' - $ref: '#/components/parameters/HistoricalInitDate' - $ref: '#/components/parameters/HistoricalEndDate' responses: '200': description: Samples of the actuator in the requested months. content: application/json: schema: $ref: '#/components/schemas/ActuatorHistoricalResponse' examples: fluidActuator: $ref: '#/components/examples/ActuatorHistoricalValve' '400': description: A parameter is missing (`code` "3", `msg_code` "3"), or `initdate` or `enddate` is not a valid month (`code` "3", `msg_code` "11"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingParameters: $ref: '#/components/examples/MissingParameters' badParameters: $ref: '#/components/examples/BadParameters' '401': $ref: '#/components/responses/Unauthorized' '403': description: No `historic` permission on the gHator of the actuator (`code` "5", `msg_code` "12"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: forbidden: $ref: '#/components/examples/ActuatorHistoricalForbidden' '404': description: The actuator does not exist or is not installed in a gHator (`code` "4", `msg_code` "10"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: $ref: '#/components/examples/ActuatorNotFound' '500': description: 'The time zone configured for the gHator is not valid. The error is not handled by the operation: the body is not part of this contract.' '503': $ref: '#/components/responses/ServiceUnavailable' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: '`Authorization: Bearer `. The credential is a redHator API key (`tkn_…`) created by the user in the web application (recommended for integrations; it does not expire and is revoked by deleting it), or a JSON Web Token issued by redHator (valid for 7 days). The user must be active and not blocked.' schemas: Actuator: type: object required: - idactuator - noutput - name - status - which_change - who_change - status_change_date - utc_date_data - status_change_time - waitingxchange - is_master - slaves - gap_master - kind - fluid properties: idactuator: type: integer description: Actuator identifier. noutput: type: integer description: Output number of the gHator where the actuator is installed. name: type: - string - 'null' description: Custom name of the actuator. status: type: integer enum: - 0 - 1 description: 1 activated (counter-normal state), 0 deactivated. which_change: type: - string - 'null' enum: - '0' - '1' - '2' - '3' - '4' - '5' - null description: 'Kind of action that caused the current state: "0" normal state, "1" program, "2" manual, "3" rule, "4" predefined alert, "5" device internal security.' who_change: type: - integer - 'null' description: Program or rule identifier when `which_change` is "1" or "3". status_change_date: type: 'null' deprecated: true description: Used by gHator versions below 3.0. Always null. utc_date_data: $ref: '#/components/schemas/NullableDateTimeUtc' description: Server UTC time when `status_change_time` was computed. status_change_time: type: - integer - 'null' description: Seconds left until the actuator returns to its normal state. gHator 3.0 or later. waitingxchange: type: boolean description: True if, in the last status reading, the gHator was changing the state of the actuator. `status_change_time` may be 0 with `status` 1 while the change completes. is_master: type: boolean description: True if the actuator is a master. gHator 3.0 or later. slaves: type: array description: Identifiers of the slave actuators of a master. items: type: integer gap_master: type: - integer - 'null' description: Seconds the master waits before/after its slaves when the master mechanism is enabled. kind: $ref: '#/components/schemas/ActuatorKind' fluid: description: Fluid-flow data. Empty object for actuators not related to fluid flow. oneOf: - $ref: '#/components/schemas/FluidActuator' - type: object maxProperties: 0 additionalProperties: false ActuatorHistoricalResponse: type: object required: - status - code - idactuator - noutput - name - kind - first_historical_date - last_historical_date - init_requested_date - end_requested_date - ghator_offset_seconds - historical properties: status: const: ok code: const: '0' idactuator: type: integer description: Actuator identifier. noutput: type: - integer - 'null' description: Output number of the gHator where the actuator is installed. name: type: - string - 'null' description: Custom name of the actuator. kind: $ref: '#/components/schemas/ActuatorKind' first_historical_date: $ref: '#/components/schemas/HistoricalDayOrZero' description: First day with stored samples of the actuator (`YYYYMMDD`, UTC), or 0 if there are none. last_historical_date: $ref: '#/components/schemas/HistoricalDayOrZero' description: Last day with stored samples of the actuator (`YYYYMMDD`, UTC), or 0 if there are none. init_requested_date: $ref: '#/components/schemas/HistoricalMonth' description: First month of the requested period (`initdate`), as `YYYYMM`. end_requested_date: $ref: '#/components/schemas/HistoricalMonth' description: Last month of the requested period (`enddate`), as `YYYYMM`. ghator_offset_seconds: $ref: '#/components/schemas/GhatorOffsetSeconds' historical: description: Samples of the requested months, grouped by month, day and time (UTC). The time of a sample is when redHator processed the state received from the gHator. type: object propertyNames: $ref: '#/components/schemas/HistoricalMonthKey' additionalProperties: type: object propertyNames: $ref: '#/components/schemas/HistoricalDayKey' additionalProperties: type: object propertyNames: $ref: '#/components/schemas/HistoricalTimeKey' additionalProperties: $ref: '#/components/schemas/ActuatorSample' additionalProperties: false ActuatorKind: type: object required: - id - description - related_to - normal_state properties: id: type: integer description: Actuator kind identifier. description: type: - string - 'null' related_to: type: - string - 'null' enum: - fluid - onoff - null description: '"fluid" for fluid flow actuators, "onoff" for other actuators.' normal_state: type: - boolean - 'null' description: Normal state of the actuator. True open, false closed. additionalProperties: false ActuatorSample: type: array description: | One sample of an actuator: `[status, afmv, afv, origin]`. Samples stored by older versions of redHator can have only the first three elements. 1. `status`: true activated (counter-normal state), false deactivated. 2. `afmv`: fluid actuators, volume measured by the linked flow meter (see `GET /api/v2/ghator`), as a decimal string. 3. `afv`: fluid actuators, volume associated with the defined flow, as a decimal string. 4. `origin`: code of the event that produced the sample. Informative; its values are not described in this documentation. minItems: 1 maxItems: 4 prefixItems: - type: - boolean - 'null' - type: - string - number - 'null' - type: - string - number - 'null' - type: - integer - 'null' Coordinates: type: array description: Location of the gHator as [latitude, longitude], each serialized as a string in decimal degrees. Empty array if not defined. items: type: string maxItems: 2 ErrorResponse: type: object description: Error envelope returned by every redHator API. `code` is the error category and `msg_code` the specific reason; clients must rely on the HTTP status, `code` and `msg_code`. `message` is informative English text and may differ between operations for the same `msg_code`. required: - message - status - code - msg_code properties: message: type: string description: Informative message. Not part of the contract. status: const: error code: type: string description: Error category (e.g. "3" missing parameters, "4" not found, "5" forbidden). msg_code: type: string description: Error reason code, used by clients to show localized messages. additionalProperties: true FlowmeterAlerts: type: object required: - leak_alert - leak_alert_start_date - noflow_alert - noflow_alert_start_date - cmax_day_alert - flow_alert - flow_alert_start_date - cmax_month_alert - cmin_day_alert properties: leak_alert: type: boolean description: True if the leak alert is triggered. leak_alert_start_date: $ref: '#/components/schemas/NullableDateTimeUtc' noflow_alert: type: boolean description: True if no flow is detected. gHator 3.0 or later. noflow_alert_start_date: $ref: '#/components/schemas/NullableDateTimeUtc' cmax_day_alert: type: boolean description: True if the maximum daily consumption threshold has been reached. flow_alert: type: boolean description: True if an instant flow threshold is exceeded. gHator 3.0 or later. flow_alert_start_date: $ref: '#/components/schemas/NullableDateTimeUtc' cmax_month_alert: type: boolean description: True if the maximum monthly consumption threshold has been reached. cmin_day_alert: type: boolean description: True if the minimum daily consumption has not been reached. additionalProperties: false FlowmeterAlertsConfig: type: object description: Configuration of the flow meter alerts. Fields marked as gHator 3.0 or later are null on earlier versions. The `*_min` and `*_max` limits are platform settings and may differ between environments. required: - leak_en - leak_threshold - leak_close_en - leak_close_n - leak_close_n_min - leak_close_n_max - leak_close_delay - leak_close_delay_min - leak_close_delay_max - leak_reset_t - leak_reset_t_min - leak_reset_t_max - noflow_en - noflow_delay - noflow_delay_min - noflow_delay_max - cmax_day_en - cmax_day_threshold - flow_value_en - flow_more_than - flow_less_than - cmax_month_en - cmax_month_threshold_fw - cmax_month_threshold - cmin_day_en - cmin_day_threshold properties: leak_en: type: boolean description: True if the leak alert is enabled. leak_threshold: $ref: '#/components/schemas/NullableDecimalString' description: Volume, in `magnitude` units, that triggers the leak alert. leak_close_en: type: boolean description: True if the automatic deactivation of outputs on leak is enabled. gHator 3.0 or later. leak_close_n: type: - integer - 'null' description: Number of deactivation attempts (between `leak_close_n_min` and `leak_close_n_max`). leak_close_n_min: type: integer leak_close_n_max: type: integer leak_close_delay: type: - integer - 'null' description: Seconds between deactivation attempts. leak_close_delay_min: type: integer description: Seconds. leak_close_delay_max: type: integer description: Seconds. leak_reset_t: type: - integer - 'null' description: Seconds without pulses that reset the leak alert. leak_reset_t_min: type: integer description: Seconds. leak_reset_t_max: type: integer description: Seconds. noflow_en: type: boolean description: True if the no-flow alert is enabled. gHator 3.0 or later. noflow_delay: type: - integer - 'null' description: Seconds without flow that trigger the no-flow alert. noflow_delay_min: type: integer description: Seconds. noflow_delay_max: type: integer description: Seconds. cmax_day_en: type: boolean description: True if the maximum daily consumption alert is enabled. cmax_day_threshold: $ref: '#/components/schemas/NullableDecimalString' description: Maximum daily consumption, in `magnitude` units. flow_value_en: type: boolean description: True if the instant flow alert is enabled. gHator 3.0 or later. flow_more_than: $ref: '#/components/schemas/NullableDecimalString' description: Upper instant flow threshold, in `magnitude` per hour. flow_less_than: $ref: '#/components/schemas/NullableDecimalString' description: Lower instant flow threshold, in `magnitude` per hour. cmax_month_en: type: boolean description: True if the maximum monthly consumption alert is enabled. cmax_month_threshold_fw: $ref: '#/components/schemas/NullableDecimalString' description: First warning of the monthly consumption alert, as a fraction of `cmax_month_threshold` between 0 and 1 (e.g. "0.8" = 80 %). cmax_month_threshold: $ref: '#/components/schemas/NullableDecimalString' description: Maximum monthly consumption, in `magnitude` units. cmin_day_en: type: boolean description: True if the minimum daily consumption alert is enabled. cmin_day_threshold: $ref: '#/components/schemas/NullableDecimalString' description: Minimum daily consumption, in `magnitude` units. additionalProperties: false FlowmeterSensor: type: object required: - idsensor - ninput - idfm - name - value - inst_flow - magnitude - scale - dayconsum - monthconsum - related_actuators - alerts - alerts_config - sensor_visual_type properties: idsensor: type: integer description: Sensor identifier. ninput: type: integer description: Input number of the gHator where the sensor is installed. idfm: type: integer description: Identifier of the sensor as flow meter. name: type: - string - 'null' maxLength: 18 description: Custom name of the sensor. value: $ref: '#/components/schemas/NullableDecimalString' description: Total volume registered since the last configuration, including the initial value, in `magnitude` units. inst_flow: $ref: '#/components/schemas/NullableDecimalString' description: Instant flow in `magnitude` per hour from the last status received. gHator 3.0 or later. magnitude: type: - string - 'null' description: Volume unit of the flow meter (e.g. "m3"). scale: $ref: '#/components/schemas/NullableDecimalString' description: Volume per pulse in `magnitude` units, applied by the gHator at origin. One of 0.001, 0.002, 0.004, 0.005, 0.008, 0.01, 0.02, 0.025, 0.04, 0.05, 0.1, 0.125, 0.2, 0.25, 0.5, 1. dayconsum: type: number description: Volume measured during the current day, in `magnitude` units. monthconsum: type: number description: Volume measured during the current month, in `magnitude` units. related_actuators: type: array description: Actuators linked to the flow meter. items: type: object required: - idactuator - name properties: idactuator: type: integer name: type: - string - 'null' additionalProperties: false alerts: $ref: '#/components/schemas/FlowmeterAlerts' alerts_config: $ref: '#/components/schemas/FlowmeterAlertsConfig' sensor_visual_type: $ref: '#/components/schemas/SensorVisualType' additionalProperties: false FluidActuator: type: object required: - idfluid_actuator - category - day_consum_fm_related - total_consum_fm_related - flow - day_consum_flow_related - total_consum_flow_related - afmv_acum_last_change - afv_acum_last_change - status_change_afmv_remain - status_change_afv_remain - related_fm properties: idfluid_actuator: type: integer category: type: - string - 'null' enum: - neutral - free - null description: '"neutral" if it gives way to a system controlled by other actuators of the same gHator; "free" if it gives way to an open system.' day_consum_fm_related: $ref: '#/components/schemas/NullableDecimalString' description: Volume registered by the linked flow meter during the day while open, in its `magnitude` units. total_consum_fm_related: $ref: '#/components/schemas/NullableDecimalString' description: Volume registered by the linked flow meter since the last counter reset while open. flow: $ref: '#/components/schemas/NullableDecimalString' description: Flow defined during installation, in flow meter `magnitude` per hour. gHator 3.0 or later. day_consum_flow_related: $ref: '#/components/schemas/NullableDecimalString' description: Volume estimated from `flow` during the day while open. total_consum_flow_related: $ref: '#/components/schemas/NullableDecimalString' description: Volume estimated from `flow` since the last counter reset while open. afmv_acum_last_change: $ref: '#/components/schemas/NullableDecimalString' description: Volume registered by the linked flow meter since the last opening. gHator 3.0 or later. afv_acum_last_change: $ref: '#/components/schemas/NullableDecimalString' description: Volume estimated from `flow` since the last opening. gHator 3.0 or later. status_change_afmv_remain: $ref: '#/components/schemas/NullableDecimalString' description: Flow meter volume remaining before the actuator changes state. gHator 3.0 or later. status_change_afv_remain: $ref: '#/components/schemas/NullableDecimalString' description: Estimated volume remaining before the actuator changes state. gHator 3.0 or later. related_fm: type: object description: Linked flow meter sensor. required: - idsensor - ninput properties: idsensor: type: integer ninput: type: integer additionalProperties: false additionalProperties: false Ghator: type: object description: 'Complete operational information of a gHator: device state, sensors, actuators, programs, rules and the permissions of the requesting user. Every listed property is always present; null means that no value is available (for example, a feature not supported by the gHator version).' required: - ghatorid - ghatorserial - v_firmware - v_subfirmware - last_firm_available - v_firmware_update_trial - fail_update_trial - ghatorv - wkmode - tsleep - bat_ext_value - bat_ext_alert - bat_ext_alert_start_date - bat_int_value - bat_int_alert - bat_int_alert_start_date - ghatorname - ghatorcoor - owner - sim - user_discharge - operating - all_programs_disabled - renable_all_programs_date - all_rules_disabled - suspended - discharged - inicialized - last_read_error - last_read_date - pending_alerts - activated_rule - rules_mismatch - rules_mismatch_sent_alert_date - installation_date - sensors - actuators - programs - rules - user_permissions - master_en - sys_temp - signal_quality - net_tech_options - net_tech - com_tech properties: ghatorid: type: string pattern: ^[0-9]+$ description: gHator identifier, serialized as a string. ghatorserial: type: string description: gHator serial number. v_firmware: type: - string - 'null' description: Firmware version currently running on the gHator. v_subfirmware: type: - integer - 'null' description: Sub-firmware version. Only meaningful for gHator versions below 3.0. last_firm_available: type: - string - 'null' description: Latest firmware version registered for this gHator board version, or null if none. v_firmware_update_trial: type: - string - 'null' description: Last firmware version sent to the gHator. If `fail_update_trial` is null and this value is null, a new state has been received since the update order; if this value is not null, the result of the update is still unknown. fail_update_trial: type: - boolean - 'null' description: True if the last firmware update order failed, false if it was delivered. ghatorv: type: string pattern: ^[0-9]+(\.[0-9]+)?$ description: Board (PCB) version of the gHator, e.g. "3.0". wkmode: type: - integer - 'null' enum: - 0 - 2 - null description: Working mode reported in the last reading. 0 continuous, 2 sleep. tsleep: type: - integer - 'null' description: Minutes the gHator sleeps in sleep mode (2..1439). bat_ext_value: $ref: '#/components/schemas/NullableDecimalString' description: External battery voltage, in volts. bat_ext_alert: type: - boolean - 'null' description: True when the external battery voltage is below the threshold defined during installation. bat_ext_alert_start_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date when the external battery alert was triggered. bat_int_value: $ref: '#/components/schemas/NullableDecimalString' description: Internal battery voltage, in volts. bat_int_alert: type: - boolean - 'null' description: True when the internal battery voltage is critical. All outputs have been deactivated and activation is not allowed while the alert is active. bat_int_alert_start_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date when the internal battery alert was triggered. ghatorname: type: - string - 'null' maxLength: 30 description: Name of the gHator / installation. ghatorcoor: $ref: '#/components/schemas/Coordinates' owner: $ref: '#/components/schemas/Owner' sim: $ref: '#/components/schemas/Sim' user_discharge: type: boolean description: True if the owner has confirmed the registration of the gHator. operating: type: boolean description: True if any output is active. all_programs_disabled: type: - boolean - 'null' description: True if all programs are disabled. renable_all_programs_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date when all programs will be enabled again, if scheduled. all_rules_disabled: type: - boolean - 'null' description: True if all rules are disabled. suspended: type: boolean description: True if the use of the gHator has been suspended by an administrator. discharged: type: boolean description: True if the installer has completed the registration of the gHator. inicialized: type: boolean description: True if the gHator has applied the last configuration sent. It is false while a configuration change is pending confirmation by the device. last_read_error: type: boolean description: True if the last operation sent to the gHator failed. last_read_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date of the last successful state received from the gHator. pending_alerts: type: boolean description: True if any predefined alert is triggered. activated_rule: type: - boolean - 'null' description: True if any rule is active. rules_mismatch: type: - boolean - 'null' description: True if the rules stored on the gHator differ from those stored in redHator. rules_mismatch_sent_alert_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date when the rules mismatch was detected. installation_date: type: - string - 'null' pattern: ^[0-9]{2}/[0-9]{2}/[0-9]{4}$ description: Installation date in DD/MM/YYYY format (not ISO 8601). sensors: $ref: '#/components/schemas/Sensors' actuators: type: array description: Actuators connected to the outputs, ordered by output number. items: $ref: '#/components/schemas/Actuator' programs: type: array description: Programs of the gHator, ordered by program number (descending). items: $ref: '#/components/schemas/Program' rules: type: array description: Rules of the gHator, ordered by priority. items: $ref: '#/components/schemas/Rule' user_permissions: $ref: '#/components/schemas/UserPermissions' master_en: type: boolean description: True if the automatic action mechanism for master actuators is enabled. sys_temp: $ref: '#/components/schemas/NullableDecimalString' description: Value of the temperature sensor connected to the dedicated input of the gHator. The unit is not specified in the current sources. signal_quality: type: - integer - 'null' minimum: 0 maximum: 100 description: Quality of the SIM signal, 0..100. net_tech_options: type: array description: Network technologies that can be configured. items: $ref: '#/components/schemas/NetTechOption' net_tech: type: - integer - 'null' description: Preferred network technology to try first. See `net_tech_options`. com_tech: type: - integer - 'null' description: Network technology currently used by the gHator. See `net_tech_options`. additionalProperties: false GhatorConfigurationResponse: type: object description: Current general configuration of the gHator and the values that can be used to change it. Values ending in `up` (`modeup`, `tsleepup`, `tioup`) are those sent in the last configuration; the others are those reported by the gHator. required: - status - code - ghatorid - ghatorserial - v_firmware - ghatorv - ghatorname - discharged - installation_date - inicialized - tz - wkmode - modeup - net_tech - delay_polling - sensors_warmup - sensors_warmup_min - sensors_warmup_max - status_interval_seconds - status_interval_seconds_min - status_interval_seconds_max - battint - battext - battext_alert_en - battextthreshold - tsleep - tsleepup - tio - tioup - master_en - wkmode_options - net_tech_options - tz_options properties: status: const: ok code: const: '0' ghatorid: type: integer description: gHator identifier (a number in this response). ghatorserial: type: string v_firmware: type: - string - 'null' description: Firmware version currently running on the gHator. ghatorv: type: string description: Board (PCB) version of the gHator, e.g. "3.0". ghatorname: type: - string - 'null' discharged: type: boolean description: True if the installer has completed the registration of the gHator. installation_date: type: string pattern: ^[0-9]{2}/[0-9]{2}/[0-9]{4}$ description: Installation date in DD/MM/YYYY format (not ISO 8601). inicialized: type: - boolean - 'null' description: True if the gHator has applied the last configuration sent. tz: type: - integer - 'null' description: Code of the time zone of the gHator. See `tz_options`. wkmode: type: - integer - 'null' enum: - 0 - 2 - null description: Working mode reported in the last reading. 0 continuous, 2 sleep. modeup: type: - integer - 'null' enum: - 0 - 2 - null description: Working mode sent in the last configuration. 0 continuous, 2 sleep. net_tech: type: - integer - 'null' description: Preferred network technology to try first. See `net_tech_options`. delay_polling: type: - integer - 'null' description: Seconds the gHator takes to complete a cycle in continuous mode. sensors_warmup: type: integer description: Warm-up time of the sensors, between `sensors_warmup_min` and `sensors_warmup_max`. sensors_warmup_min: type: integer description: Minimum value accepted for `sensors_warmup` (server setting). sensors_warmup_max: type: integer description: Maximum value accepted for `sensors_warmup` (server setting). status_interval_seconds: type: - integer - 'null' description: Seconds between status reports of the gHator. status_interval_seconds_min: type: integer description: Minimum value accepted for `status_interval_seconds` (server setting). status_interval_seconds_max: type: integer description: Maximum value accepted for `status_interval_seconds` (server setting). battint: type: - boolean - 'null' description: True if an internal battery has been defined. battext: type: - boolean - 'null' description: True if an external battery has been defined. battext_alert_en: type: - boolean - 'null' description: True if the external battery alert is enabled. battextthreshold: $ref: '#/components/schemas/NullableDecimalString' description: Voltage below which the external battery alert is triggered, in volts. tsleep: type: - integer - 'null' description: Minutes the gHator sleeps in sleep mode (2..1439), as reported by the gHator. tsleepup: type: - integer - 'null' description: Sleep time sent in the last configuration, in minutes. tio: type: - integer - 'null' description: Seconds between checks of inputs and outputs in sleep mode (15..86399), as reported by the gHator. tioup: type: - integer - 'null' description: Input/output check time sent in the last configuration, in seconds. master_en: type: - boolean - 'null' description: True if the automatic action mechanism for master actuators is enabled. wkmode_options: type: object description: Working modes, keyed by code. properties: '0': const: continuous '2': const: sleep required: - '0' - '2' additionalProperties: false net_tech_options: type: array description: Network technologies that can be configured. items: $ref: '#/components/schemas/NetTechOption' tz_options: type: array description: Time zones that can be configured. items: $ref: '#/components/schemas/TimezoneOption' additionalProperties: false GhatorInformation: type: object description: 'Administrative information of a gHator, managed by redHator (not by the device): names, brands and models of its sensors and actuators, and their kinds.' required: - ghatorid - ghatorserial - ghatorname - ghatorv - ghatorcoor - sensors - actuators - user_permissions properties: ghatorid: type: string pattern: ^[0-9]+$ description: gHator identifier, serialized as a string. ghatorserial: type: string description: gHator serial number. ghatorname: type: - string - 'null' description: Name of the gHator / installation. ghatorv: type: - string - 'null' description: Board (PCB) version of the gHator, e.g. "3.0". ghatorcoor: $ref: '#/components/schemas/Coordinates' sensors: type: array description: Sensors of the gHator, ordered by input number. items: $ref: '#/components/schemas/GhatorInformationSensor' actuators: type: array description: Actuators of the gHator, ordered by output number. items: $ref: '#/components/schemas/GhatorInformationActuator' user_permissions: $ref: '#/components/schemas/UserPermissions' additionalProperties: false GhatorInformationActuator: type: object description: Administrative information of an actuator. required: - id - idactuator - tipoactuador_id - noutput - name - brand - model - kind_actuator properties: id: type: integer description: Same value as `idactuator`. idactuator: type: integer description: Actuator identifier. tipoactuador_id: type: - integer - 'null' description: Identifier of the actuator type assigned during installation. noutput: type: - integer - 'null' description: Output number of the gHator where the actuator is installed. name: type: - string - 'null' description: Custom name of the actuator. brand: type: - string - 'null' description: Brand of the actuator. model: type: - string - 'null' description: Model of the actuator. kind_actuator: type: object required: - related_to - normal_state - category properties: related_to: type: - string - 'null' enum: - fluid - onoff - null description: '"fluid" for fluid flow actuators, "onoff" for other actuators.' normal_state: type: - boolean - 'null' description: Normal state of the actuator. True open, false closed. category: type: - string - 'null' enum: - neutral - free - null description: 'Fluid actuators only (null otherwise). "neutral": gives way to a system controlled by other actuators of the same gHator; "free": gives way to an open system not controlled by other actuators.' additionalProperties: false additionalProperties: false GhatorInformationResponse: type: object required: - status - code - ghatorinf properties: status: const: ok code: const: '0' ghatorinf: $ref: '#/components/schemas/GhatorInformation' additionalProperties: false GhatorInformationSensor: type: object description: Administrative information of a sensor. `main` and `customcode` are only present for flow meters. required: - id - idsensor - tiposensor_id - ninput - name - brand - model - factor - correction - kind_sensor properties: id: type: integer description: Same value as `idsensor`. idsensor: type: integer description: Sensor identifier. tiposensor_id: type: - integer - 'null' description: Identifier of the sensor type assigned during installation. ninput: type: - integer - 'null' description: Input number of the gHator where the sensor is installed. name: type: - string - 'null' description: Custom name of the sensor. brand: type: - string - 'null' description: Brand of the sensor. model: type: - string - 'null' description: Model of the sensor. factor: $ref: '#/components/schemas/NullableDecimalString' description: Calibration factor of the sensor. Defined together with `correction`; null if the sensor has no calibration of its own. correction: $ref: '#/components/schemas/NullableDecimalString' description: Calibration correction of the sensor. Defined together with `factor`. main: type: - boolean - 'null' description: Flow meters only. True if the flow meter has been highlighted among the other flow meters. customcode: type: - string - 'null' description: Flow meters only. Custom code defined by the user. kind_sensor: type: object required: - code - description - normal_state properties: code: type: integer enum: - 0 - 1 - 2 - 3 - 4 description: 0 digital, 1 voltage, 2 current, 3 flow meter, 4 security. description: type: - string - 'null' normal_state: type: - boolean - 'null' description: Normal state of digital and security sensors. True open, false closed; null for other kinds. additionalProperties: false additionalProperties: false GhatorOffsetSeconds: type: integer description: Offset of the time zone of the gHator with respect to UTC, in seconds, at the time of the request. It is the only time zone information of the response and it does not apply to samples recorded under a different daylight saving period (see the guide *Working with historical data*). GhatorPendingDischarge: type: object description: Reduced object returned to the owner of a gHator who has no `view` permission because the registration has not been confirmed yet (`user_discharge` is false). required: - ghatorid - ghatorserial - ghatorname - ghatorcoor - owner - user_discharge - discharged - inicialized - last_read_date - user_permissions properties: ghatorid: type: string pattern: ^[0-9]+$ ghatorserial: type: string ghatorname: type: - string - 'null' ghatorcoor: $ref: '#/components/schemas/Coordinates' owner: $ref: '#/components/schemas/Owner' user_discharge: const: false discharged: type: boolean inicialized: type: boolean last_read_date: $ref: '#/components/schemas/NullableDateTimeUtc' user_permissions: $ref: '#/components/schemas/UserPermissions' additionalProperties: false GhatorResponse: type: object required: - status - code - ghator properties: status: const: ok code: const: '0' ghator: oneOf: - $ref: '#/components/schemas/Ghator' - $ref: '#/components/schemas/GhatorPendingDischarge' additionalProperties: false GhatorSummary: type: object description: Basic information of a gHator, read from the last state stored in redHator. Unlike `GET /api/v2/ghator`, `ghatorid` is a number here. required: - ghatorid - ghatorserial - ghatorv - ghatorname - ghatorcoor - user_discharge - operating - all_programs_disabled - all_rules_disabled - suspended - discharged - inicialized - last_read_error - last_read_date - tsleep - pending_alerts - activated_rule - v_firmware - v_firmware_update_trial - fail_update_trial - renable_all_programs_date - wkmode - id properties: ghatorid: type: integer description: gHator identifier (a number, not a string as in `GET /api/v2/ghator`). ghatorserial: type: - string - 'null' description: gHator serial number. ghatorv: type: - string - 'null' description: Board (PCB) version of the gHator, e.g. "3.0". ghatorname: type: - string - 'null' description: Name of the gHator / installation. ghatorcoor: $ref: '#/components/schemas/Coordinates' user_discharge: type: - boolean - 'null' description: True if the owner has confirmed the registration of the gHator. operating: type: - boolean - 'null' description: True if any output is active. all_programs_disabled: type: - boolean - 'null' description: True if all programs are disabled. all_rules_disabled: type: - boolean - 'null' description: True if all rules are disabled. suspended: type: - boolean - 'null' description: True if the use of the gHator has been suspended by an administrator. discharged: type: - boolean - 'null' description: True if the installer has completed the registration of the gHator. inicialized: type: - boolean - 'null' description: True if the gHator has applied the last configuration sent. last_read_error: type: - boolean - 'null' description: True if the last operation sent to the gHator failed. last_read_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date of the last successful state received from the gHator. tsleep: type: - integer - 'null' description: Minutes the gHator sleeps in sleep mode. pending_alerts: type: - boolean - 'null' description: True if any predefined alert is triggered. activated_rule: type: - boolean - 'null' description: True if any rule is active. v_firmware: type: - string - 'null' description: Firmware version currently running on the gHator. v_firmware_update_trial: type: - string - 'null' description: Last firmware version sent to the gHator (see `GET /api/v2/ghator`). fail_update_trial: type: - boolean - 'null' description: True if the last firmware update order failed, false if it was delivered. renable_all_programs_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date when all programs will be enabled again, if scheduled. wkmode: type: - integer - 'null' enum: - 0 - 2 - null description: Working mode reported in the last reading. 0 continuous, 2 sleep. id: type: 'null' description: Always null. Ignore it; use `ghatorid`. additionalProperties: false GhatorsResponse: type: object required: - status - code - ghators properties: status: const: ok code: const: '0' ghators: type: - array - 'null' description: gHators of the requested profile, in no guaranteed order. Empty array if there are none. `null` when the requested profile does not apply to the user (for example `gamo` for a user who owns no gHator). items: $ref: '#/components/schemas/GhatorSummary' additionalProperties: false HistoricalDayKey: type: string pattern: ^[0-9]{1,2}$ description: Day of the month (UTC), without leading zero. HistoricalDayOrZero: type: integer description: Day as `YYYYMMDD`, or 0. HistoricalMonth: type: integer minimum: 100001 maximum: 999912 description: Month as `YYYYMM`. HistoricalMonthKey: type: string pattern: ^[0-9]{6}$ description: Month (`YYYYMM`, UTC). HistoricalTimeKey: type: string pattern: ^[0-9]{2}:[0-9]{2}:[0-9]{2}$ description: Time of the day (`HH:MM:SS`, UTC). KindSensor: type: object required: - code - description - normal_state - max_analog_value - min_analog_value properties: code: type: integer enum: - 0 - 1 - 2 - 3 - 4 description: 0 digital, 1 voltage, 2 current, 3 flow meter, 4 security. description: type: - string - 'null' normal_state: type: - boolean - 'null' description: Normal state of digital and security sensors. True open, false closed; null for other kinds. max_analog_value: description: Maximum value the sensor can measure, in `magnitude` units (calibrated in `GET /api/v2/ghator`). Usually a decimal string; in `GET /api/v2/ghator`, when the calibrated value is clipped to zero it is the number 0. anyOf: - $ref: '#/components/schemas/NullableDecimalString' - const: 0 min_analog_value: description: Minimum value the sensor can measure, in `magnitude` units (calibrated in `GET /api/v2/ghator`). Usually a decimal string; in `GET /api/v2/ghator`, when the calibrated value is clipped to zero it is the number 0. anyOf: - $ref: '#/components/schemas/NullableDecimalString' - const: 0 additionalProperties: false LogicExpression: type: object properties: operating: type: array maxItems: 2 description: Operands. If there are two, only one of them can be a constant. items: $ref: '#/components/schemas/Operand' operators: type: array maxItems: 1 description: Arithmetic operator between the operands. 0 addition, 1 subtraction, 2 multiplication, 3 division, 4 absolute difference. items: type: integer enum: - 0 - 1 - 2 - 3 - 4 NetTechOption: type: object required: - code - tech properties: code: type: - integer - 'null' description: Network technology code (0 LTE, 1 NB-IoT, 2 GPRS, 3 any). tech: type: - string - 'null' description: Network technology description. additionalProperties: false NonFlowmeterSensor: type: object required: - idsensor - ninput - name - value - status - magnitude - scale - lecture_kind - kind_sensor - sensor_visual_type - alerts - alerts_config properties: idsensor: type: integer description: Sensor identifier. ninput: type: integer description: Input number of the gHator where the sensor is installed. name: type: - string - 'null' maxLength: 18 description: Custom name of the sensor. value: description: 'Calibrated value for analog sensors, in `magnitude` units: (raw value + correction) × factor, rounded to the decimals of the sensor scale. Usually a decimal string; when the calibrated value is clipped to zero (sensor types with a minimum value of 0 or more) it is the number 0.' anyOf: - $ref: '#/components/schemas/NullableDecimalString' - const: 0 status: type: - boolean - 'null' description: State of digital and security sensors. magnitude: type: - string - 'null' description: Unit of `value` (e.g. "V", "bar"). scale: $ref: '#/components/schemas/NullableDecimalString' description: Scale applied by the gHator at origin. lecture_kind: type: - string - 'null' enum: - valor - estado - null description: '"valor" for value (analog) sensors, "estado" for digital sensors.' kind_sensor: $ref: '#/components/schemas/KindSensor' sensor_visual_type: $ref: '#/components/schemas/SensorVisualType' alerts: type: object required: - state_value_alert - state_value_alert_start_date properties: state_value_alert: type: boolean description: 'True if the sensor alert is triggered. Digital and security sensors: alert enabled and sensor active. Analog sensors: alert enabled and a configured threshold exceeded.' state_value_alert_start_date: $ref: '#/components/schemas/NullableDateTimeUtc' description: Date when the alert was triggered. additionalProperties: false alerts_config: type: object required: - state_value_alert_en - value_more_than - value_less_than properties: state_value_alert_en: type: boolean description: True if the alert is enabled. value_more_than: $ref: '#/components/schemas/NullableDecimalString' description: Upper threshold for analog sensors, in `magnitude` units (calibrated). value_less_than: $ref: '#/components/schemas/NullableDecimalString' description: Lower threshold for analog sensors, in `magnitude` units (calibrated). additionalProperties: false additionalProperties: false NullableDateTimeUtc: type: - string - 'null' format: date-time description: UTC timestamp in ISO 8601 with milliseconds, or null. NullableDecimalString: type: - string - 'null' pattern: ^-?[0-9]+(\.[0-9]+)?$ description: Decimal number serialized as a JSON string, or null when no value is available. Operand: type: object properties: operatingkind: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 description: 0 flow meter, 1 flow, 2 analog sensor, 3 sensor state, 4 actuator state, 5 constant. id_val: type: - integer - number - string - boolean description: Input or output number where the value is read, a boolean or a constant, depending on `operatingkind`. Constants referring to analog sensors are returned calibrated, as a string, in the units of the referenced sensor. max_value: type: - number - string - 'null' description: Maximum value the sensor can measure, for analog sensors. min_value: type: - number - string - 'null' description: Minimum value the sensor can measure, for analog sensors. input_ref: type: - integer - string - 'null' description: For constants, input number of the sensor the constant refers to, if defined. kind_sensor: type: - integer - 'null' description: Kind of the referenced sensor (see KindSensor.code). Used to calibrate constants. Owner: type: object description: Owner of the gHator. required: - name - email - nif - language properties: name: type: string description: First name and last name separated by a space. A single space if there is no owner. email: type: - string - 'null' nif: type: - string - 'null' description: Tax identification number of the owner. language: type: - string - 'null' description: Preferred language, two-letter code ("es", "en" and "fr" are supported; other codes fall back to English). additionalProperties: false Program: type: object required: - idprogram - nprograma - starttime - duration - daysweek - enable - active - actuators properties: idprogram: type: integer description: Program identifier. nprograma: type: - integer - 'null' description: Program number assigned by the gHator. starttime: type: - string - 'null' description: Start time, HH:MM:SS (24 h). duration: type: - integer - 'null' minimum: 1 maximum: 4294967295 description: Seconds from the start time to the end of the program. daysweek: type: string pattern: ^[01]{7}$ description: Seven-character binary string, one character per day from Monday to Sunday ("MoTuWeThFrSaSu"); "1" means the program runs that day. enable: type: boolean description: True if the program is enabled. active: type: boolean description: True if the program was running in the last status reading. actuators: type: array description: Actuators activated by the program, ordered by output number. items: $ref: '#/components/schemas/ProgramActuator' additionalProperties: false ProgramActuator: type: object required: - idactuator - name - normal_state - is_master - action - afmv - afv properties: idactuator: type: integer name: type: - string - 'null' normal_state: type: boolean description: Normal state of the actuator. is_master: type: boolean action: type: - boolean - 'null' description: Action on the actuator. Inside a program actuators can only be activated; they are deactivated when `duration`, `afmv` or `afv` is reached. afmv: $ref: '#/components/schemas/NullableDecimalString' description: Flow meter volume from the start of the program that deactivates the actuator. afv: $ref: '#/components/schemas/NullableDecimalString' description: Volume estimated from the actuator flow from the start of the program that deactivates it. additionalProperties: false Rule: type: object required: - idrule - priority - rulename - enable - active - ruleconditions - ruleactions properties: idrule: type: integer description: Rule identifier. priority: type: - integer - 'null' description: Evaluation priority within the rule set; 1 is the highest. rulename: type: - string - 'null' description: Custom name of the rule. enable: type: boolean description: True if the rule is enabled. active: type: boolean description: True if the rule was enabled and its conditions were met in the last reading. ruleconditions: $ref: '#/components/schemas/RuleConditions' ruleactions: type: array description: Actions executed when the conditions are met. Currently limited to activating or deactivating actuators. items: $ref: '#/components/schemas/RuleAction' additionalProperties: false RuleAction: type: object required: - idactuator - name - normal_state - is_master - action - duration - afmv - afv properties: idactuator: type: integer name: type: - string - 'null' normal_state: type: boolean is_master: type: boolean action: type: - boolean - 'null' description: True activates the actuator, false deactivates it. duration: type: - integer - 'null' description: If `action` is true, seconds until the actuator is deactivated. afmv: $ref: '#/components/schemas/NullableDecimalString' description: If `action` is true, flow meter volume from the activation that deactivates the actuator. afv: $ref: '#/components/schemas/NullableDecimalString' description: Volume estimated from the actuator flow from the activation that deactivates it. additionalProperties: false RuleCondition: type: object properties: logic1: $ref: '#/components/schemas/LogicExpression' comparoperator: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 description: 0 equal, 1 not equal, 2 less or equal, 3 greater or equal, 4 less than, 5 greater than. logic2: $ref: '#/components/schemas/LogicExpression' RuleConditions: type: object properties: conditions: type: array description: Conditions of the rule. Each condition compares two logical expressions; each expression has up to two operands combined by an arithmetic operator. items: $ref: '#/components/schemas/RuleCondition' logicoperators: type: array description: Logic operators between consecutive conditions (one less than the number of conditions). Only 0 (AND) is allowed. items: type: integer enum: - 0 SensorHistoricalResponse: type: object required: - status - code - idsensor - ninput - name - kind_sensor - first_historical_date - last_historical_date - init_requested_date - end_requested_date - ghator_offset_seconds - historical properties: status: const: ok code: const: '0' idsensor: type: integer description: Sensor identifier. ninput: type: - integer - 'null' description: Input number of the gHator where the sensor is installed. name: type: - string - 'null' description: Custom name of the sensor. kind_sensor: $ref: '#/components/schemas/KindSensor' description: Kind of the sensor. Here `max_analog_value` and `min_analog_value` are the limits of the sensor type without the calibration of the sensor (`GET /api/v2/ghator` returns them calibrated). first_historical_date: $ref: '#/components/schemas/HistoricalDayOrZero' description: First day with stored samples of the sensor (`YYYYMMDD`, UTC), or 0 if there are none. last_historical_date: $ref: '#/components/schemas/HistoricalDayOrZero' description: Last day with stored samples of the sensor (`YYYYMMDD`, UTC), or 0 if there are none. init_requested_date: $ref: '#/components/schemas/HistoricalMonth' description: First month of the requested period (`initdate`), as `YYYYMM`. end_requested_date: $ref: '#/components/schemas/HistoricalMonth' description: Last month of the requested period (`enddate`), as `YYYYMM`. ghator_offset_seconds: $ref: '#/components/schemas/GhatorOffsetSeconds' historical: description: Samples of the requested months, grouped by month, day and time (UTC). The time of a sample is when redHator processed the state received from the gHator. type: object propertyNames: $ref: '#/components/schemas/HistoricalMonthKey' additionalProperties: type: object propertyNames: $ref: '#/components/schemas/HistoricalDayKey' additionalProperties: type: object propertyNames: $ref: '#/components/schemas/HistoricalTimeKey' additionalProperties: $ref: '#/components/schemas/SensorSample' additionalProperties: false SensorSample: type: array description: | One sample of a sensor: `[value, inst_flow, origin]`. Samples stored by older versions of redHator can have only the first one or two elements. 1. `value`: for analog sensors and flow meters, the calibrated value in the magnitude of the sensor (see `magnitude` in `GET /api/v2/ghator`), usually as a decimal string; for digital and security sensors, the state (boolean). 2. `inst_flow`: flow meters only, instant flow (see `inst_flow` in `GET /api/v2/ghator`); null for other sensors. 3. `origin`: code of the event that produced the sample. Informative; its values are not described in this documentation. minItems: 1 maxItems: 3 prefixItems: - type: - string - number - boolean - 'null' - type: - string - number - 'null' - type: - integer - 'null' SensorVisualType: type: object description: Visual representation category of the sensor type. required: - code - name - active properties: code: type: string name: type: string active: type: boolean additionalProperties: false Sensors: type: object description: Sensors connected to the inputs, split into flow meters and other sensors. required: - none_fm_sensors - fm_sensors properties: none_fm_sensors: type: array description: Digital, analog (voltage or current) and security sensors, ordered by input number. items: $ref: '#/components/schemas/NonFlowmeterSensor' fm_sensors: type: array description: Flow meter sensors, ordered by input number. items: $ref: '#/components/schemas/FlowmeterSensor' additionalProperties: false Sim: type: object description: SIM card installed in the gHator. All values are null if no SIM is registered. required: - iccid - simprovider - ip properties: iccid: type: - string - 'null' description: ICCID of the SIM card. simprovider: type: - string - 'null' description: Provider of the SIM card. ip: type: - string - 'null' description: IP address assigned to the SIM by the provider in its private network. additionalProperties: false TimezoneOption: type: object required: - code - zone - utc_gap properties: code: type: integer description: Time zone code (`tz`). zone: type: string description: IANA time zone, e.g. "Europe/Madrid". utc_gap: type: integer description: Offset with respect to UTC at the time of the request, in seconds. additionalProperties: false UserPermissions: type: object description: Permissions of the requesting user on the gHator, as evaluated by redHator for this request. They depend on the relationship of the user with the gHator (owner, delegated user or installer) and on the state of the gHator and of the accounts involved. required: - view - action - program - alerts - rules - historic - edit - updatefirm properties: view: type: - boolean - 'null' description: View information of the gHator. action: type: - boolean - 'null' description: Operate actuators. Requires the gHator to be initialized. program: type: - boolean - 'null' description: Configure programs. alerts: type: - boolean - 'null' description: Configure predefined alerts. rules: type: - boolean - 'null' description: Configure rules. historic: type: - boolean - 'null' description: Access historical data. edit: type: - boolean - 'null' description: Configure the gHator. updatefirm: type: - boolean - 'null' description: Send firmware update orders. additionalProperties: false examples: GhatorsOwner: summary: gHators owned by the user value: status: ok code: '0' ghators: - ghatorid: 1001 ghatorserial: '9001' ghatorv: '3.0' ghatorname: Example irrigation head ghatorcoor: - '39.4700' - '-0.3700' user_discharge: true operating: false all_programs_disabled: false all_rules_disabled: false suspended: false discharged: true inicialized: true last_read_error: false last_read_date: '2026-01-15T10:00:00.000Z' tsleep: 60 pending_alerts: false activated_rule: false v_firmware: 3.18.0 v_firmware_update_trial: null fail_update_trial: null renable_all_programs_date: null wkmode: 0 id: null - ghatorid: 1002 ghatorserial: '9002' ghatorv: '3.0' ghatorname: Example well ghatorcoor: [] user_discharge: true operating: true all_programs_disabled: false all_rules_disabled: false suspended: false discharged: true inicialized: true last_read_error: false last_read_date: '2026-01-15T09:00:00.000Z' tsleep: 120 pending_alerts: true activated_rule: false v_firmware: 3.18.0 v_firmware_update_trial: null fail_update_trial: null renable_all_programs_date: null wkmode: 2 id: null GhatorsNone: summary: The user owns no gHator (profile gamo) value: status: ok code: '0' ghators: null MissingParameters: summary: A required parameter is missing or empty value: message: missing or empty parameters status: error code: '3' msg_code: '3' BadParameters: summary: A parameter has a value that is not valid value: message: bad parameters status: error code: '3' msg_code: '11' Unauthorized: summary: Invalid or expired token value: message: Unauthorized! Invalid token status: error code: '1' msg_code: '1' Maintenance: summary: Maintenance mode value: message: maintenance on status: error code: '10' msg_code: '36' GhatorFull: summary: Complete gHator information value: status: ok code: '0' ghator: ghatorid: '1001' ghatorserial: '9001' v_firmware: 3.18.0 v_subfirmware: 0 last_firm_available: 3.20.0 v_firmware_update_trial: null fail_update_trial: null ghatorv: '3.0' wkmode: 0 tsleep: 60 bat_ext_value: '12.6' bat_ext_alert: false bat_ext_alert_start_date: null bat_int_value: '3.9' bat_int_alert: false bat_int_alert_start_date: null ghatorname: Example irrigation head ghatorcoor: - '39.4700' - '-0.3700' owner: name: Example Owner email: owner@example.com nif: null language: en sim: iccid: '8900000000000000000' simprovider: Example SIM provider ip: 192.0.2.10 user_discharge: true operating: true all_programs_disabled: false renable_all_programs_date: null all_rules_disabled: false suspended: false discharged: true inicialized: true last_read_error: false last_read_date: '2026-01-15T10:00:00.000Z' pending_alerts: false activated_rule: false rules_mismatch: false rules_mismatch_sent_alert_date: null installation_date: 10/01/2026 sensors: none_fm_sensors: - idsensor: 2001 ninput: 1 name: Pressure value: '2.35' status: null magnitude: bar scale: '1.0' lecture_kind: valor kind_sensor: code: 2 description: current normal_state: null max_analog_value: '10.0' min_analog_value: '0.0' sensor_visual_type: code: pressure name: Pressure active: true alerts: state_value_alert: false state_value_alert_start_date: null alerts_config: state_value_alert_en: true value_more_than: '6.0' value_less_than: '1.0' fm_sensors: - idsensor: 2002 ninput: 2 idfm: 3001 name: Main meter value: '1520.375' inst_flow: '4.2' magnitude: m3 scale: '0.1' dayconsum: 12.4 monthconsum: 180.75 related_actuators: - idactuator: 4001 name: Valve 1 alerts: leak_alert: false leak_alert_start_date: null noflow_alert: false noflow_alert_start_date: null cmax_day_alert: false flow_alert: false flow_alert_start_date: null cmax_month_alert: false cmin_day_alert: false alerts_config: leak_en: true leak_threshold: '0.5' leak_close_en: false leak_close_n: null leak_close_n_min: 1 leak_close_n_max: 10 leak_close_delay: null leak_close_delay_min: 1 leak_close_delay_max: 3600 leak_reset_t: 300 leak_reset_t_min: 60 leak_reset_t_max: 86400 noflow_en: false noflow_delay: null noflow_delay_min: 60 noflow_delay_max: 86400 cmax_day_en: true cmax_day_threshold: '50.0' flow_value_en: false flow_more_than: null flow_less_than: null cmax_month_en: true cmax_month_threshold_fw: '0.8' cmax_month_threshold: '1000.0' cmin_day_en: false cmin_day_threshold: null sensor_visual_type: code: flow name: Flow meter active: true actuators: - idactuator: 4001 noutput: 1 name: Valve 1 status: 1 which_change: '1' who_change: 6501 status_change_date: null utc_date_data: '2026-01-15T10:00:05.000Z' status_change_time: 1195 waitingxchange: false is_master: false slaves: [] gap_master: null kind: id: 1 description: Solenoid valve related_to: fluid normal_state: false fluid: idfluid_actuator: 6001 category: free day_consum_fm_related: '8.3' total_consum_fm_related: '940.1' flow: '5.0' day_consum_flow_related: '8.0' total_consum_flow_related: '910.0' afmv_acum_last_change: '0.4' afv_acum_last_change: '0.4' status_change_afmv_remain: null status_change_afv_remain: null related_fm: idsensor: 2002 ninput: 2 - idactuator: 4002 noutput: 2 name: Pump relay status: 0 which_change: '0' who_change: null status_change_date: null utc_date_data: null status_change_time: null waitingxchange: false is_master: false slaves: [] gap_master: null kind: id: 2 description: Relay related_to: onoff normal_state: false fluid: {} programs: - idprogram: 6501 nprograma: 1 starttime: '10:00:00' duration: 1200 daysweek: '1010100' enable: true active: true actuators: - idactuator: 4001 name: Valve 1 normal_state: false is_master: false action: true afmv: '5.0' afv: null rules: - idrule: 7001 priority: 1 rulename: Low pressure stop enable: true active: false ruleconditions: conditions: - logic1: operating: - operatingkind: 2 id_val: 1 operators: [] comparoperator: 4 logic2: operating: - operatingkind: 5 id_val: '1.0' input_ref: 1 kind_sensor: 2 operators: [] logicoperators: [] ruleactions: - idactuator: 4002 name: Pump relay normal_state: false is_master: false action: false duration: null afmv: null afv: null user_permissions: view: true action: true program: true alerts: true rules: true historic: true edit: true updatefirm: true master_en: false sys_temp: '24.5' signal_quality: 78 net_tech_options: - code: 0 tech: LTE - code: 1 tech: NBIoT - code: 2 tech: GPRS - code: 3 tech: Any net_tech: 0 com_tech: 0 GhatorPendingDischarge: summary: Owner who has not confirmed the registration yet value: status: ok code: '0' ghator: ghatorid: '1001' ghatorserial: '9001' ghatorname: Example irrigation head ghatorcoor: - '39.4700' - '-0.3700' owner: name: Example Owner email: owner@example.com nif: null language: en user_discharge: false discharged: true inicialized: true last_read_date: '2026-01-15T10:00:00.000Z' user_permissions: view: false action: false program: false alerts: false rules: false historic: false edit: false updatefirm: false GhatorMissingParameters: summary: ghatorid or ghatorserial missing value: message: missing or empty parameters status: error code: '3' msg_code: '3' GhatorForbidden: summary: The user has no view permission value: message: you can not manage required idris status: error code: '5' msg_code: '12' GhatorNotFound: summary: Identifier and serial number do not match a gHator value: message: serial or id of the idri not found status: error code: '4' msg_code: '10' GhatorInvalidBoardVersion: summary: The gHator has no valid board version value: message: idri has not or bad pcb version assigned status: error code: '6' msg_code: '14' GhatorInformation: summary: Administrative information of a gHator value: status: ok code: '0' ghatorinf: ghatorid: '1001' ghatorserial: '9001' ghatorname: Example irrigation head ghatorv: '3.0' ghatorcoor: - '39.4700' - '-0.3700' sensors: - id: 2001 idsensor: 2001 tiposensor_id: 1 ninput: 1 name: Main meter brand: Example model: M-1 factor: null correction: null main: true customcode: PLOT-12 kind_sensor: code: 3 description: flowmeter normal_state: null - id: 2002 idsensor: 2002 tiposensor_id: 4 ninput: 2 name: Door brand: Example model: D-1 factor: null correction: null kind_sensor: code: 0 description: digital normal_state: false - id: 2003 idsensor: 2003 tiposensor_id: 6 ninput: 3 name: Pressure brand: Example model: P-1 factor: '1.0' correction: '0.0' kind_sensor: code: 2 description: current normal_state: null actuators: - id: 3001 idactuator: 3001 tipoactuador_id: 2 noutput: 1 name: Valve 1 brand: Example model: V-1 kind_actuator: related_to: fluid normal_state: false category: free - id: 3002 idactuator: 3002 tipoactuador_id: 5 noutput: 2 name: Pump relay brand: Example model: R-1 kind_actuator: related_to: onoff normal_state: false category: null user_permissions: view: true action: true program: true alerts: true rules: true historic: true edit: true updatefirm: true GhatorConfiguration: summary: General configuration of a gHator in sleep mode value: status: ok code: '0' ghatorid: 1001 ghatorserial: '9001' v_firmware: 3.18.0 ghatorv: '3.0' ghatorname: Example irrigation head discharged: true installation_date: 10/01/2026 inicialized: true tz: 0 wkmode: 2 modeup: 2 net_tech: 3 delay_polling: 10 sensors_warmup: 1 sensors_warmup_min: 1 sensors_warmup_max: 60 status_interval_seconds: 3600 status_interval_seconds_min: 60 status_interval_seconds_max: 86400 battint: true battext: true battext_alert_en: true battextthreshold: '11.0' tsleep: 60 tsleepup: 60 tio: 300 tioup: 300 master_en: false wkmode_options: '0': continuous '2': sleep net_tech_options: - code: 0 tech: LTE-4G - code: 1 tech: NBIOT - code: 2 tech: GPRS-2G - code: 3 tech: Any tz_options: - code: 0 zone: Europe/Madrid utc_gap: 3600 - code: 1 zone: Africa/Algiers utc_gap: 3600 GhatorEditForbidden: summary: The user has no edit permission value: message: you can not edit required idri status: error code: '5' msg_code: '12' GhatorNotAvailableForEdition: summary: The gHator is not installed, active and not suspended value: message: idri is not available for edition status: error code: '4' msg_code: '10' SensorHistoricalFlowMeter: summary: Flow meter, one month value: status: ok code: '0' idsensor: 2001 ninput: 1 name: Main meter kind_sensor: code: 3 description: flowmeter normal_state: null max_analog_value: null min_analog_value: null first_historical_date: 20251201 last_historical_date: 20260115 init_requested_date: 202601 end_requested_date: 202601 ghator_offset_seconds: 3600 historical: '202601': '14': '00:00:00': - '118.2' - '0.0' - 11 '08:00:00': - '118.9' - '2.5' - 11 '09:00:00': - '121.3' - '2.5' - 11 '15': '00:00:00': - '121.3' - '0.0' - 11 '10:00:00': - '121.3' - '0.0' - 12 SensorHistoricalDigital: summary: Digital sensor, samples stored by an older version description: Older samples can have fewer elements. value: status: ok code: '0' idsensor: 2002 ninput: 2 name: Door kind_sensor: code: 0 description: digital normal_state: false max_analog_value: null min_analog_value: null first_historical_date: 20231010 last_historical_date: 20260115 init_requested_date: 202311 end_requested_date: 202311 ghator_offset_seconds: 3600 historical: '202311': '2': '00:00:00': - false - null '06:04:02': - true - null SensorHistoricalForbidden: summary: No historic permission value: message: you can not obtain historical data for required sensor status: error code: '5' msg_code: '12' SensorNotFound: summary: The sensor does not exist value: message: sensor not found status: error code: '4' msg_code: '10' ActuatorHistoricalValve: summary: Fluid actuator, one month value: status: ok code: '0' idactuator: 3001 noutput: 1 name: Valve 1 kind: id: 2 description: Solenoid valve related_to: fluid normal_state: false first_historical_date: 20251201 last_historical_date: 20260115 init_requested_date: 202601 end_requested_date: 202601 ghator_offset_seconds: 3600 historical: '202601': '15': '00:00:00': - false - '0.0' - '0.0' - 11 '08:00:00': - true - '0.0' - '0.0' - 11 '08:30:00': - false - '2.5' - '2.5' - 11 ActuatorHistoricalForbidden: summary: No historic permission value: message: you can not obtain historical data for required actuator status: error code: '5' msg_code: '12' ActuatorNotFound: summary: The actuator does not exist value: message: actuator not found status: error code: '4' msg_code: '10' responses: Unauthorized: description: The bearer token is invalid or expired, or the user is not active (`code` "1", `msg_code` "1"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/Unauthorized' ServiceUnavailable: description: The platform is in maintenance mode (`code` "10", `msg_code` "36"). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: maintenance: $ref: '#/components/examples/Maintenance' parameters: GhatorId: name: ghatorid in: query required: true description: gHator identifier. schema: type: string pattern: ^[0-9]+$ example: '1001' GhatorSerial: name: ghatorserial in: query required: true description: Serial number of the gHator. Must belong to the gHator identified by `ghatorid`. schema: type: string example: '9001' HistoricalInitDate: name: initdate in: query required: true description: First month of the requested period, `YYYY-MM` (UTC months). schema: type: string pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$ example: 2026-01 HistoricalEndDate: name: enddate in: query required: true description: Last month of the requested period, `YYYY-MM` (UTC months), included. schema: type: string pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$ example: 2026-01