{
  "openapi": "3.1.0",
  "info": {
    "title": "Mount Emporium Public SEO API",
    "version": "1.0.0",
    "summary": "Public, read-only JSON endpoints for AI answer engines, SEO tools, and integrators.",
    "description": "All endpoints are cross-origin (`Access-Control-Allow-Origin: *`), respect `ETag` / `If-None-Match` with `304 Not Modified`, and return no PII.",
    "contact": {
      "name": "Mount Emporium",
      "url": "https://www.mountemporium.com/contact"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://www.mountemporium.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Discovery",
      "description": "Manifest of available endpoints."
    },
    {
      "name": "Structured Data",
      "description": "schema.org @graph payloads."
    },
    {
      "name": "Sitemap",
      "description": "Machine-readable sitemap enumeration."
    },
    {
      "name": "Entities",
      "description": "AEO entity export."
    },
    {
      "name": "Crawler Config",
      "description": "robots + llms.txt as JSON."
    }
  ],
  "components": {
    "parameters": {
      "IfNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "description": "ETag from a previous successful response. Triggers 304.",
        "schema": {
          "type": "string"
        }
      },
      "IfModifiedSince": {
        "name": "If-Modified-Since",
        "in": "header",
        "required": false,
        "description": "RFC 1123 date from a previous `Last-Modified` header.",
        "schema": {
          "type": "string"
        }
      }
    },
    "headers": {
      "ETag": {
        "description": "Opaque cache validator. Echo in `If-None-Match`.",
        "schema": {
          "type": "string"
        }
      },
      "LastModified": {
        "description": "RFC 1123 timestamp of the newest included entity.",
        "schema": {
          "type": "string"
        }
      },
      "CacheControl": {
        "description": "Cache directives.",
        "schema": {
          "type": "string"
        }
      },
      "AccessControlAllowOrigin": {
        "description": "Always `*`.",
        "schema": {
          "type": "string"
        }
      }
    },
    "responses": {
      "NotModified": {
        "description": "Cached copy is still valid.",
        "headers": {
          "ETag": {
            "$ref": "#/components/headers/ETag"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          }
        }
      },
      "BadRequest": {
        "description": "Invalid query parameter (e.g. unknown `kind`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "Upstream error building payload. Safe to retry.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "Breadcrumb": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "name",
          "url"
        ]
      },
      "SitemapEntry": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "page",
              "product",
              "article",
              "faq",
              "breadcrumb"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "path": {
            "type": "string"
          },
          "lastmod": {
            "type": "string",
            "format": "date"
          },
          "changefreq": {
            "type": "string",
            "enum": [
              "always",
              "hourly",
              "daily",
              "weekly",
              "monthly",
              "yearly",
              "never"
            ]
          },
          "priority": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "images": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "breadcrumbs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Breadcrumb"
            }
          }
        },
        "required": [
          "url"
        ]
      },
      "SitemapResponse": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "count": {
            "type": "integer"
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SitemapEntry"
            }
          },
          "xml": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Entity": {
        "type": "object",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "article",
              "faq",
              "breadcrumb"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "answer": {
            "type": "string"
          },
          "excerpt": {
            "type": "string"
          },
          "hub": {
            "type": "string",
            "format": "uri"
          },
          "updated_at": {
            "type": "string",
            "format": "date"
          }
        },
        "required": [
          "kind",
          "url"
        ]
      },
      "EntitiesResponse": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "entities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Entity"
            }
          }
        }
      },
      "GraphNode": {
        "type": "object",
        "additionalProperties": true
      },
      "StructuredDataResponse": {
        "type": "object",
        "properties": {
          "@context": {
            "type": "string",
            "const": "https://schema.org"
          },
          "@graph": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/GraphNode"
            }
          }
        },
        "required": [
          "@context",
          "@graph"
        ]
      },
      "DiscoveryResponse": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          },
          "endpoints": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "description": {
                  "type": "string"
                },
                "params": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "id",
                "url"
              ]
            }
          },
          "xml_feeds": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "CrawlerConfigResponse": {
        "type": "object",
        "properties": {
          "site": {
            "type": "string",
            "format": "uri"
          },
          "robots": {
            "type": "object",
            "properties": {
              "rules": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "user_agent": {
                      "type": "string"
                    },
                    "allow": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "disallow": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "sitemaps": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "llms_txt": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "hubs": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/public/seo/index.json": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "Discovery manifest",
        "description": "Lists every public SEO/AEO endpoint. Start here to enumerate what's available.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          },
          {
            "$ref": "#/components/parameters/IfModifiedSince"
          }
        ],
        "responses": {
          "200": {
            "description": "Manifest of endpoints.",
            "headers": {
              "ETag": {
                "$ref": "#/components/headers/ETag"
              },
              "Last-Modified": {
                "$ref": "#/components/headers/LastModified"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "Access-Control-Allow-Origin": {
                "$ref": "#/components/headers/AccessControlAllowOrigin"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiscoveryResponse"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/public/seo/structured-data.json": {
      "get": {
        "tags": [
          "Structured Data"
        ],
        "summary": "schema.org @graph",
        "description": "Aggregated schema.org @graph for the entire site — Organization, WebSite, page ItemList, and per-article/product JSON-LD.",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Filter which node types are returned.",
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "organization",
                "website",
                "pages",
                "articles",
                "products"
              ],
              "default": "all"
            }
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          },
          {
            "$ref": "#/components/parameters/IfModifiedSince"
          }
        ],
        "responses": {
          "200": {
            "description": "schema.org @graph payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StructuredDataResponse"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/public/seo/sitemap.json": {
      "get": {
        "tags": [
          "Sitemap"
        ],
        "summary": "Machine-readable sitemap",
        "description": "URLs with lastmod, priority, changefreq, page summaries, breadcrumb trails, and images.",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "pages",
                "products",
                "articles",
                "faqs",
                "breadcrumbs"
              ],
              "default": "all"
            }
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          },
          {
            "$ref": "#/components/parameters/IfModifiedSince"
          }
        ],
        "responses": {
          "200": {
            "description": "Sitemap entries.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SitemapResponse"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/public/seo/entities.json": {
      "get": {
        "tags": [
          "Entities"
        ],
        "summary": "AEO entity export",
        "description": "Long-form knowledge articles, FAQ hubs, and pages carrying breadcrumb trails for AI answer engines.",
        "parameters": [
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "all",
                "articles",
                "faqs",
                "breadcrumbs"
              ],
              "default": "all"
            }
          },
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          },
          {
            "$ref": "#/components/parameters/IfModifiedSince"
          }
        ],
        "responses": {
          "200": {
            "description": "Entity export.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EntitiesResponse"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/public/seo/crawler-config.json": {
      "get": {
        "tags": [
          "Crawler Config"
        ],
        "summary": "robots + llms.txt hubs as JSON",
        "description": "Effective robots.txt rules, sitemap URLs, and llms.txt content hubs exposed as structured JSON.",
        "parameters": [
          {
            "$ref": "#/components/parameters/IfNoneMatch"
          },
          {
            "$ref": "#/components/parameters/IfModifiedSince"
          }
        ],
        "responses": {
          "200": {
            "description": "Crawler config.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CrawlerConfigResponse"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/api/public/seo/openapi.json": {
      "get": {
        "tags": [
          "Discovery"
        ],
        "summary": "This OpenAPI specification",
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "304": {
            "$ref": "#/components/responses/NotModified"
          }
        }
      }
    }
  }
}