openapi: "3.0.3"
info:
  title: therappai API
  version: "1.0.0"
  description: |
    Public API for therappai – an AI-powered mental wellbeing platform.
    This spec is based on the current Postman collection and is intended
    as a starting point for your official documentation.

servers:
  - url: https://api.therappai.com/api/v1
    description: Production
  - url: https://staging-api.therappai.com/api/v1
    description: Staging

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  responses:
    Unauthorized:
      description: Unauthorized – missing or invalid access token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        name:
          type: string
        profile_pic:
          type: string
          nullable: true
          description: URL of profile picture
    PersonalInfo:
      type: object
      properties:
        date_of_birth:
          type: string
          format: date
          nullable: true
        goals:
          type: string
          nullable: true
        therapy_focus:
          type: string
          nullable: true
        addiction_type:
          type: string
          nullable: true
        mood:
          type: string
          nullable: true
        contact_number:
          type: string
          nullable: true
    Therapist:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        specialty:
          type: string
          nullable: true
        avatar_id:
          type: string
          format: uuid
          nullable: true
    Content:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        duration_seconds:
          type: integer
          nullable: true
        tags:
          type: array
          items:
            type: string
    MoodCheckin:
      type: object
      properties:
        id:
          type: integer
        mood_value:
          type: integer
        slider_value:
          type: integer
          nullable: true
        note:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    EmergencyContact:
      type: object
      properties:
        id:
          type: integer
        full_name:
          type: string
        relationship:
          type: string
        phone_number:
          type: string
        email:
          type: string
          format: email
        address:
          type: string
          nullable: true
        photo_url:
          type: string
          nullable: true
    Avatar:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    Context:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    Voice:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
    Error:
      type: object
      properties:
        detail:
          type: string

security:
  - BearerAuth: []

