{
  "openapi": "3.1.0",
  "info": {
    "title": "My Face Shape Chart public guide lookup",
    "version": "0.2.0",
    "description": "Bounded, read-only search and retrieval for the site's published face-shape guides. No authentication is required for these public operations."
  },
  "servers": [{"url": "https://myfaceshapechart.com"}],
  "paths": {
    "/api/agent": {
      "get": {
        "operationId": "siteLookup",
        "summary": "Find or read a public guide",
        "description": "Provide exactly one short query or one known slug. The service never fetches arbitrary URLs.",
        "parameters": [
          {"name": "query", "in": "query", "required": false, "schema": {"type": "string", "maxLength": 120}, "description": "Short keyword query, for example round jaw."},
          {"name": "slug", "in": "query", "required": false, "schema": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 80}, "description": "Known guide id, for example face-shape-chart."}
        ],
        "responses": {
          "200": {"description": "Search results or one public guide record.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/LookupResponse"}}}},
          "400": {"description": "Missing or invalid bounded input."},
          "404": {"description": "No public guide matches the slug."}
        }
      }
    },
    "/api/agent/health": {
      "get": {
        "operationId": "siteLookupHealth",
        "summary": "Check public lookup availability",
        "responses": {"200": {"description": "The public lookup service is available."}}
      }
    }
  },
  "components": {
    "schemas": {
      "GuideSummary": {
        "type": "object",
        "required": ["id", "title", "description", "url", "source_url"],
        "properties": {
          "id": {"type": "string"},
          "title": {"type": "string"},
          "description": {"type": "string"},
          "url": {"type": "string", "format": "uri"},
          "source_url": {"type": "string", "format": "uri"}
        }
      },
      "LookupResponse": {
        "type": "object",
        "properties": {
          "query": {"type": "string"},
          "count": {"type": "integer"},
          "results": {"type": "array", "items": {"$ref": "#/components/schemas/GuideSummary"}},
          "result": {"type": "object"},
          "source_url": {"type": "string", "format": "uri"}
        }
      }
    }
  }
}