{
  "openapi": "3.1.0",
  "info": {
    "title": "Voyspark Public API",
    "version": "1.0.0",
    "description": "Public read endpoints for Voyspark: unified search, flight prices, hotel availability, and trip plan simulator. IP rate-limited.",
    "contact": {
      "email": "support@voyspark.com",
      "url": "https://voyspark.com/sobre/contato"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://voyspark.com/legal/termos"
    }
  },
  "servers": [
    {
      "url": "https://voyspark.com"
    }
  ],
  "paths": {
    "/api/search/spotlight": {
      "get": {
        "summary": "Unified search",
        "description": "Searches across articles, destinations, users, posts, hashtags, communities, stories, tools, and reservation verticals.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Query string"
          },
          {
            "name": "locale",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "pt-BR",
                "pt-PT",
                "en",
                "es",
                "fr",
                "it",
                "de"
              ],
              "default": "en"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results grouped by category",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpotlightResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/search/flights": {
      "get": {
        "summary": "Flight prices",
        "description": "Cheapest flight offers from Travelpayouts (Aviasales). Affiliate-tracked booking URLs.",
        "parameters": [
          {
            "name": "origin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            },
            "description": "IATA airport code"
          },
          {
            "name": "destination",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Z]{3}$"
            }
          },
          {
            "name": "depart",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "return",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "adults",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Flight offers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlightOffersResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/search/hotels": {
      "get": {
        "summary": "Hotel availability",
        "description": "Hotel offers from Hotellook. Affiliate-tracked booking URLs.",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "checkin",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "checkout",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "adults",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 2
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Hotel offers"
          }
        }
      }
    },
    "/api/trip-plans/simulator": {
      "post": {
        "summary": "Build trip plan draft (no persistence)",
        "description": "Combines cheapest flight + hotel + sample itinerary. Returns a draft payload that can be POSTed to /api/trip-plans to persist.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$"
                  },
                  "destination": {
                    "type": "string",
                    "pattern": "^[A-Z]{3}$"
                  },
                  "startDate": {
                    "type": "string",
                    "format": "date"
                  },
                  "endDate": {
                    "type": "string",
                    "format": "date"
                  },
                  "adults": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 1
                  },
                  "budget": {
                    "type": "number"
                  }
                },
                "required": [
                  "origin",
                  "destination",
                  "startDate",
                  "endDate"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trip plan draft"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Hit": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "article",
              "story",
              "destination",
              "tool",
              "search",
              "user",
              "post",
              "hashtag",
              "community"
            ]
          },
          "title": {
            "type": "string"
          },
          "excerpt": {
            "type": "string"
          },
          "href": {
            "type": "string"
          },
          "meta": {
            "type": "string"
          },
          "image": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "type",
          "title",
          "href"
        ]
      },
      "SpotlightResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string"
          },
          "articles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "stories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "destinations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "search": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "users": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "posts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "hashtags": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          },
          "communities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Hit"
            }
          }
        }
      },
      "FlightOffer": {
        "type": "object",
        "properties": {
          "airline": {
            "type": "string"
          },
          "flightNumber": {
            "type": "string"
          },
          "departureAt": {
            "type": "string",
            "format": "date-time"
          },
          "returnAt": {
            "type": "string",
            "format": "date-time"
          },
          "price": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "bookingUrl": {
            "type": "string",
            "format": "uri",
            "description": "Affiliate-tracked"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "FlightOffersResponse": {
        "type": "object",
        "properties": {
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FlightOffer"
            }
          }
        }
      }
    }
  }
}