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'

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"

  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"