openapi: 3.1.0
info:
  title: Tinder API
  description: >
    This is an OpenAPI specification for a subset of the Tinder API endpoints.
    It covers basic functionality including authentication, user actions (like/pass),
    and recommendations.
  version: "1.0.0"
servers:
  - url: https://tinder.cloonar.com
paths:
  /like/{user_id}:
    get:
      operationId: likeUser
      summary: Like a user
      description: >
        Call this endpoint to "like" a user. In the Tinder app the like action is performed
        when you swipe right or tap the heart.
      parameters:
        - name: user_id
          in: path
          description: The Tinder user ID of the profile to like.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful like response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  match:
                    type: boolean
                  likes_remaining:
                    type: integer
                  X-Padding:
                    type: string
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pass/{user_id}:
    get:
      operationId: passUser
      summary: Pass on a user
      description: >
        Call this endpoint to “pass” (dislike) a user. In the Tinder app this action happens
        when you swipe left or tap the red X.
      parameters:
        - name: user_id
          in: path
          description: The Tinder user ID of the profile to pass.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful pass response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: A status message or code.
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/recs/core:
    get:
      operationId: getRecsCore
      summary: Get Recommendations
      description: >
        Retrieves a list of recommended Tinder profiles. An optional locale query parameter can be provided.
      parameters:
        - name: locale
          in: query
          description: Locale for recommendations (e.g. "en").
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of recommended profiles.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      status:
                        type: integer
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          $ref: '#/components/schemas/UserRecommendation'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v2/auth/sms/send:
    post:
      operationId: sendPhoneLogin
      summary: Send OTP code
      description: Initiate phone authentication by requesting an OTP code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_number:
                  type: string
                  description: The phone number to send the OTP to
              required:
                - phone_number
      responses:
        '200':
          description: SMS sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        default:
          $ref: '#/components/responses/Error'

  /v2/auth/sms/validate:
    post:
      operationId: validateOTP
      summary: Validate OTP
      description: Complete phone authentication by validating the OTP code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone_number:
                  type: string
                  description: The phone number the OTP was sent to
                otp:
                  type: string
                  description: The OTP code received via SMS
              required:
                - phone_number
                - otp
      responses:
        '200':
          description: OTP validated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        default:
          $ref: '#/components/responses/Error'

  /v2/auth/facebook:
    post:
      operationId: facebookAuth
      summary: Facebook Authentication
      description: Authenticate using Facebook credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                facebook_id:
                  type: string
                  description: Facebook user ID
                facebook_token:
                  type: string
                  description: Facebook access token
              required:
                - facebook_id
                - facebook_token
      responses:
        '200':
          description: Facebook authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        default:
          $ref: '#/components/responses/Error'

  /v2/auth/login/refresh:
    post:
      operationId: refreshAuth
      summary: Refresh Authentication
      description: Refresh the authentication token using a refresh token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
                  description: The refresh token obtained from a previous authentication
              required:
                - refresh_token
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        default:
          $ref: '#/components/responses/Error'

  /v2/profile:
    get:
      operationId: getProfile
      summary: Get User Profile
      description: Retrieve the authenticated user's profile information
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Profile retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileResponse'
        default:
          $ref: '#/components/responses/Error'

components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
    UserRecommendation:
      type: object
      properties:
        type:
          type: string
        user:
          type: object
          properties:
            _id:
              type: string
            bio:
              type: string
            birth_date:
              type: string
              format: date-time
            name:
              type: string
            photos:
              type: array
              items:
                $ref: '#/components/schemas/Photo'
            gender:
              type: integer
            jobs:
              type: array
              items:
                type: object
            schools:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
        instagram:
          type: object
          properties:
            last_fetch_time:
              type: string
              format: date-time
            completed_initial_fetch:
              type: boolean
            photos:
              type: array
              items:
                $ref: '#/components/schemas/InstagramPhoto'
            media_count:
              type: integer
            profile_picture:
              type: string
        facebook:
          type: object
          properties:
            common_connections:
              type: array
              items:
                type: object
            connection_count:
              type: integer
            common_interests:
              type: array
              items:
                type: object
        spotify:
          type: object
          properties:
            spotify_connected:
              type: boolean
            spotify_theme_track:
              type: object
              description: Track info (partial schema – extend as needed)
        distance_mi:
          type: integer
        content_hash:
          type: string
        s_number:
          type: integer
        teaser:
          type: object
          properties:
            type:
              type: string
            string:
              type: string
        teasers:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              string:
                type: string
    Photo:
      type: object
      properties:
        id:
          type: string
        crop_info:
          type: object
          properties:
            user:
              type: object
              properties:
                width_pct:
                  type: number
                x_offset_pct:
                  type: number
                height_pct:
                  type: number
                y_offset_pct:
                  type: number
            algo:
              type: object
              properties:
                width_pct:
                  type: number
                x_offset_pct:
                  type: number
                height_pct:
                  type: number
                y_offset_pct:
                  type: number
            processed_by_bullseye:
              type: boolean
            user_customized:
              type: boolean
        url:
          type: string
        processedFiles:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              height:
                type: integer
              width:
                type: integer
        fileName:
          type: string
        extension:
          type: string
        main:
          type: boolean
    InstagramPhoto:
      type: object
      properties:
        image:
          type: string
        thumbnail:
          type: string
        ts:
          type: string
        link:
          type: string
    AuthResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: integer
            message:
              type: string
        data:
          type: object
          properties:
            api_token:
              type: string
              description: The authentication token to use for subsequent requests
            refresh_token:
              type: string
              description: Token that can be used to refresh the authentication
            is_new_user:
              type: boolean
              description: Whether this is a new user account
            sms_sent:
              type: boolean
              description: Whether an SMS was sent (for phone authentication)

    ProfileResponse:
      type: object
      properties:
        meta:
          type: object
          properties:
            status:
              type: integer
        data:
          type: object
          properties:
            user:
              type: object
              properties:
                _id:
                  type: string
                bio:
                  type: string
                name:
                  type: string

  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    BearerAuth:
      type: apiKey
      in: header
      name: X-Auth-Token