{
  "openapi": "3.1.1",
  "info": {
    "title": "IngSoft Datahub API",
    "description": "Provides data from connected platforms (e.g. load profiles from MakoFlow) to InterWatt installations.",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://datahub.interwatt.net/"
    }
  ],
  "paths": {
    "/restapi/mako/load-profiles": {
      "get": {
        "tags": [
          "Mako"
        ],
        "summary": "Get load profiles",
        "description": "Returns the load profiles of all locations assigned to the API key as IngSoft Standard-JSON, read from MakoFlow.\n\n**Range**\n\n- `[fromTimestampUtc, toTimestampUtc)` is split into local calendar days (Europe/Berlin); only intervals that lie completely inside the range are returned.\n- If `fromTimestampUtc` equals `toTimestampUtc`, the whole local calendar day (Europe/Berlin) containing that instant is returned.\n- The length of the range is not limited. The supported period is 2010-01-01 to 2065-01-01 local time (Europe/Berlin); outside it the request is rejected.\n- All versions delivered by MakoFlow (original and corrections) are included.\n\n**Response**\n\n- A stream of Standard-JSON documents: a JSON array by default, or NDJSON (one document per line) with `Accept: application/x-ndjson`.\n- The range is split into calendar months (Europe/Berlin). Each month with data yields one document with all locations of the key, in chronological order and as soon as the month is complete.\n- A month without data yields no document; in NDJSON it yields an empty line instead (keep-alive), which the client must skip.\n- If the whole range has no data, the stream contains exactly one document with empty `measurementGroups`.\n- Errors in the first month are reported as status code. If a later month fails, the connection is aborted after the documents already sent; the client must treat the incomplete stream as an error.\n\n**Test keys**\n\nTwo dedicated test API keys always receive fixed test data, without MakoFlow (fictitious location 99999999999). The range is still validated, but the test data is neither filtered nor shifted to it.\n\n- First key: one document with 8 measurement groups on 2026-03-01 between 00:00 and 02:00 local time.\n- Second key: behaves like a long range with three months: 4 measurement groups on 2026-03-01, a month without data (an empty line in NDJSON, nothing in the JSON array), and 4 measurement groups on 2026-04-26, each between 00:00 and 01:00 local time.",
        "operationId": "GetMakoLoadProfiles",
        "parameters": [
          {
            "name": "fromTimestampUtc",
            "in": "query",
            "description": "Start of the range (inclusive), ISO 8601 with offset, e.g. 2026-03-01T00:00:00+01:00.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "toTimestampUtc",
            "in": "query",
            "description": "End of the range (exclusive), ISO 8601 with offset, e.g. 2026-04-01T00:00:00+02:00. Equal to fromTimestampUtc: the whole local calendar day (Europe/Berlin) of fromTimestampUtc.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/StandardJsonDocumentDto"
                  }
                }
              },
              "application/x-ndjson": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/StandardJsonDocumentDto"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "502": {
            "description": "Bad Gateway",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "504": {
            "description": "Gateway Timeout",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MeasurementDto": {
        "required": [
          "value",
          "unit",
          "property"
        ],
        "type": "object",
        "properties": {
          "value": {
            "type": "number",
            "description": "Measured value.",
            "format": "double"
          },
          "unit": {
            "type": "string",
            "description": "Unit with the suffix _noncumulative (interval values, not meter readings): kWh_noncumulative, kVArh_noncumulative, kVAr_noncumulative, kW_noncumulative, m³_noncumulative, Wh/m²_noncumulative, vG_noncumulative, %_noncumulative or 1_noncumulative."
          },
          "property": {
            "type": "string",
            "description": "Measured property: QW (active energy), QB (reactive energy), PBM (reactive power), PW4 (power), Vgas (gas volume), EE (irradiation), vWind (wind speed), Prozent (percentage) or Anzahl (count). InterWatt measurand: \"{property}_{unit}\"."
          },
          "exactMeasurement": {
            "type": [
              "null",
              "string"
            ],
            "description": "Measurement quality: W (measured), E (substitute), I (interpolated), V (preliminary), F (missing), G (disturbed). Omitted if unknown."
          }
        },
        "additionalProperties": false,
        "description": "One measured value."
      },
      "MeasurementGroupDto": {
        "required": [
          "timestamp",
          "consumerID",
          "consumerName",
          "measurements"
        ],
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "integer",
            "description": "Measurement time, UTC as Unix epoch seconds. Interval end for energy values, interval start otherwise (fixed OBIS table).",
            "format": "int64"
          },
          "consumerID": {
            "type": "string",
            "description": "Consumer: \"{location}_{obis}\", e.g. \"12345678901_1-1:1.29.0\". Max. 255 characters."
          },
          "consumerName": {
            "type": "string",
            "description": "Consumer name (location description), max. 255 characters, not unique."
          },
          "measurements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MeasurementDto"
            },
            "description": "Measurements. If MakoFlow delivered several versions (original and corrections) of an interval, each version is a separate entry, oldest first."
          }
        },
        "additionalProperties": false,
        "description": "All measurements of one consumer at one timestamp."
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": [
              "null",
              "string"
            ]
          },
          "title": {
            "type": [
              "null",
              "string"
            ]
          },
          "status": {
            "type": [
              "null",
              "integer"
            ],
            "format": "int32"
          },
          "detail": {
            "type": [
              "null",
              "string"
            ]
          },
          "instance": {
            "type": [
              "null",
              "string"
            ]
          },
          "traceId": {
            "type": "string",
            "description": "Trace ID of the request; quote it when reporting a problem."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code, e.g. unauthorized, invalid_time_range, mako_timeout."
          }
        }
      },
      "StandardJsonDocumentDto": {
        "required": [
          "transmissionTime",
          "schemaVersion",
          "measurementGroups"
        ],
        "type": "object",
        "properties": {
          "transmissionTime": {
            "type": "integer",
            "description": "Transmission time, UTC as Unix epoch seconds.",
            "format": "int64"
          },
          "schemaVersion": {
            "type": "string",
            "description": "Schema version, always \"1.0\"."
          },
          "measurementGroups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MeasurementGroupDto"
            },
            "description": "Measurement groups, ordered by consumerID and timestamp."
          }
        },
        "additionalProperties": false,
        "description": "IngSoft Standard-JSON document (specification version 1.2): measurements grouped by consumer and timestamp."
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "description": "API key issued by IngSoft for the calling InterWatt server.",
        "name": "X-API-Key",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "ApiKey": [ ]
    }
  ],
  "tags": [
    {
      "name": "Mako"
    }
  ]
}