{
  "openapi": "3.1.0",
  "info": {
    "title": "A Seat Awaits — Public read-only API",
    "version": "1.0.0",
    "description": "Public, anonymous endpoints for looking up seating assignments at events shared via QR code. All endpoints require a per-event QR token (issued by the event owner). No authentication is required.",
    "contact": {
      "name": "A Seat Awaits Support",
      "email": "support@aseatawaits.com",
      "url": "https://aseatawaits.com/help"
    }
  },
  "servers": [
    { "url": "https://aseatawaits.com" }
  ],
  "paths": {
    "/api/public/events/{token}": {
      "get": {
        "summary": "Get publicly-shared event metadata by QR token",
        "operationId": "getPublicEvent",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "description": "Per-event QR token issued by the event owner.",
            "schema": { "type": "string", "minLength": 8 }
          }
        ],
        "responses": {
          "200": {
            "description": "schema.org SocialEvent JSON-LD.",
            "content": {
              "application/ld+json": {
                "schema": { "$ref": "#/components/schemas/PublicEvent" }
              }
            }
          },
          "404": { "description": "No event with that token." }
        }
      }
    },
    "/api/public/events/{token}/guests": {
      "get": {
        "summary": "Search for a guest by name and return their table assignment",
        "operationId": "searchPublicGuests",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 8 }
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Guest name fragment. Must be at least 2 characters.",
            "schema": { "type": "string", "minLength": 2 }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 8 }
          }
        ],
        "responses": {
          "200": {
            "description": "schema.org ItemList of matching Person records with their assigned Place.",
            "content": {
              "application/ld+json": {
                "schema": { "$ref": "#/components/schemas/GuestSearchResult" }
              }
            }
          },
          "400": { "description": "Query too short or invalid token." }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PublicEvent": {
        "type": "object",
        "properties": {
          "@context": { "type": "string", "const": "https://schema.org" },
          "@type": { "type": "string", "const": "SocialEvent" },
          "name": { "type": "string" },
          "identifier": { "type": "string", "format": "uuid" },
          "url": { "type": "string", "format": "uri" },
          "description": { "type": "string" },
          "potentialAction": {
            "type": "object",
            "properties": {
              "@type": { "type": "string", "const": "SearchAction" },
              "target": { "type": "string" }
            }
          }
        }
      },
      "GuestSearchResult": {
        "type": "object",
        "properties": {
          "@context": { "type": "string", "const": "https://schema.org" },
          "@type": { "type": "string", "const": "ItemList" },
          "numberOfItems": { "type": "integer" },
          "itemListElement": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "@type": { "type": "string", "const": "ListItem" },
                "position": { "type": "integer" },
                "item": {
                  "type": "object",
                  "properties": {
                    "@type": { "type": "string", "const": "Person" },
                    "identifier": { "type": "string", "format": "uuid" },
                    "name": { "type": "string" },
                    "affiliation": { "type": "string" },
                    "location": {
                      "type": "object",
                      "properties": {
                        "@type": { "type": "string", "const": "Place" },
                        "name": { "type": "string" },
                        "description": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}