xui-one-api-docs/openapi.yaml

openapi: 3.0.3
info:
  title: XUI.ONE Admin API
  description: |
    **Comprehensive API documentation for XUI.ONE IPTV Panel Administration**
    
    ### 🎯 Quick Start
    
    This API provides programmatic access to manage your IPTV platform with 180+ endpoints for:
    - 📺 Manage subscriptions (Lines, MAG, Enigma2 devices)
    - 🎬 Control streams, channels, movies, and series  
    - 📊 Monitor connections and activity logs
    - ⚙️ Configure servers and load balancers
    
    ---
    
    ### 🔗 Base URL Pattern
    
    ```
    {protocol}://YOUR_SERVER:{port}/<Access-Code>/?api_key=<API-KEY>&action=ACTION
    ```
    
    **Customize:**
    - `{protocol}` → http or https
    - `YOUR_SERVER` → Your server domain/IP (e.g., 192.168.1.100)
    - `{port}` → Your port (80, 8000, 9000, or custom)
    - `<Access-Code>` → Your access code (e.g., `cSbuFLhp`)
    - `<API-KEY>` → Your API key
    - `ACTION` → API action name (e.g., `get_lines`)
    
    **Common Ports:**
    - `80` - HTTP (default)
    - `8000` - HTTP (alternative)
    - `9000` - HTTPS (recommended)
    - Custom - Any port you configured
    
    ---
    
    ### 🔐 Authentication Setup
    
    **Required:**
    1. XUI.ONE panel installed (v1.5.5+)
    2. Admin API access code created
    3. API key generated from profile
    
    **Quick Setup:**
    1. Panel → Management → Access Control → Access Codes
    2. Create "Admin API" access code
    3. Profile → Generate API Key
    4. Test: `curl "http://your-server.com/<Access-Code>/?api_key=<API-KEY>&action=user_info"`
    
    📖 **[View detailed setup guide →](https://github.com/worldofiptvcom/xui-one-api-docs/blob/main/docs/getting-started.md)**
    
    ---
    
    ### 📝 Request Methods
    
    **GET** - Query data
    ```
    /?api_key=<API-KEY>&action=get_lines
    ```
    
    **POST** - Create/update data  
    ```
    curl -X POST ".../?api_key=<API-KEY>&action=create_line" -d "username=test"
    ```
    
    ---
    
    ### ✅ Response Format
    
    **Success:**
    ```json
    {
      "status": "STATUS_SUCCESS",
      "data": { ... }
    }
    ```
    
    **Error:**
    ```json
    {
      "status": "STATUS_FAILURE",
      "error": "Error description"
    }
    ```
    
    ---
    
    ### 🔒 Security Best Practices
    
    - ✅ Use HTTPS (port 9000) in production
    - ✅ Whitelist IPs in access code settings
    - ✅ Rotate API keys regularly
    - ✅ Never commit keys to version control
    
    ---
    
    ### 📚 Resources
    
    - **GitHub:** [Documentation Repository](https://github.com/worldofiptvcom/xui-one-api-docs)
    - **Community:** [World of IPTV Forums](https://www.worldofiptv.com)
    - **Getting Started:** [Setup Guide](https://github.com/worldofiptvcom/xui-one-api-docs/blob/main/docs/getting-started.md)
    - **XUI.ONE:** [Official Website](https://xui.one)
    
  version: 1.5.13
  contact:
    name: XUI.ONE API Support
    url: https://xui.one
  license:
    name: Proprietary
    url: https://xui.one

servers:
  - url: '{protocol}://{server}:{port}/{accessCode}'
    description: XUI.ONE API Server (Customizable)
    variables:
      protocol:
        default: http
        description: Protocol (http or https)
        enum:
          - http
          - https
      server:
        default: your-server.com
        description: Your XUI.ONE server IP or domain (e.g., 192.168.1.100 or panel.yourdomain.com)
      port:
        default: '80'
        description: API port (80 for HTTP, 9000 for HTTPS, or custom port)
      accessCode:
        default: cSbuFLhp
        description: Your unique access code for API access

security:
  - ApiKeyAuth: []

tags:
  - name: Authentication
    description: Authentication and authorization operations
  - name: GET INFO
    description: Query and retrieve information
  - name: Logs & Events
    description: Activity logs, connections, and monitoring
  - name: Line API
    description: Subscription line management
  - name: User API
    description: User account management
  - name: MAG API
    description: MAG device management
  - name: Enigma API
    description: Enigma2 STB management
  - name: Streams API
    description: Live stream management
  - name: Channel API
    description: Channel management
  - name: Station API
    description: Radio station management
  - name: Movie API
    description: VOD movie management
  - name: Series API
    description: Series management
  - name: Episode API
    description: Episode management
  - name: Servers API
    description: Server and load balancer management
  - name: Settings & System
    description: System settings and administrative functions

paths:
  /:
    get:
      summary: API Base Endpoint
      description: |
        Base endpoint for all API requests. All actions are performed by adding the `action` parameter.
        
        **Usage Pattern:**
        ```
        /?api_key=<API-KEY>&action=ACTION_NAME&param1=value1
        ```
        
        **Example:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
        ```
      operationId: apiBase
      tags:
        - Authentication
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - $ref: '#/components/parameters/Action'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'

  /?action=user_info:
    get:
      summary: Get Current User Info
      description: |
        Retrieves information about the currently authenticated admin user.
        
        **Purpose:** Verify API authentication and check admin privileges.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=user_info"
        ```
        
        **Example Response:**
        ```json
        {
          "status": "STATUS_SUCCESS",
          "data": {
            "id": "1",
            "username": "admin",
            "member_group_id": "1",
            "email": "admin@example.com",
            "date_registered": "1609459200",
            "last_login": "1734048000",
            "status": "1"
          }
        }
        ```
        
        ---
        
        **Use Cases:**
        - ✅ Test API authentication
        - ✅ Verify admin access
        - ✅ Get current user details
        - ✅ Check account status
      operationId: getUserInfo
      tags:
        - Authentication
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          description: Action to perform
          schema:
            type: string
            enum: [user_info]
          example: user_info
      responses:
        '200':
          description: Current user information retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/UserInfo'
              example:
                status: "STATUS_SUCCESS"
                data:
                  id: "1"
                  username: "admin"
                  member_group_id: "1"
                  email: "admin@example.com"
                  date_registered: "1609459200"
                  last_login: "1734048000"
                  status: "1"
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_lines:
    get:
      summary: Get All Subscription Lines
      description: |
        Retrieves a list of all subscription lines in your XUI.ONE panel.
        
        **Purpose:** View and manage all active and inactive subscription lines.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_lines"
        ```
        
        **Use Cases:**
        - ✅ List all subscriptions
        - ✅ Monitor active lines
        - ✅ Export subscription data
        - ✅ Check expiration dates
        - ✅ View connection limits
      operationId: getLines
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_lines]
      responses:
        '200':
          description: List of all subscription lines
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/Line'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_users:
    get:
      summary: Get All Users
      description: |
        Retrieves a list of all user accounts in your XUI.ONE panel.
        
        **Purpose:** View all admin, reseller, and user accounts.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_users"
        ```
        
        **Use Cases:**
        - ✅ List all users
        - ✅ View user roles and permissions
        - ✅ Audit user accounts
        - ✅ Export user data
      operationId: getUsers
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_users]
      responses:
        '200':
          description: List of all users
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_streams:
    get:
      summary: Get All Live Streams
      description: |
        Retrieves a list of all live TV streams configured in your panel.
        
        **Purpose:** View all live streaming channels and their configurations.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_streams"
        ```
        
        **Use Cases:**
        - ✅ List all live streams
        - ✅ Check stream status
        - ✅ View stream sources
        - ✅ Monitor stream health
        - ✅ Export stream configurations
      operationId: getStreams
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_streams]
      responses:
        '200':
          description: List of all live streams
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_channels:
    get:
      summary: Get All Channels
      description: |
        Retrieves a list of all channels configured in your panel.
        
        **Purpose:** View all channel configurations and metadata.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_channels"
        ```
        
        **Use Cases:**
        - ✅ List all channels
        - ✅ View channel categories
        - ✅ Check EPG data
        - ✅ Export channel list
      operationId: getChannels
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_channels]
      responses:
        '200':
          description: List of all channels
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_movies:
    get:
      summary: Get All Movies
      description: |
        Retrieves a list of all VOD movies in your panel.
        
        **Purpose:** View all movie content and metadata.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_movies"
        ```
        
        **Use Cases:**
        - ✅ List all movies
        - ✅ View movie metadata (title, year, rating)
        - ✅ Check movie availability
        - ✅ Export movie catalog
        - ✅ Monitor storage usage
      operationId: getMovies
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_movies]
      responses:
        '200':
          description: List of all movies
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_series_list:
    get:
      summary: Get All Series
      description: |
        Retrieves a list of all TV series in your panel.
        
        **Purpose:** View all series content and metadata.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_series_list"
        ```
        
        **Use Cases:**
        - ✅ List all TV series
        - ✅ View series metadata
        - ✅ Check episode counts
        - ✅ Export series catalog
      operationId: getSeriesList
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_series_list]
      responses:
        '200':
          description: List of all series
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_episodes:
    get:
      summary: Get All Episodes
      description: |
        Retrieves a list of all episodes across all series.
        
        **Purpose:** View all episode content and metadata.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_episodes"
        ```
        
        **Note:** To get episodes for a specific series, use the series_id parameter.
        
        **Use Cases:**
        - ✅ List all episodes
        - ✅ View episode metadata
        - ✅ Check episode availability
        - ✅ Filter by series
      operationId: getEpisodes
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_episodes]
        - name: series_id
          in: query
          required: false
          description: Filter episodes by series ID
          schema:
            type: integer
          example: 123
      responses:
        '200':
          description: List of episodes
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_mags:
    get:
      summary: Get All MAG Devices
      description: |
        Retrieves a list of all MAG devices configured in your panel.
        
        **Purpose:** View all MAG set-top box subscriptions.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_mags"
        ```
        
        **Use Cases:**
        - ✅ List all MAG devices
        - ✅ View MAC addresses
        - ✅ Check device status
        - ✅ Monitor connections
      operationId: getMags
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_mags]
      responses:
        '200':
          description: List of all MAG devices
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_enigmas:
    get:
      summary: Get All Enigma2 Devices
      description: |
        Retrieves a list of all Enigma2 devices configured in your panel.
        
        **Purpose:** View all Enigma2 STB subscriptions.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_enigmas"
        ```
        
        **Use Cases:**
        - ✅ List all Enigma2 devices
        - ✅ View device status
        - ✅ Check expiration dates
        - ✅ Monitor connections
      operationId: getEnigmas
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_enigmas]
      responses:
        '200':
          description: List of all Enigma2 devices
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_stations:
    get:
      summary: Get All Radio Stations
      description: |
        Retrieves a list of all radio stations configured in your panel.
        
        **Purpose:** View all radio streaming channels.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_stations"
        ```
        
        **Use Cases:**
        - ✅ List all radio stations
        - ✅ View station metadata
        - ✅ Check stream sources
        - ✅ Export station list
      operationId: getStations
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_stations]
      responses:
        '200':
          description: List of all radio stations
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /?action=get_packages:
    get:
      summary: Get All Packages
      description: |
        Retrieves a list of all subscription packages (bouquets) in your panel.
        
        **Purpose:** View all available subscription packages and their configurations.
        
        ---
        
        **Example Request:**
        ```bash
        curl "http://your-server.com/cSbuFLhp/?api_key=8D3135D30437F86EAE2FA4A2A8345000&action=get_packages"
        ```
        
        **Use Cases:**
        - ✅ List all packages
        - ✅ View package pricing
        - ✅ Check channel assignments
        - ✅ Export package configurations
      operationId: getPackages
      tags:
        - GET INFO
      parameters:
        - $ref: '#/components/parameters/ApiKey'
        - name: action
          in: query
          required: true
          schema:
            type: string
            enum: [get_packages]
      responses:
        '200':
          description: List of all packages
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: api_key
      description: |
        API key for authentication. Generate from your admin profile.
        
        **Example:** `8D3135D30437F86EAE2FA4A2A8345000`

  parameters:
    ApiKey:
      name: api_key
      in: query
      required: true
      description: Your API key for authentication
      schema:
        type: string
        example: "8D3135D30437F86EAE2FA4A2A8345000"
    
    Action:
      name: action
      in: query
      required: true
      description: The API action to perform
      schema:
        type: string
      example: user_info

  schemas:
    SuccessResponse:
      type: object
      required:
        - status
        - data
      properties:
        status:
          type: string
          enum: [STATUS_SUCCESS]
          description: Response status indicator
        data:
          type: object
          description: Response data (structure varies by endpoint)
      example:
        status: "STATUS_SUCCESS"
        data: {}

    ErrorResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum: [STATUS_FAILURE]
          description: Error status indicator
        error:
          type: string
          description: Error message describing what went wrong
      example:
        status: "STATUS_FAILURE"
        error: "Invalid API key"

    UserInfo:
      type: object
      description: User information object
      properties:
        id:
          type: string
          description: User ID
          example: "1"
        username:
          type: string
          description: Username
          example: "admin"
        member_group_id:
          type: string
          description: Member group ID (1 = Administrator)
          example: "1"
        email:
          type: string
          format: email
          description: User email address
          example: "admin@example.com"
        date_registered:
          type: string
          description: Unix timestamp of registration date
          example: "1609459200"
        last_login:
          type: string
          description: Unix timestamp of last login
          example: "1734048000"
        status:
          type: string
          description: User status (1 = Active, 0 = Inactive)
          enum: ["0", "1"]
          example: "1"

    Line:
      type: object
      description: Subscription line object
      properties:
        id:
          type: string
          description: Line ID
          example: "123"
        username:
          type: string
          description: Line username
          example: "testuser"
        password:
          type: string
          description: Line password
          example: "testpass123"
        exp_date:
          type: string
          description: Expiration date (Unix timestamp)
          example: "1735689600"
        max_connections:
          type: string
          description: Maximum concurrent connections allowed
          example: "1"
        is_trial:
          type: string
          description: Trial status (0 = No, 1 = Yes)
          enum: ["0", "1"]
          example: "0"
        enabled:
          type: string
          description: Line status (0 = Disabled, 1 = Enabled)
          enum: ["0", "1"]
          example: "1"
        is_restreamer:
          type: string
          description: Reseller status (0 = No, 1 = Yes)
          enum: ["0", "1"]
          example: "0"
        bouquet:
          type: string
          description: Assigned bouquet/package IDs (JSON array)
          example: "[1,2,3]"
        notes:
          type: string
          description: Admin notes
          example: "Premium customer"
        created_at:
          type: string
          description: Creation date (Unix timestamp)
          example: "1609459200"

  responses:
    Unauthorized:
      description: Authentication failed - Invalid API key or access code
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: "STATUS_FAILURE"
            error: "Invalid API key"

    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: "STATUS_FAILURE"
            error: "Internal server error"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status: "STATUS_FAILURE"
            error: "Resource not found"