{
  "openapi": "3.1.0",
  "info": {
    "title": "The World Guide — public endpoints",
    "version": "1.0.0",
    "summary": "Machine-readable entry points of theworldguide.org, the B2B directory of essential oils and aromatic raw materials.",
    "description": "The public, read-only endpoints of The World Guide. The site itself is a web application; these endpoints let software agents discover its pages and content without running JavaScript. Errors from these endpoints, and from any unknown path under /api/, are JSON Problem Details (RFC 9457).",
    "contact": {
      "name": "The World Guide",
      "url": "https://www.theworldguide.org/about"
    }
  },
  "servers": [
    {
      "url": "https://www.theworldguide.org"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getHomePage",
        "summary": "Home page, negotiated by the Accept header",
        "description": "Returns HTML by default (no Accept header, */*, or text/html). Returns the same content as Markdown for Accept: text/markdown, or as plain text for Accept: text/plain. Quality values are honoured. Every response carries Vary: Accept.",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Preferred representation, with optional quality values.",
            "schema": {
              "type": "string",
              "examples": ["text/markdown", "text/html"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The home page in the negotiated representation.",
            "headers": {
              "Vary": {
                "$ref": "#/components/headers/Vary"
              }
            },
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "406": {
            "description": "None of the requested representations is available; the body lists those that are.",
            "headers": {
              "Vary": {
                "$ref": "#/components/headers/Vary"
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/sitemap.xml": {
      "get": {
        "operationId": "getSitemap",
        "summary": "XML sitemap of every public page",
        "description": "Suppliers, products, articles and the main sections, in the sitemaps.org format.",
        "responses": {
          "200": {
            "description": "The sitemap.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/rss-feed": {
      "get": {
        "operationId": "getNewsFeed",
        "summary": "RSS 2.0 feed of the latest articles",
        "responses": {
          "200": {
            "description": "The news feed.",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/api/{path}": {
      "get": {
        "operationId": "unknownApiPath",
        "summary": "Any other path under /api/",
        "description": "There is no other public endpoint under /api/. Any method on an unknown path returns 404 with a Problem Details body.",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "Vary": {
        "description": "Always includes Accept: the body depends on the Accept request header.",
        "schema": {
          "type": "string",
          "examples": ["Accept"]
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "No resource at this path.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          },
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "Problem Details for HTTP APIs (RFC 9457), with three extension members.",
        "required": ["type", "title", "status", "detail", "code", "hint", "docs"],
        "properties": {
          "type": {
            "type": "string",
            "description": "A URI identifying the problem type; about:blank when the HTTP status says it all.",
            "examples": ["about:blank"]
          },
          "title": {
            "type": "string",
            "description": "The HTTP status phrase.",
            "examples": ["Not Found"]
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code.",
            "examples": [404]
          },
          "detail": {
            "type": "string",
            "description": "What happened for this request."
          },
          "instance": {
            "type": "string",
            "description": "The requested path."
          },
          "code": {
            "type": "string",
            "description": "A stable, machine-readable error code.",
            "enum": [
              "not_found",
              "method_not_allowed",
              "payload_too_large",
              "invalid_body",
              "unknown_function",
              "upstream_unavailable"
            ]
          },
          "hint": {
            "type": "string",
            "description": "What the caller can do to succeed."
          },
          "docs": {
            "type": "string",
            "format": "uri",
            "description": "This document."
          }
        }
      }
    }
  }
}