{
  "openapi": "3.0.3",
  "info": {
    "title": "DB-Master5 API",
    "version": "v1",
    "description": "Heavy master-data distribution API. Multi-gigabyte snapshot exports (full + incremental, continuously replicated), a live change stream over Server-Sent Events (persistent connections), and low-latency single-record lookups served from a fleet of distribution nodes.",
    "contact": {
      "name": "DB-Master5 Support",
      "url": "https://db-master5.info/contact",
      "email": "support@db-master5.info"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {"url": "https://main.db-master5.info/v1", "description": "Primary distribution node"},
    {"url": "https://a2.db-master5.info/v1", "description": "Edge distribution node"}
  ],
  "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": "Node is up", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Health"}}}}}
      }
    },
    "/status": {
      "get": {
        "tags": ["System"],
        "summary": "Distribution node status",
        "security": [],
        "responses": {"200": {"description": "Status payload", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Status"}}}}}
      }
    },
    "/regions": {
      "get": {
        "tags": ["System"],
        "summary": "List distribution nodes",
        "security": [],
        "responses": {"200": {"description": "List of distribution nodes", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/NodeList"}}}}}
      }
    },
    "/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 serving node timezone)", "schema": {"type": "string", "example": "Europe/Moscow"}}
        ],
        "responses": {
          "200": {"description": "Time payload"},
          "401": {"description": "Missing or invalid API key"},
          "422": {"description": "Unknown timezone"}
        }
      }
    },
    "/v3/api/stream": {
      "servers": [
        {"url": "https://main.db-master5.info", "description": "Primary distribution node"},
        {"url": "https://a2.db-master5.info", "description": "Edge distribution node"}
      ],
      "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://main.db-master5.info", "description": "Primary distribution node"},
        {"url": "https://a2.db-master5.info", "description": "Edge distribution node"}
      ],
      "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 across distribution nodes. 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 (realm db-master5). Get one at https://db-master5.info/pricing"}
    },
    "schemas": {
      "Health": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "example": "ok"},
          "region": {"type": "string", "example": "main"},
          "timestamp": {"type": "string", "format": "date-time"}
        }
      },
      "Status": {
        "type": "object",
        "properties": {
          "status": {"type": "string", "example": "operational"},
          "build": {"type": "string", "example": "2026.5.3"},
          "region": {
            "type": "object",
            "properties": {
              "code": {"type": "string", "example": "main"},
              "role": {"type": "string", "example": "primary"},
              "tier": {"type": "string", "example": "core"}
            }
          },
          "nodes_online": {"type": "integer", "example": 14},
          "latency_ms": {"type": "integer", "example": 12},
          "timestamp": {"type": "string", "format": "date-time"}
        }
      },
      "Node": {
        "type": "object",
        "properties": {
          "code": {"type": "string", "example": "main"},
          "role": {"type": "string", "example": "primary", "enum": ["primary", "replica", "edge", "router"]},
          "tier": {"type": "string", "example": "core", "enum": ["core", "edge", "cache", "anycast"]},
          "datasets": {"type": "array", "items": {"type": "string"}, "example": ["timezones", "countries", "currencies", "calendars"]},
          "endpoint": {"type": "string", "example": "https://main.db-master5.info/v1"}
        }
      },
      "NodeList": {
        "type": "object",
        "properties": {
          "object": {"type": "string", "example": "list"},
          "count": {"type": "integer", "example": 14},
          "data": {"type": "array", "items": {"$ref": "#/components/schemas/Node"}}
        }
      },
      "List": {
        "type": "object",
        "properties": {
          "object": {"type": "string", "example": "list"},
          "count": {"type": "integer", "example": 14},
          "data": {"type": "array", "items": {"type": "object"}}
        }
      }
    }
  }
}