{
  "openapi": "3.1.0",
  "info": {
    "title": "Global Debt Clock API",
    "description": "Live government debt data for 138 countries + world aggregate. Data is computed in real-time using IMF GFS and World Bank IDS baselines anchored to April 2025. Formula: debt = base_debt + (rate_per_second × elapsed_seconds). No authentication required. CORS enabled.",
    "version": "1.0.0",
    "contact": {
      "name": "Global Debt Clock",
      "url": "https://www.global-debt-clock.com",
      "email": "contact@global-debt-clock.com"
    },
    "license": {
      "name": "Data from IMF GFS + World Bank IDS",
      "url": "https://www.global-debt-clock.com/llms.txt"
    }
  },
  "servers": [
    {
      "url": "https://www.global-debt-clock.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/debt": {
      "get": {
        "operationId": "getDebt",
        "summary": "Get live debt for one country or all countries",
        "description": "Returns real-time computed government debt. Pass `?c={id}` for a single country or omit for all 138 countries + world. Country IDs are ISO 3166-1 alpha-2 lowercase (e.g. `us`, `jp`, `gb`). Special ID: `world` for global aggregate.",
        "parameters": [
          {
            "name": "c",
            "in": "query",
            "required": false,
            "description": "ISO 3166-1 alpha-2 country code (lowercase). Examples: us, jp, gb, de, cn, world",
            "schema": {
              "type": "string",
              "example": "us"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Live debt data",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": { "type": "string", "example": "*" }
              },
              "Cache-Control": {
                "schema": { "type": "string", "example": "public, max-age=60, stale-while-revalidate=300" }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/CountryDebt" },
                    { "$ref": "#/components/schemas/AllCountriesDebt" }
                  ]
                },
                "examples": {
                  "single_country": {
                    "summary": "Single country (?c=us)",
                    "value": {
                      "id": "us",
                      "name": "United States",
                      "flag": "🇺🇸",
                      "region": "Americas",
                      "debt": 36523847291034,
                      "debtFormatted": "$36,523,847,291,034",
                      "rate": 58100,
                      "ratePerDay": 5018240000,
                      "ratePerYear": 1832616000000,
                      "gdpPct": 124,
                      "perCapita": 108680,
                      "population": 336050000,
                      "baseDebt": 36400000000000,
                      "baseDate": "2025-04-01",
                      "computedAt": "2026-06-07T12:00:00.000Z",
                      "note": null,
                      "source": "IMF GFS + World Bank IDS via global-debt-clock.com",
                      "methodology": "base_debt + (rate_per_second × elapsed_seconds)",
                      "liveCounter": "https://www.global-debt-clock.com/us/"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown country ID",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": { "type": "string", "example": "Unknown country id. See /data/debt.json for valid ids." }
                  }
                }
              }
            }
          }
        }
      },
      "options": {
        "operationId": "debtCORS",
        "summary": "CORS preflight",
        "responses": {
          "204": { "description": "CORS preflight response" }
        }
      }
    },
    "/data/debt.json": {
      "get": {
        "operationId": "getStaticDataset",
        "summary": "Full static dataset — all 138 countries",
        "description": "Static JSON file containing baseline parameters for all tracked countries. Suitable for AI training data, offline analysis, and initial page loads. Does not include live computed debt values — use /api/debt for real-time figures.",
        "responses": {
          "200": {
            "description": "Full dataset",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StaticDataset" }
              }
            }
          }
        }
      }
    },
    "/countries": {
      "get": {
        "operationId": "getCountryIndex",
        "summary": "Discovery index — all country IDs and page URLs",
        "description": "Lightweight index of all tracked countries: id, name, flag, region, and canonical page URL. Use this for discovery before fetching individual debt figures.",
        "responses": {
          "200": {
            "description": "Country index",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": { "type": "integer", "example": 139 },
                    "countries": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/CountryIndexEntry" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/debt/snapshot": {
      "get": {
        "operationId": "getDebtSnapshot",
        "summary": "Reproducible point-in-time debt figure for citation",
        "description": "Returns the computed debt at a specific UTC timestamp. The result is deterministic and cacheable — use this when you need a stable number to cite rather than a live value that changes every second. Includes a pre-formatted `citeAs` string.",
        "parameters": [
          {
            "name": "c",
            "in": "query",
            "required": true,
            "description": "ISO 3166-1 alpha-2 country code, e.g. us, jp, gb",
            "schema": { "type": "string", "example": "us" }
          },
          {
            "name": "t",
            "in": "query",
            "required": false,
            "description": "ISO 8601 UTC timestamp. Defaults to now if omitted.",
            "schema": { "type": "string", "format": "date-time", "example": "2026-01-01T00:00:00Z" }
          }
        ],
        "responses": {
          "200": {
            "description": "Snapshot debt at requested timestamp",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id":            { "type": "string" },
                    "name":          { "type": "string" },
                    "snapshotAt":    { "type": "string", "format": "date-time" },
                    "debt":          { "type": "integer" },
                    "debtFormatted": { "type": "string" },
                    "rate":          { "type": "number" },
                    "gdpPct":        { "type": "number" },
                    "perCapita":     { "type": "integer" },
                    "methodology":   { "type": "string" },
                    "citeAs":        { "type": "string", "description": "Pre-formatted citation string" },
                    "liveCounter":   { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/compare": {
      "get": {
        "operationId": "compareDebt",
        "summary": "Side-by-side debt comparison between two countries",
        "description": "Returns live debt, rate, gdpPct, and perCapita for two countries with computed deltas. Useful for answering questions like 'how does US debt compare to China?'",
        "parameters": [
          {
            "name": "a",
            "in": "query",
            "required": true,
            "description": "First country ISO code",
            "schema": { "type": "string", "example": "us" }
          },
          {
            "name": "b",
            "in": "query",
            "required": true,
            "description": "Second country ISO code",
            "schema": { "type": "string", "example": "cn" }
          }
        ],
        "responses": {
          "200": {
            "description": "Comparison result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "computedAt": { "type": "string", "format": "date-time" },
                    "a":    { "$ref": "#/components/schemas/CountryCompareEntry" },
                    "b":    { "$ref": "#/components/schemas/CountryCompareEntry" },
                    "delta": {
                      "type": "object",
                      "properties": {
                        "debt":          { "type": "integer" },
                        "debtFormatted": { "type": "string" },
                        "rateDiff":      { "type": "number" },
                        "gdpPctDiff":    { "type": "number" },
                        "perCapitaDiff": { "type": "integer" },
                        "largerDebt":    { "type": "string" },
                        "higherRate":    { "type": "string" },
                        "higherGdpPct":  { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/watch": {
      "get": {
        "operationId": "watchDebtThreshold",
        "summary": "Register a webhook for when debt crosses a threshold",
        "description": "Register a callback URL to be notified when a country's debt crosses a specified USD threshold. Returns ETA estimate and current debt. Persistent delivery requires KV binding — contact us to enable.",
        "parameters": [
          {
            "name": "c",
            "in": "query",
            "required": true,
            "description": "Country ISO code",
            "schema": { "type": "string", "example": "us" }
          },
          {
            "name": "threshold",
            "in": "query",
            "required": true,
            "description": "USD threshold value",
            "schema": { "type": "number", "example": 37000000000000 }
          },
          {
            "name": "callback",
            "in": "query",
            "required": true,
            "description": "URL to POST when threshold is crossed",
            "schema": { "type": "string", "format": "uri" }
          }
        ],
        "responses": {
          "202": {
            "description": "Registration accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status":        { "type": "string", "example": "registration_accepted" },
                    "currentDebt":   { "type": "integer" },
                    "threshold":     { "type": "number" },
                    "alreadyCrossed":{ "type": "boolean" },
                    "etaSeconds":    { "type": "integer", "nullable": true },
                    "etaHuman":      { "type": "string", "nullable": true }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "get": {
        "operationId": "getMcpManifest",
        "summary": "MCP tool manifest",
        "description": "Returns the Model Context Protocol tool definitions for this API. POST to this endpoint to invoke tools directly from MCP-compatible agents.",
        "responses": {
          "200": {
            "description": "MCP manifest",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      },
      "post": {
        "operationId": "mcpToolCall",
        "summary": "Invoke an MCP tool",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tool":  { "type": "string", "example": "get_debt" },
                  "input": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Tool result" }
        }
      }
    },
    "/news": {
      "get": {
        "operationId": "getNews",
        "summary": "Latest debt-related headlines",
        "description": "Returns up to 5 recent headlines from The Guardian related to government debt. Cached for 15 minutes.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search query. Defaults to 'government debt'",
            "schema": { "type": "string", "example": "United States debt" }
          }
        ],
        "responses": {
          "200": {
            "description": "News headlines",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": { "type": "string" },
                          "link": { "type": "string", "format": "uri" },
                          "pubDate": { "type": "string", "format": "date-time" },
                          "source": { "type": "string", "example": "The Guardian" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CountryDebt": {
        "type": "object",
        "description": "Live computed debt for a single country",
        "properties": {
          "id":             { "type": "string", "example": "us" },
          "name":           { "type": "string", "example": "United States" },
          "flag":           { "type": "string", "example": "🇺🇸" },
          "region":         { "type": "string", "example": "Americas" },
          "debt":           { "type": "integer", "description": "Current debt in USD", "example": 36523847291034 },
          "debtFormatted":  { "type": "string", "example": "$36,523,847,291,034" },
          "rate":           { "type": "number", "description": "USD added per second", "example": 58100 },
          "ratePerDay":     { "type": "number", "description": "USD added per day", "example": 5018240000 },
          "ratePerYear":    { "type": "number", "description": "USD added per year", "example": 1832616000000 },
          "gdpPct":         { "type": "number", "description": "Debt as % of GDP", "example": 124 },
          "perCapita":      { "type": "integer", "description": "Debt per citizen in USD", "example": 108680 },
          "population":     { "type": "integer", "example": 336050000 },
          "baseDebt":       { "type": "integer", "description": "Baseline debt at baseDate", "example": 36400000000000 },
          "baseDate":       { "type": "string", "format": "date", "example": "2025-04-01" },
          "computedAt":     { "type": "string", "format": "date-time" },
          "note":           { "type": "string", "nullable": true },
          "source":         { "type": "string" },
          "methodology":    { "type": "string" },
          "liveCounter":    { "type": "string", "format": "uri" }
        }
      },
      "AllCountriesDebt": {
        "type": "object",
        "properties": {
          "computedAt": { "type": "string", "format": "date-time" },
          "count":      { "type": "integer", "example": 139 },
          "source":     { "type": "string" },
          "staticData": { "type": "string", "format": "uri" },
          "countries":  {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "name":       { "type": "string" },
                "flag":       { "type": "string" },
                "region":     { "type": "string" },
                "debt":       { "type": "integer" },
                "rate":       { "type": "number" },
                "gdpPct":     { "type": "number" },
                "perCapita":  { "type": "integer" },
                "population": { "type": "integer" },
                "baseDate":   { "type": "string" }
              }
            }
          }
        }
      },
      "StaticDataset": {
        "type": "object",
        "properties": {
          "_meta": {
            "type": "object",
            "properties": {
              "description": { "type": "string" },
              "methodology":  { "type": "string" },
              "sources":      { "type": "array", "items": { "type": "string" } },
              "baseDate":     { "type": "string" },
              "liveApi":      { "type": "string", "format": "uri" },
              "generated":    { "type": "string", "format": "date" }
            }
          },
          "countries": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "name":     { "type": "string" },
                "flag":     { "type": "string" },
                "region":   { "type": "string" },
                "base":     { "type": "integer" },
                "rate":     { "type": "number" },
                "baseDate": { "type": "string" },
                "pop":      { "type": "integer" },
                "gdpPct":   { "type": "number" },
                "note":     { "type": "string" }
              }
            }
          }
        }
      },
      "CountryCompareEntry": {
        "type": "object",
        "properties": {
          "id":            { "type": "string" },
          "name":          { "type": "string" },
          "flag":          { "type": "string" },
          "region":        { "type": "string" },
          "debt":          { "type": "integer" },
          "debtFormatted": { "type": "string" },
          "rate":          { "type": "number" },
          "gdpPct":        { "type": "number" },
          "perCapita":     { "type": "integer" },
          "population":    { "type": "integer" }
        }
      },
      "CountryIndexEntry": {
        "type": "object",
        "properties": {
          "id":      { "type": "string", "example": "us" },
          "name":    { "type": "string", "example": "United States" },
          "flag":    { "type": "string", "example": "🇺🇸" },
          "region":  { "type": "string", "example": "Americas" },
          "pageUrl": { "type": "string", "format": "uri", "example": "https://www.global-debt-clock.com/us/" },
          "apiUrl":  { "type": "string", "format": "uri", "example": "https://www.global-debt-clock.com/api/debt?c=us" }
        }
      }
    }
  }
}