openapi: 3.0.3
info:
  title: POPPYCORN TV API
  description: Production API documentation for POPPYCORN TV. Includes Smart TV hardware
    endpoints (Android TV, Firestick, Apple TV), Web Portal account management, Playlist
    synchronization, Stripe payments, and Reseller services.
  version: 1.0.0
  contact:
    name: POPPYCORN TV Support Desk
    url: https://poppycorn.tv/contact-us
    email: support@poppycorn.tv
servers:
- url: https://poppycorn.tv
  description: Production Server (HTTPS)
- url: http://localhost:4321
  description: Local Development Server
tags:
- name: Smart TV Core APIs
  description: Endpoints queried directly by Android TV, Firestick, and Apple TV APKs
- name: Playlists Management
  description: IPTV Playlist CRUD operations (Xtream Codes API & M3U URLs)
- name: Account & Subscription
  description: Subscription status check, device pairing, and remote force-sync
- name: Activation & Payments
  description: Plans catalog and Stripe PaymentIntent activation workflows
- name: Authentication
  description: Reseller and user authentication endpoints
- name: Tools & Diagnostics
  description: Xtream server checker, contact form, and system health status
paths:
  /checkaccount:
    get:
      tags:
      - Smart TV Core APIs
      summary: Verify Smart TV Device License
      description: 'Authenticates the TV device using email or device hardware key.
        Returns subscription status: 1 = Active/Authorized, 2 = Max devices limit
        exceeded, 0 = Inactive/Not found.'
      operationId: checkAccount
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
        description: Account email or serial key
      - name: key
        in: query
        required: false
        schema:
          type: string
        description: Device hardware key / Serial Key (or device_key)
      - name: device_key
        in: query
        required: false
        schema:
          type: string
        description: Alias for key
      - name: emailId
        in: query
        required: false
        schema:
          type: string
        description: Hardware device unique ID
      - name: deviceName
        in: query
        required: false
        schema:
          type: string
        description: Device model name (e.g. Amazon AFTMM)
      responses:
        '200':
          description: Verification status code
          content:
            text/html:
              schema:
                type: string
                enum:
                - '1'
                - '2'
                - '0'
                example: '1'
      security:
      - {}
  /getplaylists:
    get:
      tags:
      - Smart TV Core APIs
      - Playlists Management
      summary: Retrieve Playlists for Smart TV
      description: Fetches all active playlists (Xtream Codes credentials & M3U streams)
        configured for the device.
      operationId: getPlaylists
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
        description: Account email
      - name: key
        in: query
        required: false
        schema:
          type: string
        description: Device Serial Key
      responses:
        '200':
          description: Array of playlists configured for the account
          content:
            application/json:
              schema:
                type: array
                items:
                  ? ''
                  : '#/components/schemas/Playlist'
      security:
      - {}
  /events:
    get:
      tags:
      - Smart TV Core APIs
      summary: Get TV Slider Events & Banners
      description: Returns active banner slides, promotional events, and announcements
        for the Smart TV home slider.
      operationId: getEventSlides
      responses:
        '200':
          description: List of active event slides
          content:
            application/json:
              schema:
                type: array
                items:
                  ? ''
                  : '#/components/schemas/EventSlide'
      security:
      - {}
  /accountinfo:
    get:
      tags:
      - Smart TV Core APIs
      - Account & Subscription
      summary: Get Account Details & Master PIN
      description: Returns account plan type, expiration date, max devices count,
        active status, force_sync_at timestamp, and master PIN for authenticated owner.
      operationId: getAccountInfo
      parameters:
      - name: email
        in: query
        required: false
        schema:
          type: string
      - name: key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Account details object
          content:
            application/json:
              schema:
                ? ''
                : '#/components/schemas/AccountInfo'
        '404':
          description: Account not found
      security:
      - {}
  /createaccount:
    get:
      tags:
      - Smart TV Core APIs
      summary: Auto-Register New TV Device / Free Trial
      description: Initializes a new account or links a new hardware device on first
        app launch.
      operationId: createAccount
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: key
        in: query
        required: false
        schema:
          type: string
      - name: emailId
        in: query
        required: false
        schema:
          type: string
      - name: deviceName
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: 1 = success, 0 = failed
          content:
            text/html:
              schema:
                type: string
                example: '1'
      security:
      - {}
  /setplaylist:
    get:
      tags:
      - Playlists Management
      summary: Create Playlist (Legacy Endpoint)
      description: Adds a new IPTV playlist to an account via query parameters.
      operationId: setPlaylist
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: name
        in: query
        required: false
        schema:
          type: string
        example: My IPTV
      - name: username
        in: query
        required: false
        schema:
          type: string
      - name: password
        in: query
        required: false
        schema:
          type: string
      - name: url
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Playlist creation result text
      security:
      - {}
  /deleteplaylist:
    get:
      tags:
      - Playlists Management
      summary: Delete Playlist (Legacy Endpoint)
      description: Removes a playlist by ID from an account.
      operationId: deletePlaylistLegacy
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: playlist_id
        in: query
        required: true
        schema:
          type: string
      - name: key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Playlist deletion result text
        '403':
          description: Unauthorized device key
      security:
      - {}
  /getdevices:
    get:
      tags:
      - Account & Subscription
      summary: List Connected TV Devices
      description: Lists all active hardware devices paired with the account.
      operationId: getDevices
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Array of registered devices
          content:
            application/json:
              schema:
                type: array
                items:
                  ? ''
                  : '#/components/schemas/Device'
      security:
      - {}
  /removedevice:
    get:
      tags:
      - Account & Subscription
      summary: Remove / Unpair TV Device
      description: Unlinks a hardware device slot from the account.
      operationId: removeDevice
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: device_id
        in: query
        required: true
        schema:
          type: string
      - name: key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Device disconnected successfully
      security:
      - {}
  /changekey:
    get:
      tags:
      - Account & Subscription
      summary: Update Account Device Key
      description: Updates the primary device key associated with an email account.
      operationId: changeKey
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
      - name: device_key
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ok
      security:
      - {}
  /account-lookup:
    post:
      tags:
      - Account & Subscription
      summary: Lookup Subscription by Serial Key or Email
      description: Checks subscription status, plan name, devices connected, and playlists
        for web users entering via /check-account or Smart TV QR code.
      operationId: accountLookup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - identifier
              properties:
                identifier:
                  type: string
                  example: POPPY-7842-9912
      responses:
        '200':
          description: Detailed account summary
          content:
            application/json:
              schema:
                ? ''
                : '#/components/schemas/AccountLookupResponse'
        '404':
          description: Account not found
      security:
      - {}
  /api/account/status-actions:
    post:
      tags:
      - Account & Subscription
      summary: Execute Account Actions (Force-Sync, Disconnect, Filters)
      description: 'Performs management actions: force-sync (remote trigger for Smart
        TV to refresh data), disconnect-device, rename-device, and update-filters.'
      operationId: statusActions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - action
              properties:
                email:
                  type: string
                  example: user@example.com
                action:
                  type: string
                  enum:
                  - force-sync
                  - disconnect-device
                  - rename-device
                  - update-filters
                  example: force-sync
                device_key:
                  type: string
                  description: Required for disconnect-device & rename-device
                custom_name:
                  type: string
                  description: Required for rename-device
                parental_locked:
                  type: boolean
                hide_live:
                  type: boolean
                hide_movies:
                  type: boolean
                hide_series:
                  type: boolean
      responses:
        '200':
          description: Action executed successfully
        '400':
          description: Missing parameters or action failed
      security:
      - {}
  /api/playlist/list:
    get:
      tags:
      - Playlists Management
      summary: List Playlists (Web Portal)
      description: Returns sanitized playlist list for web management dashboard.
      operationId: listPlaylistsWeb
      parameters:
      - name: identifier
        in: query
        required: true
        schema:
          type: string
        description: Serial Key or Email
      responses:
        '200':
          description: List of user playlists with masked sensitive credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  count:
                    type: integer
                    example: 2
                  playlists:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        type:
                          type: string
                          enum:
                          - xtream
                          - m3u
                        host:
                          type: string
                        status:
                          type: integer
                        createdAt:
                          type: string
                          format: date-time
      security:
      - {}
  /api/playlist/xtream:
    post:
      tags:
      - Playlists Management
      summary: Add Xtream Codes Playlist
      description: Creates a new Xtream Codes API playlist for the account.
      operationId: addXtreamPlaylist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - host
              - username
              - password
              properties:
                email:
                  type: string
                  description: Serial key or email
                  example: POPPY-7842-9912
                playlist_name:
                  type: string
                  example: Sports & Movies
                host:
                  type: string
                  example: http://iptv.server.io:8080
                username:
                  type: string
                  example: iptv_user
                password:
                  type: string
                  example: iptv_pass
      responses:
        '200':
          description: Playlist added successfully
        '400':
          description: Validation error
      security:
      - {}
  /api/playlist/m3u:
    post:
      tags:
      - Playlists Management
      summary: Add M3U Playlist
      description: Creates a new M3U/M3U8 link playlist for the account.
      operationId: addM3uPlaylist
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - playlist_url
              properties:
                email:
                  type: string
                  example: POPPY-7842-9912
                playlist_name:
                  type: string
                  example: My Stream List
                playlist_url:
                  type: string
                  example: https://example.com/playlist.m3u8
      responses:
        '200':
          description: Playlist added successfully
      security:
      - {}
  /api/playlist/delete:
    post:
      tags:
      - Playlists Management
      summary: Delete Playlist (Web Portal)
      description: Deletes a playlist by ID or Name.
      operationId: deletePlaylistWeb
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  example: POPPY-7842-9912
                playlist_id:
                  type: integer
                  example: 105
                playlist_name:
                  type: string
                  example: Sports & Movies
      responses:
        '200':
          description: Playlist removed successfully
      security:
      - {}
  /api/plans.json:
    get:
      tags:
      - Activation & Payments
      summary: Get Public Pricing Plans & Packages
      description: Fetches live grouped pricing tiers (1-Year, Lifetime) with multi-device
        pricing variations and reseller credit tiers.
      operationId: getPlansCatalog
      responses:
        '200':
          description: Plans catalog object
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  groupedPlans:
                    type: array
                    items:
                      type: object
                  allPlans:
                    type: array
                    items:
                      type: object
                  reseller:
                    type: object
      security:
      - {}
  /api/activation/create-intent:
    post:
      tags:
      - Activation & Payments
      summary: Create Stripe PaymentIntent
      description: Initializes a secure Stripe PaymentIntent for a selected device
        key and plan ID.
      operationId: createPaymentIntent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - device_key
              - plan_id
              properties:
                device_key:
                  type: string
                  example: POPPY-7842-9912
                plan_id:
                  type: integer
                  example: 20
                email:
                  type: string
                  example: customer@example.com
      responses:
        '200':
          description: Stripe clientSecret and payment details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  clientSecret:
                    type: string
                    example: pi_3MtwBwLkdIwHu7ix28a3tqPa_secret_YrkjAWQsNWBuZQIO9pHm
                  amount:
                    type: number
                    example: 7.0
                  currency:
                    type: string
                    example: USD
                  planName:
                    type: string
                    example: 1 Year Activation
        '400':
          description: Validation or device not found error
      security:
      - {}
  /api/activation/confirm:
    post:
      tags:
      - Activation & Payments
      summary: Confirm Payment & Activate Device
      description: Verifies the completed Stripe PaymentIntent directly with Stripe
        API, validates metadata, and unlocks the device account in MySQL.
      operationId: confirmActivation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - payment_intent_id
              - device_key
              - plan_id
              properties:
                payment_intent_id:
                  type: string
                  example: pi_3MtwBwLkdIwHu7ix28a3tqPa
                device_key:
                  type: string
                  example: POPPY-7842-9912
                plan_id:
                  type: integer
                  example: 20
                email:
                  type: string
                  example: customer@example.com
      responses:
        '200':
          description: Device activated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Device activated successfully.
        '400':
          description: Payment not confirmed or verification mismatch
      security:
      - {}
  /api/iptv-check:
    post:
      tags:
      - Tools & Diagnostics
      summary: Test Xtream IPTV Server Connection
      description: Server-side validator with SSRF protection that connects to Xtream
        Codes player_api.php, testing authentication and returning account expiration
        info.
      operationId: checkIptvServer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - server
              properties:
                server:
                  type: string
                  example: http://line.iptvservice.com:8080
                username:
                  type: string
                  example: streamuser
                password:
                  type: string
                  example: streampass
      responses:
        '200':
          description: Connection and stream diagnostics
        '403':
          description: Private or loopback IP address forbidden (SSRF protection)
      security:
      - {}
  /api/contact:
    post:
      tags:
      - Tools & Diagnostics
      summary: Submit Support Desk Inquiry
      description: Records a customer support message into the system.
      operationId: submitContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - email
              - message
              properties:
                name:
                  type: string
                  example: Alex Johnson
                email:
                  type: string
                  example: alex@example.com
                subject:
                  type: string
                  example: Smart TV activation help
                message:
                  type: string
                  example: Need assistance with Firestick Downloader code.
      responses:
        '200':
          description: Message recorded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
      security:
      - {}
  /api/health-check:
    get:
      tags:
      - Tools & Diagnostics
      summary: System & Database Health Check
      description: Validates MySQL connection pool and test account querying.
      operationId: healthCheck
      responses:
        '200':
          description: Health status object
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  db_connected:
                    type: boolean
                    example: true
      security:
      - {}
  /api/auth/login:
    post:
      tags:
      - Authentication
      summary: Reseller & Admin Login
      description: Authenticates reseller accounts with bcrypt password verification.
      operationId: authLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - password
              properties:
                email:
                  type: string
                  example: reseller@poppycorn.tv
                password:
                  type: string
                  example: SecurePassword123!
      responses:
        '200':
          description: Authentication successful
        '401':
          description: Invalid credentials
      security:
      - {}
