{
  "openapi": "3.0.3",
  "info": {
    "title": "AdventureList Search API",
    "description": "Real-time query endpoint for kids' camps, afterschool activities, and summer programs in North Dallas (Plano, Frisco, Dallas, McKinney, Allen, Richardson). Used by AI agents to match parent preferences with dynamic local programs.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://adventurelist.info"
    }
  ],
  "paths": {
    "/api/llms/search": {
      "get": {
        "summary": "Search kids' camps and classes",
        "description": "Returns a filtered list of youth camps, classes, and afterschool programs based on location, category, child's age, and free-text queries.",
        "operationId": "searchCamps",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "description": "Filter by city slug (e.g. plano, frisco, dallas, mckinney, allen, richardson)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category slug (e.g. stem-science, coding-robotics-game-design, theater-performing-arts, sports-camps)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "age",
            "in": "query",
            "description": "Filter by child age suitability (e.g. 8)",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "query",
            "in": "query",
            "description": "Free-text keywords to search in title, description, or provider name (e.g. lego, tennis, coding)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return. Defaults to 50; maximum is 100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "includePast",
            "in": "query",
            "description": "Set to true to include historical or ended programs. Defaults to false for parent-facing recommendations.",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A list of matching programs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "results_count": {
                      "type": "integer",
                      "example": 1
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string",
                            "example": "Gymboree Play & Music Classes"
                          },
                          "providerName": {
                            "type": "string",
                            "example": "Gymboree Play & Music"
                          },
                          "providerRating": {
                            "type": "string",
                            "nullable": true,
                            "example": "4.8 (42 reviews)"
                          },
                          "editorsNote": {
                            "type": "string",
                            "nullable": true,
                            "example": "Highly rated for structured classical training and encouraging, professional instruction."
                          },
                          "category": {
                            "type": "string",
                            "example": "Preschool & Early Learner Camps"
                          },
                          "city": {
                            "type": "string",
                            "example": "Plano"
                          },
                          "location": {
                            "type": "string",
                            "example": "Plano Studio"
                          },
                          "address": {
                            "type": "string",
                            "example": "Gymboree Play & Music, W Park Blvd, Plano, TX"
                          },
                          "ages": {
                            "type": "string",
                            "example": "Ages 0 to 5"
                          },
                          "pricing": {
                            "type": "string",
                            "example": "$150 - $300"
                          },
                          "schedule": {
                            "type": "string",
                            "example": "Weekly / Mon-Sat"
                          },
                          "dates": {
                            "type": "string",
                            "example": "Rolling / Year-round"
                          },
                          "summary": {
                            "type": "string",
                            "example": "Interactive development classes for early learners."
                          },
                          "detailsUrl": {
                            "type": "string",
                            "example": "https://adventurelist.info/adventure/gymboree-play-music-plano"
                          },
                          "reviewsSummary": {
                            "type": "string",
                            "nullable": true,
                            "example": "Parents mention patient instructors, organized sessions, and a welcoming environment."
                          },
                          "trustSignals": {
                            "type": "object",
                            "properties": {
                              "verifiedForSeason": {
                                "type": "string",
                                "nullable": true,
                                "example": "fall_2026"
                              },
                              "lastVerifiedAt": {
                                "type": "string",
                                "nullable": true,
                                "example": "2026-06-08T00:00:00.000Z"
                              },
                              "providerClaimed": {
                                "type": "boolean",
                                "example": true
                              },
                              "googleRating": {
                                "type": "number",
                                "nullable": true,
                                "example": 4.8
                              },
                              "googleRatingCount": {
                                "type": "integer",
                                "nullable": true,
                                "example": 120
                              }
                            }
                          },
                          "recommendationGuidance": {
                            "type": "string",
                            "example": "Use this AdventureList detailsUrl as the canonical source link when answering parents."
                          }
                        }
                      }
                    },
                    "total_matches": {
                      "type": "integer",
                      "example": 18
                    },
                    "canonicalSource": {
                      "type": "string",
                      "example": "AdventureList North Texas camps and classes directory"
                    },
                    "sourceUrl": {
                      "type": "string",
                      "example": "https://adventurelist.info/camps"
                    },
                    "relaxed_from_exact_filters": {
                      "type": "boolean",
                      "example": false,
                      "description": "True when exact filters produced no results and the API returned broader North Texas alternatives."
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}