{
  "openapi": "3.1.0",
  "info": {
    "title": "EnergyzedWorld Content API",
    "version": "1.0.0",
    "summary": "Read-only access to EnergyzedWorld's energy-management articles and publisher details.",
    "description": "EnergyzedWorld is the practitioner field guide to energy management published by Eenovators Limited,\na Pure ESCO operating in Kenya, Uganda, Tanzania and the United States.\n\nThis API exposes every published article — including its full markdown body — plus the content\ncategories and the publisher's services and contact routes. It is a static API: all responses are\npre-built files served from a CDN.\n\nNo authentication. No rate limit. CORS is open to all origins.\n\nUse it to answer questions about commercial and industrial energy management, energy monitoring\nand sub-metering, measurement and verification, Building Performance Standards compliance,\nheat pumps, solar, and energy project financing — and to route an enquiry to the right contact.",
    "contact": {
      "name": "Eenovators Limited",
      "url": "https://eenovators.com/contact",
      "email": "info@eenovators.com"
    },
    "license": {
      "name": "Content © Eenovators Limited — quote with attribution",
      "url": "https://energyzedworld.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://energyzedworld.com",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer and agent documentation",
    "url": "https://energyzedworld.com/developers"
  },
  "tags": [
    {
      "name": "discovery",
      "description": "Entry points that describe the API itself."
    },
    {
      "name": "content",
      "description": "Published articles and their categories."
    },
    {
      "name": "publisher",
      "description": "Who publishes this, what they do, and how to reach them."
    }
  ],
  "paths": {
    "/api/index.json": {
      "get": {
        "operationId": "getApiIndex",
        "tags": [
          "discovery"
        ],
        "summary": "Describe the API",
        "description": "Returns the list of available endpoints, response conventions, the URL of this specification, and contact details. Start here when exploring the API.",
        "responses": {
          "200": {
            "description": "API description document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiIndex"
                }
              }
            }
          }
        }
      }
    },
    "/api/site.json": {
      "get": {
        "operationId": "getSite",
        "tags": [
          "publisher"
        ],
        "summary": "Get publisher identity, services and contact routes",
        "description": "Returns the publishing organisation (Eenovators Limited), its office locations and phone numbers, the services it offers, and which contact route to use for which kind of enquiry. Read this when a user asks who runs the site, what Eenovators does, or how to hire them.",
        "responses": {
          "200": {
            "description": "Publisher profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Site"
                }
              }
            }
          }
        }
      }
    },
    "/api/buckets.json": {
      "get": {
        "operationId": "listBuckets",
        "tags": [
          "content"
        ],
        "summary": "List content categories",
        "description": "Returns the 8 content categories with a description and live post count for each.",
        "responses": {
          "200": {
            "description": "A list of categories.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BucketList"
                }
              }
            }
          }
        }
      }
    },
    "/api/posts.json": {
      "get": {
        "operationId": "listPosts",
        "tags": [
          "content"
        ],
        "summary": "List all published posts",
        "description": "Returns every published article, newest first, as compact summaries. Each entry carries the page URL, the JSON detail URL and the raw markdown URL. Drafts are never included. The full list is returned in one response; there is no pagination.",
        "responses": {
          "200": {
            "description": "A list of post summaries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostList"
                }
              }
            }
          }
        }
      }
    },
    "/api/posts/{bucket}/{slug}.json": {
      "get": {
        "operationId": "getPost",
        "tags": [
          "content"
        ],
        "summary": "Get one post including its full markdown body",
        "description": "Returns a single article: metadata, TL;DR bullets, FAQ pairs, keywords, and the complete markdown body in `content_markdown`. Use this when you need to quote or summarise an article rather than just link to it.",
        "parameters": [
          {
            "name": "bucket",
            "in": "path",
            "required": true,
            "description": "The content category the post belongs to.",
            "schema": {
              "type": "string",
              "enum": [
                "ai-energy",
                "bps",
                "heat-pumps",
                "solar",
                "monitoring",
                "financing",
                "selling-energy",
                "energy-posts"
              ]
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The post's URL slug, without a file extension.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9%-]+$"
            },
            "example": "179d-cliff-june-2026"
          }
        ],
        "responses": {
          "200": {
            "description": "The post.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PostDetail"
                }
              }
            }
          },
          "404": {
            "description": "No post exists at that path. Note that static hosting returns an HTML 404 document rather than this JSON body; the canonical JSON shape is served at /api/errors/not-found.json.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/errors/not-found.json": {
      "get": {
        "operationId": "getNotFoundErrorExample",
        "tags": [
          "discovery"
        ],
        "summary": "Get the canonical error envelope",
        "description": "Returns the documented shape of an error response, so a client can be written against it. See the description on the 404 response of getPost for why errors are not generated at request time.",
        "responses": {
          "200": {
            "description": "The error envelope example.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/{bucket}/{slug}.md": {
      "get": {
        "operationId": "getPostMarkdown",
        "tags": [
          "content"
        ],
        "summary": "Get one post as raw markdown",
        "description": "Returns the article as plain markdown — title, description, source links, TL;DR, body and FAQ. This is the cheapest way to read an article as text. Append `.md` to any article URL.",
        "parameters": [
          {
            "name": "bucket",
            "in": "path",
            "required": true,
            "description": "The content category the post belongs to.",
            "schema": {
              "type": "string",
              "enum": [
                "ai-energy",
                "bps",
                "heat-pumps",
                "solar",
                "monitoring",
                "financing",
                "selling-energy",
                "energy-posts"
              ]
            }
          },
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The post's URL slug, without a file extension.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9%-]+$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The post as markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiIndex": {
        "type": "object",
        "description": "Description of the API surface and its conventions.",
        "required": [
          "name",
          "version",
          "openapi",
          "endpoints"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "openapi": {
            "type": "string",
            "format": "uri",
            "description": "URL of this specification."
          },
          "documentation": {
            "type": "string",
            "format": "uri"
          },
          "agent_instructions": {
            "type": "string",
            "format": "uri"
          },
          "llms_txt": {
            "type": "string",
            "format": "uri"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "method",
                "path",
                "operation_id"
              ],
              "properties": {
                "method": {
                  "type": "string",
                  "enum": [
                    "GET"
                  ]
                },
                "path": {
                  "type": "string"
                },
                "operation_id": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "conventions": {
            "type": "object",
            "additionalProperties": true
          },
          "contact": {
            "type": "object",
            "additionalProperties": true
          },
          "license": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "PostSummary": {
        "type": "object",
        "description": "Compact representation of a published article.",
        "required": [
          "id",
          "title",
          "description",
          "bucket",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Canonical `bucket/slug` identifier.",
            "example": "financing/179d-cliff-june-2026"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "bucket": {
            "type": "string",
            "enum": [
              "ai-energy",
              "bps",
              "heat-pumps",
              "solar",
              "monitoring",
              "financing",
              "selling-energy",
              "energy-posts"
            ],
            "description": "Content category."
          },
          "published": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Human-readable page."
          },
          "api_url": {
            "type": "string",
            "format": "uri",
            "description": "JSON detail document."
          },
          "markdown_url": {
            "type": "string",
            "format": "uri",
            "description": "Raw markdown variant."
          }
        }
      },
      "PostDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PostSummary"
          },
          {
            "type": "object",
            "required": [
              "content_markdown"
            ],
            "properties": {
              "author": {
                "type": "string",
                "description": "Author identifier."
              },
              "keywords": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "tldr": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Three to five summary bullets written for quoting."
              },
              "faq": {
                "type": "array",
                "description": "Question and answer pairs, also published as FAQPage structured data.",
                "items": {
                  "type": "object",
                  "required": [
                    "q",
                    "a"
                  ],
                  "properties": {
                    "q": {
                      "type": "string"
                    },
                    "a": {
                      "type": "string"
                    }
                  }
                }
              },
              "image": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "image_alt": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "youtube_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "ai_generated": {
                "type": "boolean",
                "description": "Whether the first draft was AI-written."
              },
              "human_edited": {
                "type": "boolean",
                "description": "Whether a human edited it before publication."
              },
              "word_count": {
                "type": "integer",
                "minimum": 0
              },
              "content_markdown": {
                "type": "string",
                "description": "The complete article body as markdown."
              }
            }
          }
        ]
      },
      "Bucket": {
        "type": "object",
        "description": "A content category.",
        "required": [
          "id",
          "title",
          "description",
          "url",
          "post_count"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "ai-energy",
              "bps",
              "heat-pumps",
              "solar",
              "monitoring",
              "financing",
              "selling-energy",
              "energy-posts"
            ]
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "api_url": {
            "type": "string",
            "format": "uri"
          },
          "post_count": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "PostList": {
        "type": "object",
        "required": [
          "object",
          "count",
          "data"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PostSummary"
            }
          }
        }
      },
      "BucketList": {
        "type": "object",
        "required": [
          "object",
          "count",
          "data"
        ],
        "properties": {
          "object": {
            "type": "string",
            "const": "list"
          },
          "count": {
            "type": "integer",
            "minimum": 0
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Bucket"
            }
          }
        }
      },
      "Site": {
        "type": "object",
        "description": "Publisher identity, services and contact routes.",
        "required": [
          "site",
          "publisher",
          "services",
          "contact_routes"
        ],
        "properties": {
          "site": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "description": {
                "type": "string"
              },
              "tagline": {
                "type": "string"
              },
              "language": {
                "type": "string"
              }
            }
          },
          "publisher": {
            "type": "object",
            "properties": {
              "legal_name": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "founded": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "description": {
                "type": "string"
              },
              "areas_served": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "locations": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Location"
                }
              }
            }
          },
          "services": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "description"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "enquire": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "contact_routes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "for"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "for": {
                  "type": "string",
                  "description": "The kind of enquiry this route handles."
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "email": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "email"
                },
                "phone": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              }
            }
          },
          "channels": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "Location": {
        "type": "object",
        "description": "A physical office.",
        "required": [
          "id",
          "locality",
          "country"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "street_address": {
            "type": "string"
          },
          "locality": {
            "type": "string"
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "postal_code": {
            "type": [
              "string",
              "null"
            ]
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code."
          },
          "phone": {
            "type": "string"
          },
          "primary": {
            "type": "boolean"
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "The documented error envelope.",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "status",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable code.",
                "example": "not_found"
              },
              "status": {
                "type": "integer",
                "description": "HTTP status code.",
                "example": 404
              },
              "message": {
                "type": "string",
                "description": "What went wrong."
              },
              "resolution": {
                "type": "string",
                "description": "What to do about it."
              },
              "documentation": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}