components:
  schemas:
    Playlist:
      type: object
      properties:
        id:
          type: integer
          example: 12
        playlistName:
          type: string
          example: Cinema & Sports HD
        username:
          type: string
          example: user123
        password:
          type: string
          example: pass123
        playlistLink:
          type: string
          example: http://server.iptv:8080/get.php?username=...
        account_id:
          type: integer
          example: 45
        status:
          type: integer
          example: 1
        sort_order:
          type: integer
          example: 0
        parental_locked:
          type: integer
          example: 0
        hide_live:
          type: integer
          example: 0
        hide_movies:
          type: integer
          example: 0
        hide_series:
          type: integer
          example: 0
    EventSlide:
      type: object
      properties:
        id:
          type: integer
          example: 1
        title:
          type: string
          example: UCL Final 4K Live Broadcast
        image:
          type: string
          example: /uploads/banner1.webp
        url:
          type: string
          example: https://poppycorn.tv/#pricing
    AccountInfo:
      type: object
      properties:
        plan_type:
          type: string
          example: Forever Plan
        expire_date:
          type: string
          example: Never
        max_devices:
          type: integer
          example: 3
        status:
          type: string
          example: Active
        force_sync_at:
          type: integer
          nullable: true
          example: 1727278910
        master_pin:
          type: string
          example: '1234'
    Device:
      type: object
      properties:
        id:
          type: integer
          example: 88
        device_key:
          type: string
          example: POPPY-7842-9912
        device_id:
          type: string
          example: 44a728b9d
        device_name:
          type: string
          example: Sony Bravia 4K TV
        last_seen:
          type: string
          format: date-time
    AccountLookupResponse:
      type: object
      properties:
        account:
          type: object
        planName:
          type: string
          example: Forever (Lifetime Access)
        isActive:
          type: boolean
          example: true
        playlists:
          type: array
          items:
            ? ''
            : '#/components/schemas/Playlist'
        devices:
          type: array
          items:
            ? ''
            : '#/components/schemas/Device'
        maxDevices:
          type: integer
          example: 3
security:
- {}