{
    "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). Latency-sensitive regions additionally expose an experimental HTTP/3 (QUIC, UDP 443) endpoint on the same regional host (e.g. sg.live12db.com), serving the same API with automatic fallback to HTTPS over TCP.",
        "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": "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": {
        "/": {
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "API index",
                "description": "Service metadata and the list of available /v1 endpoints.",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Service index"
                    }
                }
            }
        },
        "/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": [],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of regions",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        },
                        "headers": {
                            "ETag": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified"
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/timezones": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "List timezones with current offsets",
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of timezones",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Missing or invalid API key"
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/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"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of countries",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        },
                        "headers": {
                            "ETag": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified"
                    },
                    "401": {
                        "description": "Missing or invalid API key"
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/currencies": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "List currencies",
                "description": "ISO 4217 currencies, each enriched with the ISO 3166 countries that use it.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "query",
                        "description": "Filter by ISO 4217 currency code",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of currencies",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        },
                        "headers": {
                            "ETag": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified"
                    },
                    "401": {
                        "description": "Missing or invalid API key"
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/calendars": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "List calendar systems",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of calendar systems",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        },
                        "headers": {
                            "ETag": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified"
                    },
                    "401": {
                        "description": "Missing or invalid API key"
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/languages": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "List languages",
                "description": "ISO 639 languages with native names and writing direction.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "code",
                        "in": "query",
                        "description": "Filter by ISO 639-1 (alpha-2) or ISO 639-2/T (alpha-3) code",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of languages",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        },
                        "headers": {
                            "ETag": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "Cache-Control": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Not modified"
                    },
                    "401": {
                        "description": "Missing or invalid API key"
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/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"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/v3/api": {
            "servers": [
                {
                    "url": "https://{region}.live12db.com",
                    "description": "Regional edge endpoint",
                    "variables": {
                        "region": {
                            "default": "nl"
                        }
                    }
                }
            ],
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "Gateway index",
                "description": "Gateway metadata and the list of available /v3/api endpoints.",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Gateway index"
                    }
                }
            }
        },
        "/v3/api/status": {
            "servers": [
                {
                    "url": "https://{region}.live12db.com",
                    "description": "Regional edge endpoint",
                    "variables": {
                        "region": {
                            "default": "nl"
                        }
                    }
                }
            ],
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "Gateway cluster status",
                "description": "Cluster health, replication lag and live streaming throughput for the edge region.",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Gateway status payload"
                    }
                }
            }
        },
        "/v3/api/lookup": {
            "servers": [
                {
                    "url": "https://{region}.live12db.com",
                    "description": "Regional edge endpoint",
                    "variables": {
                        "region": {
                            "default": "nl"
                        }
                    }
                }
            ],
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "Single-record lookup",
                "description": "Low-latency single-record read served from the edge region cache.",
                "security": [],
                "parameters": [
                    {
                        "name": "key",
                        "in": "query",
                        "required": true,
                        "description": "Record key to resolve",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Record payload"
                    },
                    "422": {
                        "description": "Missing required 'key' parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/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.",
                "security": [],
                "responses": {
                    "200": {
                        "description": "An open text/event-stream of change events",
                        "content": {
                            "text/event-stream": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/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": [],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of snapshots with download URLs",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/v3/api/hosts": {
            "servers": [
                {
                    "url": "https://{region}.live12db.com",
                    "description": "Regional edge endpoint",
                    "variables": {
                        "region": {
                            "default": "nl"
                        }
                    }
                }
            ],
            "get": {
                "tags": [
                    "System"
                ],
                "summary": "List cluster hosts",
                "description": "Edge cluster topology: one node per region with its role and health.",
                "security": [],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "description": "Page size (1-200, default 50)",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 200,
                            "default": 50
                        }
                    },
                    {
                        "name": "offset",
                        "in": "query",
                        "description": "Zero-based page offset",
                        "schema": {
                            "type": "integer",
                            "minimum": 0,
                            "default": 0
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "List of cluster hosts",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/List"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid query parameter"
                    },
                    "429": {
                        "description": "Rate limit exceeded"
                    }
                }
            }
        },
        "/v3/api/exports/{id}": {
            "servers": [
                {
                    "url": "https://{region}.live12db.com",
                    "description": "Regional edge endpoint",
                    "variables": {
                        "region": {
                            "default": "nl"
                        }
                    }
                }
            ],
            "get": {
                "tags": [
                    "Bulk"
                ],
                "summary": "Download a snapshot export",
                "description": "Streams a snapshot export as newline-delimited JSON. The {id} accepts an optional .jsonl/.ndjson extension and .zst/.gz suffix.",
                "security": [],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Snapshot id (see GET /v3/api/snapshots)",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Snapshot export stream",
                        "content": {
                            "application/x-ndjson": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown snapshot"
                    }
                }
            }
        }
    },
    "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",
                        "description": "Number of items in this page",
                        "example": 28
                    },
                    "total_count": {
                        "type": "integer",
                        "description": "Total number of items across all pages",
                        "example": 28
                    },
                    "has_more": {
                        "type": "boolean",
                        "description": "True when further items exist beyond this page"
                    },
                    "limit": {
                        "type": "integer",
                        "description": "Page size in effect (default 50, max 200)",
                        "example": 50
                    },
                    "offset": {
                        "type": "integer",
                        "description": "Zero-based offset of this page",
                        "example": 0
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        }
                    }
                }
            }
        }
    }
}