{
  "openapi": "3.1.0",
  "info": {
    "title": "EnMo Integration API",
    "version": "1.1.0",
    "description": "Read-only daily device snapshot with recorded VS, safe meter serial and latest reading. API keys are issued in the EnMo portal. All timestamps are UTC ISO 8601. No internal flat ID, user identity, address, battery or raw radio payload is returned."
  },
  "servers": [{ "url": "https://app.enmo.sk/api" }],
  "paths": {
    "/v1/devices": {
      "get": {
        "operationId": "getDailyDevices",
        "summary": "Read the current devices and their latest valid readings",
        "description": "One successful request per API key per UTC day. Access is rechecked against current account permissions and assigned flats. A failed request does not consume the daily quota. No pagination; maximum 20,000 devices per category. API returns 503 rather than a partial list.",
        "security": [{ "apiKey": [] }],
        "responses": {
          "200": {
            "description": "Daily snapshot",
            "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" } } }
          },
          "401": { "description": "Missing, invalid, revoked or expired key" },
          "403": { "description": "Account, role, ownership or manager assignment changed" },
          "429": { "description": "Daily request already used; Retry-After gives seconds until next UTC day", "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } },
          "503": { "description": "Data temporarily unavailable or result too large; daily quota is not consumed" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Send the one-time displayed EnMo key in Authorization: Bearer <key>. Do not put it in a URL." } },
    "schemas": {
      "Reading": {
        "type": "object", "required": ["value", "measuredAt", "unit"],
        "properties": {
          "value": { "type": "string", "description": "Decimal reading, represented as a string to avoid rounding in consumers" },
          "measuredAt": { "type": "string", "format": "date-time" },
          "unit": { "type": "string", "enum": ["m3", "kWh", "device_unit"] },
          "source": { "type": "string", "enum": ["legacy", "iperl"] }
        }
      },
      "Device": {
        "type": "object", "required": ["category", "devEui", "vs", "serialNumber", "serialNumberLast8", "latestReading"],
        "properties": {
          "category": { "type": "string", "enum": ["water", "prvn", "heat"] },
          "devEui": { "type": "string", "description": "Stable technical device identifier" },
          "vs": { "type": ["string", "null"], "description": "Recorded flat variable symbol (variabilný symbol), preserving leading zeros. Null when not recorded. No internal EnMo flat ID is exposed." },
          "serialNumber": { "type": ["string", "null"], "description": "Full meter serial only when safely recognized from the device name; never a resident name or DevEUI fallback." },
          "serialNumberLast8": { "type": ["string", "null"], "pattern": "^[0-9]{8}$", "description": "Last eight decimal digits of serialNumber; null when serial is unknown. Preserve leading zeros." },
          "type": { "type": "string", "description": "Water meter subtype (TV, SV, etc.) when known" },
          "latestReading": { "oneOf": [{ "$ref": "#/components/schemas/Reading" }, { "type": "null" }], "description": "Null means no valid measurement. Never interpret as zero consumption." }
        }
      },
      "Snapshot": {
        "type": "object", "required": ["schemaVersion", "generatedAt", "timezone", "scope", "count", "devices"],
        "properties": {
          "schemaVersion": { "type": "string", "const": "1.1" },
          "generatedAt": { "type": "string", "format": "date-time" },
          "timezone": { "type": "string", "const": "UTC" },
          "scope": { "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "enum": ["manager", "flat"] } } },
          "count": { "type": "integer", "minimum": 0 },
          "devices": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }
        }
      }
    }
  }
}