openapi: 3.1.0
info:
  title: cPanel UAPI
  description: |
    cPanel UAPI is the modern HTTP API exposed by the cPanel web hosting
    control panel. Endpoints follow the pattern
    `/execute/{Module}/{Function}` and accept parameters as query string
    values. UAPI returns JSON responses and authenticates calls via API
    tokens or Basic Authentication. UAPI runs on the cPanel account ports
    (2083 secure, 2082 unsecure) and Webmail ports (2096 secure, 2095
    unsecure).
  version: '1'
  contact:
    name: cPanel
    url: https://api.docs.cpanel.net/cpanel/introduction/
servers:
  - url: https://{hostname}:2083
    description: Secure cPanel account access
    variables:
      hostname:
        default: example.com
        description: The cPanel server hostname.
  - url: https://{hostname}:2096
    description: Secure Webmail session
    variables:
      hostname:
        default: example.com
security:
  - BearerAuth: []
  - BasicAuth: []
tags:
  - name: Email
    description: Email account management (Email module)
  - name: Mysql
    description: MySQL database operations (Mysql module)
  - name: DomainInfo
    description: Domain information (DomainInfo module)
  - name: UAPI
    description: Generic UAPI execute endpoint
paths:
  /execute/{Module}/{Function}:
    parameters:
      - in: path
        name: Module
        required: true
        schema:
          type: string
        description: The UAPI module name (e.g. `Email`, `Mysql`, `DomainInfo`).
      - in: path
        name: Function
        required: true
        schema:
          type: string
        description: The function within the module (e.g. `add_pop`, `list_databases`).
    get:
      tags: [UAPI]
      summary: Execute any UAPI function
      description: |
        Generic UAPI entry point. Pass module-specific parameters as query
        string values.
      operationId: executeUapi
      responses:
        '200':
          description: A UAPI response envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UapiResponse'
  /execute/Email/add_pop:
    get:
      tags: [Email]
      summary: Create an email account
      operationId: emailAddPop
      parameters:
        - in: query
          name: domain
          required: true
          schema:
            type: string
        - in: query
          name: email
          required: true
          schema:
            type: string
        - in: query
          name: password
          required: true
          schema:
            type: string
        - in: query
          name: quota
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Email account creation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UapiResponse'
  /execute/Email/list_pops:
    get:
      tags: [Email]
      summary: List email accounts
      operationId: emailListPops
      responses:
        '200':
          description: List of email accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UapiResponse'
  /execute/Mysql/list_databases:
    get:
      tags: [Mysql]
      summary: List MySQL databases
      operationId: mysqlListDatabases
      responses:
        '200':
          description: List of MySQL databases.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UapiResponse'
  /execute/DomainInfo/list_domains:
    get:
      tags: [DomainInfo]
      summary: List domains on the account
      operationId: domainInfoListDomains
      responses:
        '200':
          description: List of domains.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UapiResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cPanel API Token
      description: |
        Provide a cPanel API token using
        `Authorization: cpanel <username>:<token>` (cPanel's documented
        token header format). Standard `Authorization: Bearer` is also
        accepted by some deployments.
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication with cPanel account credentials.
  schemas:
    UapiResponse:
      type: object
      properties:
        status:
          type: integer
          description: 1 on success, 0 on failure.
        data:
          description: Function-specific response payload.
        errors:
          type: array
          items:
            type: string
        messages:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
        metadata:
          type: object