paths:
  /signup/:
    post:
      summary: User signup
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, name, password, confirm_password]
              properties:
                email:
                  type: string
                  format: email
                name:
                  type: string
                password:
                  type: string
                confirm_password:
                  type: string
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "400":
          description: Validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /login/:
    post:
      summary: User login
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email:
                  type: string
                  format: email
                password:
                  type: string
      responses:
        "200":
          description: Tokens returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  access:
                    type: string
                  refresh:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"

  /profile/:
    get:
      summary: Get current user profile
      tags: [Users]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: User profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      summary: Update profile
      tags: [Users]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                name:
                  type: string
                profile_pic:
                  type: string
                  format: binary
      responses:
        "200":
          description: Updated user profile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /personal-info/:
    get:
      summary: Get personal info
      tags: [Users]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Personal info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonalInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      summary: Set or update personal info
      tags: [Users]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PersonalInfo"
      responses:
        "200":
          description: Updated personal info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonalInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"
    patch:
      summary: Partial update of personal info
      tags: [Users]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PersonalInfo"
      responses:
        "200":
          description: Updated personal info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PersonalInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /therapists/:
    get:
      summary: List therapists
      tags: [Therapists]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of therapists
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Therapist"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /select-therapist/:
    post:
      summary: Select a therapist for the current user
      tags: [Therapists]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [therapist]
              properties:
                therapist:
                  type: integer
      responses:
        "200":
          description: Therapist selected
        "401":
          $ref: "#/components/responses/Unauthorized"

  /selected-therapist/:
    get:
      summary: Get selected therapist
      tags: [Therapists]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Selected therapist
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Therapist"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /password-reset/request/:
    post:
      summary: Request password reset via email
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
      responses:
        "200":
          description: OTP sent if email exists

  /password-reset/verify-otp/:
    post:
      summary: Verify password reset OTP
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, otp]
              properties:
                email:
                  type: string
                  format: email
                otp:
                  type: string
      responses:
        "200":
          description: OTP valid

  /password-reset/change-password/:
    post:
      summary: Change password after OTP verification
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, new_password, confirm_password]
              properties:
                email:
                  type: string
                  format: email
                new_password:
                  type: string
                confirm_password:
                  type: string
      responses:
        "200":
          description: Password changed

  /change-password/:
    put:
      summary: Change password (logged-in user)
      tags: [Auth]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [old_password, new_password, confirm_password]
              properties:
                old_password:
                  type: string
                new_password:
                  type: string
                confirm_password:
                  type: string
      responses:
        "200":
          description: Password changed
        "401":
          $ref: "#/components/responses/Unauthorized"

  /refresh/:
    post:
      summary: Refresh access token
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh]
              properties:
                refresh:
                  type: string
      responses:
        "200":
          description: New access token
          content:
            application/json:
              schema:
                type: object
                properties:
                  access:
                    type: string

  /logout/:
    post:
      summary: Logout and revoke refresh token
      tags: [Auth]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [refresh]
              properties:
                refresh:
                  type: string
      responses:
        "200":
          description: Logged out
        "401":
          $ref: "#/components/responses/Unauthorized"

  /delete-account/:
    delete:
      summary: Delete current account
      tags: [Auth]
      security:
        - BearerAuth: []
      responses:
        "204":
          description: Account deleted
        "401":
          $ref: "#/components/responses/Unauthorized"

  /chatting/:
    post:
      summary: Send chat or voice message to AI therapist
      tags: [Chat]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                message:
                  type: string
                  format: binary
                  description: Audio file
                type:
                  type: string
                  description: "Message type (e.g. audio, text)"
      responses:
        "200":
          description: AI response
        "401":
          $ref: "#/components/responses/Unauthorized"

  /contents/:
    get:
      summary: List content items
      tags: [Content]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of content
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Content"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /contents/{id}/:
    get:
      summary: Get content details
      tags: [Content]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Content details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Content"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /contents/{id}/favorite/:
    post:
      summary: Mark content as favourite
      tags: [Content]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Marked as favourite
        "401":
          $ref: "#/components/responses/Unauthorized"

  /contents/{id}/download/:
    post:
      summary: Trigger content download
      tags: [Content]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Download started
        "401":
          $ref: "#/components/responses/Unauthorized"

  /contents/{id}/transcript/generate/:
    post:
      summary: Generate transcript for content
      tags: [Content]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "202":
          description: Transcript generation started
        "401":
          $ref: "#/components/responses/Unauthorized"

  /contents/{id}/transcript/:
    get:
      summary: Get content transcript
      tags: [Content]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Transcript
          content:
            application/json:
              schema:
                type: object
                properties:
                  transcript:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"

  /contents/{id}/update_progress/:
    patch:
      summary: Update user progress for content
      tags: [Content]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                last_position:
                  type: integer
                  description: "Seconds"
                is_completed:
                  type: boolean
      responses:
        "200":
          description: Progress updated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /mood/checkin/:
    post:
      summary: Create mood check-in
      tags: [Mood]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mood_value]
              properties:
                mood_value:
                  type: integer
                slider_value:
                  type: integer
                  nullable: true
                note:
                  type: string
                  nullable: true
      responses:
        "201":
          description: Mood check-in created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MoodCheckin"
        "401":
          $ref: "#/components/responses/Unauthorized"
    get:
      summary: List mood check-ins
      tags: [Mood]
      security:
        - BearerAuth: []
      parameters:
        - name: from
          in: query
          schema:
            type: string
            format: date
        - name: to
          in: query
          schema:
            type: string
            format: date
        - name: page
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Mood check-ins
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/MoodCheckin"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /mood/insights/mood-over-time/:
    get:
      summary: Mood over time
      tags: [Mood]
      security:
        - BearerAuth: []
      parameters:
        - name: days
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Mood trend data
        "401":
          $ref: "#/components/responses/Unauthorized"

  /mood/insights/summary/:
    get:
      summary: Mood summary
      tags: [Mood]
      security:
        - BearerAuth: []
      parameters:
        - name: range
          in: query
          schema:
            type: string
            enum: [week, month, custom]
      responses:
        "200":
          description: Mood summary
        "401":
          $ref: "#/components/responses/Unauthorized"

  /mood/insights/calendar/:
    get:
      summary: Mood calendar view
      tags: [Mood]
      security:
        - BearerAuth: []
      parameters:
        - name: year
          in: query
          schema:
            type: integer
        - name: month
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: Calendar data
        "401":
          $ref: "#/components/responses/Unauthorized"

  /emergency-contacts/:
    post:
      summary: Create emergency contact
      tags: [Emergency Contacts]
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [full_name, relationship, phone_number, email]
              properties:
                full_name:
                  type: string
                relationship:
                  type: string
                phone_number:
                  type: string
                email:
                  type: string
                  format: email
                address:
                  type: string
                  nullable: true
                photo:
                  type: string
                  format: binary
      responses:
        "201":
          description: Emergency contact created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmergencyContact"
        "401":
          $ref: "#/components/responses/Unauthorized"
    get:
      summary: List emergency contacts
      tags: [Emergency Contacts]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of contacts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EmergencyContact"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /emergency-contacts/{id}/:
    get:
      summary: Get emergency contact
      tags: [Emergency Contacts]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Contact details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmergencyContact"
        "401":
          $ref: "#/components/responses/Unauthorized"
    patch:
      summary: Update emergency contact
      tags: [Emergency Contacts]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EmergencyContact"
      responses:
        "200":
          description: Contact updated
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      summary: Delete emergency contact
      tags: [Emergency Contacts]
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "204":
          description: Contact deleted
        "401":
          $ref: "#/components/responses/Unauthorized"

  /liveavatar/public-avatars/:
    get:
      summary: List public avatars
      tags: [Live Avatar]
      responses:
        "200":
          description: List of avatars
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Avatar"

  /liveavatar/avatars/{id}:
    get:
      summary: Get avatar by ID
      tags: [Live Avatar]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Avatar details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Avatar"

  /liveavatar/contexts/:
    get:
      summary: List contexts
      tags: [Live Avatar]
      responses:
        "200":
          description: List of contexts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Context"

  /liveavatar/contexts/{id}:
    get:
      summary: Get context by ID
      tags: [Live Avatar]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Context details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Context"

  /liveavatar/voices/:
    get:
      summary: List voices
      tags: [Live Avatar]
      responses:
        "200":
          description: List of voices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Voice"

  /liveavatar/voices/{id}:
    get:
      summary: Get voice by ID
      tags: [Live Avatar]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Voice details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Voice"

  /liveavatar/sessions/token/:
    post:
      summary: Create avatar session token
      tags: [Live Avatar]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [mode, avatar_id, avatar_persona]
              properties:
                mode:
                  type: string
                avatar_id:
                  type: string
                avatar_persona:
                  type: object
                  properties:
                    context_id:
                      type: string
      responses:
        "200":
          description: Session token created

  /liveavatar/sessions/start/:
    post:
      summary: Start avatar session
      tags: [Live Avatar]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [session_token]
              properties:
                session_token:
                  type: string
      responses:
        "200":
          description: Session started

  /liveavatar/sessions/stop/:
    post:
      summary: Stop avatar session
      tags: [Live Avatar]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [session_token]
              properties:
                session_token:
                  type: string
      responses:
        "200":
          description: Session stopped

  /liveavatar/keep-alive-session/:
    post:
      summary: Keep avatar session alive
      tags: [Live Avatar]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [session_token]
              properties:
                session_token:
                  type: string
      responses:
        "200":
          description: Session refreshed

  /daily-tasks/:
    get:
      summary: Get user daily tasks
      tags: [Tasks]
      security:
        - BearerAuth: []
      responses:
        "200":
          description: List of daily tasks
        "401":
          $ref: "#/components/responses/Unauthorized"
