openapi: 3.1.0
info:
  title: OffersBeat AI Hotel Discovery / Verified Offers
  version: 1.0.0
  description: >
    Stage AI-2. Discovery provides public, published hotel pages, not prices or availability.
    Live verified offers require approved enterprise credentials and an anonymous-owned,
    finalized intent. This API does not book rooms or replace the hotel checkout.
servers:
  - url: https://offersbeat.com
paths:
  /api/v1/ai-discovery/hotels:
    get:
      operationId: listPublishedHotels
      summary: Discover hotels with publicly published offer rules
      parameters:
        - {name: locale, in: query, schema: {type: string, enum: [el, en], default: en}}
        - {name: country, in: query, schema: {type: string, minLength: 2, maxLength: 2}}
        - {name: city, in: query, schema: {type: string, maxLength: 120}}
        - {name: name, in: query, schema: {type: string, maxLength: 120}}
        - {name: page, in: query, schema: {type: integer, minimum: 1, maximum: 40, default: 1}}
        - {name: per_page, in: query, schema: {type: integer, minimum: 1, maximum: 25, default: 20}}
      responses:
        '200':
          description: Hotels eligible for published SEO pages, NOT live rate quotations
          content:
            application/json:
              schema: {type: object}
        '422': {description: Invalid query}
        '429': {description: Rate limited}
  /api/v1/ai-discovery/hotels/{propertyKey}:
    get:
      operationId: getPublishedHotel
      summary: Get a published hotel and its non-priced offer rules
      parameters:
        - {name: propertyKey, in: path, required: true, schema: {type: string}}
        - {name: locale, in: query, schema: {type: string, enum: [el, en], default: en}}
      responses:
        '200': {description: Hotel profile; final price and inventory not checked}
        '404': {description: Hotel not published or not found}
  /api/v1/enterprise/ai/intents/{intentId}/offers:
    get:
      operationId: listVerifiedHotelOffers
      summary: Read live, public, selectable offers from an already-finalized hotel intent
      security:
        - enterpriseBearer: []
      parameters:
        - {name: intentId, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: locale, in: query, schema: {type: string, enum: [el, en], default: en}}
        - name: X-OffersBeat-Anonymous-Token
          in: header
          required: true
          schema: {type: string}
          description: Must own the intent; enterprise credential must have offers.read scope.
      responses:
        '200': {description: Public-policy-eligible, fresh offers and recheck links; NOT booking confirmation}
        '401': {description: Enterprise authentication or anonymous token failed}
        '403': {description: Enterprise scope denied}
        '404': {description: Intent unavailable/not owned}
        '409': {description: Collection not finalized}
        '410': {description: Intent expired}
        '422': {description: Not a hotel intent}
components:
  securitySchemes:
    enterpriseBearer:
      type: http
      scheme: bearer
      bearerFormat: OffersBeat Enterprise API credential