{
  "openapi": "3.0.3",
  "info": {
    "title": "Live12 DB API",
    "version": "v1",
    "description": "Distributed reference data API with regional edge endpoints. Low-latency single-record reads, a live change stream over Server-Sent Events (persistent connections), and bulk snapshot exports (full + incremental, tens of GB, continuously replicated).",
    "contact": {
      "name": "Live12 DB Support",
      "url": "https://live12db.com/contact",
      "email": "support@live12db.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {"url": "https://{region}.live12db.com/v1", "description": "Regional edge endpoint", "variables": {"region": {"default": "nl", "description": "Two-letter region code (see GET /regions)"}}}
  ],
  "security": [
    {"bearerAuth": []}
  ],
  "tags": [
    {"name": "System", "description": "Health and status checks (no auth)"},
    {"name": "Reference", "description": "Reference datasets"},
    {"name": "Streaming", "description": "Live change stream over Server-Sent Events (persistent connections)"},
    {"name": "Bulk", "description": "Snapshot listing and bulk export downloads"}
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["System"],
        "summary": "Liveness probe",
        "security": [],
        "responses": {"200": {"description": "Service is up", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Health"}}}}}
      }
    },
    "/status": {
      "get": {
        "tags": ["System"],
        "summary": "Edge node status",
        "security": [],
        "responses": {"200": {"description": "Status payload"}}
      }
    },
    "/regions": {
      "get": {
        "tags": ["System"],
        "summary": "List regional endpoints",
        "security": [],
        "responses": {"200": {"description": "List of regions", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/List"}}}}}
      }
    },
    "/timezones": {
      "get": {
        "tags": ["Reference"],
        "summary": "List timezones with current offsets",
        "responses": {
          "200": {"description": "List of timezones", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/List"}}}},
          "401": {"description": "Missing or invalid API key"}
        }
      }
    },
    "/countries": {
      "get": {
        "tags": ["Reference"],
        "summary": "List countries",
        "parameters": [
          {"name": "code", "in": "query", "description": "Filter by ISO 3166-1 alpha-2/alpha-3 code", "schema": {"type": "string"}},
          {"name": "currency", "in": "query", "description": "Filter by ISO 4217 currency code", "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {"description": "List of countries", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/List"}}}},
          "401": {"description": "Missing or invalid API key"}
        }
      }
    },
    "/time": {
      "get": {
        "tags": ["Reference"],
        "summary": "Current time for a timezone",
        "parameters": [
          {"name": "tz", "in": "query", "description": "IANA timezone (defaults to the edge region timezone)", "schema": {"type": "string", "example": "Europe/Riga"}}
        ],
        "responses": {
          "200": {"description": "Time payload"},
          "401": {"description": "Missing or invalid API key"},
          "422": {"description": "Unknown timezone"}
        }
      }
    },
    "/v3/api/stream": {
      "servers": [
        {"url": "https://{region}.live12db.com", "description": "Regional edge endpoint", "variables": {"region": {"default": "nl"}}}
      ],
      "get": {
        "tags": ["Streaming"],
        "summary": "Live change stream (Server-Sent Events)",
        "description": "Persistent SSE connection. Emits a 'change' event per dataset update; sends heartbeat comments between events. Resume with the Last-Event-ID header.",
        "responses": {
          "200": {"description": "An open text/event-stream of change events", "content": {"text/event-stream": {"schema": {"type": "string"}}}},
          "401": {"description": "Missing or invalid API key"}
        }
      }
    },
    "/v3/api/snapshots": {
      "servers": [
        {"url": "https://{region}.live12db.com", "description": "Regional edge endpoint", "variables": {"region": {"default": "nl"}}}
      ],
      "get": {
        "tags": ["Bulk"],
        "summary": "List dataset snapshots (full + incremental)",
        "description": "Point-in-time snapshots: nightly full dumps and hourly incremental diffs as jsonl.zst, continuously replicated. Each item carries a download_url that streams the export as application/x-ndjson.",
        "security": [],
        "responses": {
          "200": {"description": "List of snapshots with download URLs", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/List"}}}}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {"type": "http", "scheme": "bearer", "description": "API key as a Bearer token. Get one at https://live12db.com/pricing"}
    },
    "schemas": {
      "Health": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "example": "ok"},
          "region": {"type": "string", "example": "nl"},
          "timestamp": {"type": "string", "format": "date-time"}
        }
      },
      "List": {
        "type": "object",
        "properties": {
          "object": {"type": "string", "example": "list"},
          "count": {"type": "integer", "example": 30},
          "data": {"type": "array", "items": {"type": "object"}}
        }
      }
    }
  }
}