{
  "openapi": "3.1.0",
  "info": {
    "title": "Energy North public API",
    "version": "1.0.0",
    "description": "Public, read-only endpoints for searching and reading the Energy North guides. No key needed. 60 requests a minute per IP. Guides are general information, not legal advice.",
    "contact": { "name": "Energy North Ltd", "url": "https://energynorth.uk/contact" }
  },
  "servers": [{ "url": "https://energynorth.uk" }],
  "paths": {
    "/api/journal": {
      "get": {
        "operationId": "searchGuides",
        "summary": "Search the guides (or list the newest when q is empty)",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Plain words, e.g. EICR landlord" },
          { "name": "journal", "in": "query", "schema": { "type": "string", "enum": ["all", "main", "ev"], "default": "all" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 8 } }
        ],
        "responses": {
          "200": { "description": "Matching guides", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } },
          "429": { "description": "Too many requests" }
        }
      }
    },
    "/api/journal/guide": {
      "get": {
        "operationId": "getGuide",
        "summary": "Read one guide as plain text",
        "parameters": [{ "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }],
        "responses": {
          "200": { "description": "The guide", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Guide" } } } },
          "404": { "description": "Not an Energy North guide link" }
        }
      }
    },
    "/api/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "Energy North Journal MCP server (Streamable HTTP, JSON-RPC 2.0)",
        "description": "Model Context Protocol endpoint. Methods: initialize, tools/list, tools/call. Tools: search_guides, get_guide, latest_guides, booking_info.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": { "200": { "description": "JSON-RPC answer" }, "202": { "description": "Notification accepted" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Card": {
        "type": "object",
        "properties": {
          "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "journal": { "type": "string" },
          "published": { "type": "string", "description": "yyyy-mm-dd" }, "summary": { "type": "string" }
        }
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }, "journal": { "type": "string" }, "count": { "type": "integer" },
          "results": { "type": "array", "items": { "$ref": "#/components/schemas/Card" } }, "note": { "type": "string" }
        }
      },
      "Guide": {
        "type": "object",
        "properties": {
          "title": { "type": "string" }, "url": { "type": "string" }, "journal": { "type": "string" },
          "published": { "type": "string" }, "updated": { "type": "string" }, "text": { "type": "string" }, "note": { "type": "string" }
        }
      }
    }
  }
}