{
  "openapi": "3.1.0",
  "info": {
    "title": "SVAMI Agentic ID (AID) resolver",
    "version": "1.0.0",
    "summary": "Identify hotels by Agentic ID (AID); GDS codes are aliases.",
    "description": "Free, keyless, rate-limited look-up of the Agentic ID (AID), the hotel identifier used by SVAMI. Always written \"Agentic ID (AID) AI-XXXXXX\": `AI-` followed by 6 Crockford base32 characters (0-9, A-Z without I, L, O, U). Permanent and never reused; merged duplicates resolve to the surviving hotel.\n\nThe free card holds name, city, country, group/brand, official website, Sabre / Amadeus / Galileo-Apollo / Worldspan codes and awards. Address, IATA city code, coordinates, phone, email and the knowledge base need a subscription and are never in these responses.\n\nExact match only: an unknown AID is `AID_NOT_FOUND`, never a similar hotel. A GDS code on several hotels returns all of them as candidates.\n\nMCP: the same look-ups are MCP tools `resolve_aid` and `find_hotel` at `POST https://mytour.travel/mcp` (Streamable HTTP).",
    "contact": {"name": "SVAMI", "url": "https://mytour.travel/aid"}
  },
  "servers": [{"url": "https://mytour.travel"}],
  "paths": {
    "/v1/aid/{aid}": {
      "get": {
        "operationId": "resolveAid",
        "summary": "Resolve an Agentic ID to the free hotel card",
        "description": "Identify hotels by Agentic ID (AID); GDS codes are aliases. Input is normalised: trimmed, upper-cased, spaces and hyphens removed, `AI-` added if missing (`ai-h0zqhr`, `H0ZQHR` work).",
        "parameters": [{"name": "aid", "in": "path", "required": true, "schema": {"type": "string", "examples": ["AI-H0ZQHR"]}}],
        "responses": {
          "200": {"description": "Free card", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Card"}}}},
          "400": {"description": "INVALID_AID", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "404": {"description": "AID_NOT_FOUND", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "429": {"description": "RATE_LIMITED (see Retry-After)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
        }
      }
    },
    "/v1/aid/search": {
      "get": {
        "operationId": "findHotel",
        "summary": "Find hotels and their Agentic IDs by name, city or GDS code",
        "description": "Returns candidates, never a guess. Give at least one parameter; several parameters narrow the result (AND).",
        "parameters": [
          {"name": "q", "in": "query", "schema": {"type": "string"}, "description": "Hotel name, alias, AID or any GDS code"},
          {"name": "city", "in": "query", "schema": {"type": "string"}, "description": "City or country (English)"},
          {"name": "sabre", "in": "query", "schema": {"type": "string", "examples": ["LW 004778"]}},
          {"name": "amadeus", "in": "query", "schema": {"type": "string", "examples": ["RZ USMRZR"]}},
          {"name": "galileo", "in": "query", "schema": {"type": "string"}, "description": "Galileo / Apollo code"},
          {"name": "worldspan", "in": "query", "schema": {"type": "string"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 50, "default": 20}}
        ],
        "responses": {
          "200": {"description": "Candidates (possibly none)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Candidates"}}}},
          "400": {"description": "INVALID_QUERY", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}},
          "429": {"description": "RATE_LIMITED", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Gds": {
        "type": "object",
        "properties": {
          "sabre": {"type": ["string", "null"], "examples": ["LW 004778"]},
          "amadeus": {"type": ["string", "null"], "examples": ["RZ USMRZR"]},
          "galileo_apollo": {"type": ["string", "null"]},
          "worldspan": {"type": ["string", "null"]}
        }
      },
      "Card": {
        "type": "object",
        "required": ["aid", "name", "url"],
        "properties": {
          "aid": {"type": "string", "pattern": "^AI-[0-9A-HJKMNP-TV-Z]{6}$"},
          "name": {"type": "string"},
          "city": {"type": ["string", "null"]},
          "country": {"type": ["string", "null"]},
          "country_code": {"type": ["string", "null"], "description": "ISO 3166-1 alpha-2"},
          "group": {"type": ["string", "null"]},
          "brand": {"type": ["string", "null"]},
          "gds": {"$ref": "#/components/schemas/Gds"},
          "website": {"type": ["string", "null"], "format": "uri"},
          "awards": {"type": "array", "items": {"type": "object"}},
          "status": {"type": "string", "enum": ["operating", "temporarily_closed"]},
          "url": {"type": "string", "format": "uri"},
          "resolved_from": {"type": "string", "description": "Present when the AID asked for belongs to a merged duplicate"},
          "paid_fields": {"type": "array", "items": {"type": "string"}, "description": "Fields available with a subscription"}
        }
      },
      "Candidates": {
        "type": "object",
        "properties": {
          "count": {"type": "integer"},
          "truncated": {"type": "boolean"},
          "candidates": {"type": "array", "items": {"type": "object", "properties": {
            "aid": {"type": "string"}, "name": {"type": "string"}, "city": {"type": ["string", "null"]},
            "country": {"type": ["string", "null"]}, "country_code": {"type": ["string", "null"]}, "url": {"type": "string"},
            "gds": {"$ref": "#/components/schemas/Gds"}, "matched_on": {"type": "array", "items": {"type": "string"}}}}}
        }
      },
      "Error": {
        "type": "object",
        "properties": {"error": {"type": "object", "required": ["code", "message"], "properties": {
          "code": {"type": "string", "enum": ["INVALID_AID", "AID_NOT_FOUND", "INVALID_QUERY", "RATE_LIMITED", "METHOD_NOT_ALLOWED", "NOT_FOUND", "SUBSCRIPTION_REQUIRED", "INTERNAL_ERROR"]},
          "message": {"type": "string"},
          "aid": {"type": "string"},
          "retry_after": {"type": "integer"}}}}
      }
    }
  }
}
