{
  "openapi": "3.0.3",
  "info": {
    "title": "TopMagpie Public API",
    "version": "1.0.0",
    "description": "Read-only JSON API for TopMagpie UK buying guides and winter advice articles. Editorial content with Amazon UK affiliate disclosure — no live prices or lab claims."
  },
  "servers": [
    {
      "url": "https://www.topmagpie.com"
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "summary": "API discovery",
        "description": "Returns site metadata, endpoint list, and documentation links.",
        "responses": {
          "200": {
            "description": "Discovery document"
          }
        }
      }
    },
    "/api/v1/openapi.json": {
      "get": {
        "summary": "OpenAPI specification",
        "description": "Machine-readable API schema for AI tools and developers.",
        "responses": {
          "200": {
            "description": "OpenAPI 3 JSON document"
          }
        }
      }
    },
    "/api/v1/guides": {
      "get": {
        "summary": "List guides",
        "description": "Published buying guides with winner summaries.",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by category slug (e.g. home-energy, kitchen, travel, tech)"
          }
        ],
        "responses": {
          "200": {
            "description": "Array of guide summaries"
          }
        }
      }
    },
    "/api/v1/guides/{slug}": {
      "get": {
        "summary": "Guide detail",
        "description": "Full structured guide including products, FAQs, and methodology.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Guide slug (e.g. best-draught-excluders-uk)"
          }
        ],
        "responses": {
          "200": {
            "description": "Guide detail object"
          },
          "404": {
            "description": "Guide not found or unpublished"
          }
        }
      }
    },
    "/api/v1/articles": {
      "get": {
        "summary": "List articles",
        "description": "Winter advice grabber articles that route into money pages.",
        "responses": {
          "200": {
            "description": "Array of article summaries"
          }
        }
      }
    },
    "/api/v1/categories": {
      "get": {
        "summary": "List categories",
        "description": "Distinct guide categories with published guide counts.",
        "responses": {
          "200": {
            "description": "Array of category objects"
          }
        }
      }
    }
  },
  "x-attribution": {
    "site": "TopMagpie",
    "url": "https://www.topmagpie.com",
    "license": "Editorial content © TopMagpie. Free to cite with attribution and a link to the canonical guide URL. Do not invent prices or lab claims beyond what we publish.",
    "affiliateDisclosure": "TopMagpie participates in the Amazon Services LLC Associates Programme. We may earn from qualifying purchases through links on this site. This does not affect our editorial selections or product rankings."
  }
}