docs

gistfile1.txt

openapi: 3.0.3
info:
  title: GuestJourneyAI REST API
  version: 0.0.1
  description: Developer facing REST API for the hotel recommender system, ready to be integrated into your application

servers:
  - url: https://journey.yanovis.com
    description: Production Deployment
  - url: https://journey-staging.yanovis.com
    description: Staging Deployment

paths:
  /recommendations:
    get:
      summary: Get recommendations for a user
      description: Fetch relevant content recommendations based on the user and realm.
      security:
        - apiKeyAuth: []
      parameters:
        - name: realm
          in: query
          required: true
          description: The realm of the content (e.g., "carlito-surroundings", "carlito-bookito", "yanovis-sales").
          schema:
            type: string
            example: carlito-surroundings
        - name: user_id
          in: query
          required: false
          description: The actual user ID if the user is logged in.
          schema:
            type: string
            example: 987654321
        - name: anonymous_user
          in: query
          required: false
          description: The anonymous ID provided by the tracking script if the user is not logged in.
          schema:
            type: string
            example: abcde12345
        - name: book_for
          in: query
          required: false
          description: ISO Datestring for when the relevant content should be displayed. Used for time-sensitive recommendations.
          schema:
            type: string
            format: date
            example: 2024-12-25
        - name: duration
          in: query
          required: false
          description: The duration in days. Currently relevant for room bookings.
          schema:
            type: integer
            example: 7
      responses:
        "200":
          description: Successful response with recommendations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  payload:
                    type: object
                    properties:
                      realm:
                        type: string
                        description: The realm provided in the request.
                        example: carlito-surroundings
                      recommendations:
                        type: array
                        items:
                          type: object
                          properties:
                            score:
                              type: number
                              format: float
                              description: The score of the recommendation.
                              example: 0.75
                            id:
                              type: string
                              description: The ID of the recommended item.
                              example: "1234"
                            tags:
                              type: array
                              items:
                                type: string
                              description: Tags associated with the recommendation.
                              example:
                                ["family-friendly", "mountain-view", "spa"]

        "400":
          description: Bad Request - Invalid or missing parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "Either user_id or anonymous_user must be specified."
        "500":
          description: Internal Server Error - Unexpected issue.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: "An unexpected error occurred."

components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: API-Key
  parameters:
    userIdOrAnonymousId:
      name: user_id_or_anonymous_user
      in: query
      required: true
      description: Either user_id or anonymous_user must be provided.
      schema:
        oneOf:
          - type: string
            description: user_id (Actual User ID)
          - type: string
            description: anonymous_user (Anonymous ID)