# Auto-generated from internal/apidocs/api_endpoints.json by scripts/generate_openapi.py.
# To update: regenerate rather than hand-editing this file directly.
openapi: 3.0.3
info:
  title: OpenAdmin API
  version: 1.0.0
  description: |-
    REST API for OpenAdmin, the administrator-level control panel for OpenPanel server management. Every feature available in OpenAdmin's web UI can also be accessed programmatically.

    All endpoints require a Bearer token obtained from `POST /api/` (username/password login), except the login call itself and the `GET /api/` health check. Tokens expire after 15 minutes. Beyond authentication, most endpoints also require the administrator role -- see each operation's **Access** note for its exact requirement (some allow a reseller who owns the target account, and a handful of the most dangerous server-control actions require the Super Admin role specifically).

    The whole API is also gated behind [PANEL] api=on and a configured license key -- when either is off, every /api/* route (including this one) responds as if it doesn't exist.

    Success responses are JSON objects (`200`) unless noted otherwise. Error responses always include an `error` field and use standard HTTP status codes (400, 401, 403, 404, 409, 500).
  contact:
    name: OpenPanel
    url: https://openpanel.com
  license:
    name: OpenPanel EULA
    url: https://openpanel.com/LICENSE
servers:
- url: https://panel.example.com:2087
  description: Your OpenAdmin installation (default port 2087)
tags:
- name: Authentication
- name: Users
- name: Domains
- name: Domain Files
- name: Domain Stats
- name: Plans
- name: Containers
- name: DNS
- name: Email
- name: Security
- name: Two-Factor Authentication
- name: Passkeys
- name: Services
- name: Podman
- name: Backups
- name: System
- name: Notifications
- name: Cron Jobs
- name: SSH
- name: Server
- name: Processes
- name: Power & Root Access
- name: Migration
- name: Settings - Administrators
- name: Settings - Resellers
- name: Settings - General
- name: Settings - Defaults
- name: Settings - Plan Features
- name: Settings - Locales
- name: Settings - Modules
- name: Settings - Custom Code
- name: Settings - PHP
- name: Settings - Caddy
- name: Settings - Updates
- name: Settings - Notifications
- name: License
- name: Support
- name: Import & Transfers
paths:
  /api/:
    get:
      summary: Health check - confirms the API is reachable.
      description: '**Access:** No authentication (this is the login/health-check endpoint itself).'
      operationId: get_root
      tags:
      - Authentication
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: API is working!
                example:
                  message: API is working!
        default:
          $ref: '#/components/responses/Error'
      security: []
    post:
      summary: Log in with username/password and obtain a JWT Bearer token, valid for 15 minutes.
      description: '**Access:** No authentication (this is the login/health-check endpoint itself).'
      operationId: post_root
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: admin
                password:
                  type: string
                  example: secret
              example:
                username: admin
                password: secret
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                example:
                  access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        default:
          $ref: '#/components/responses/Error'
      security: []
  /api/whoami:
    get:
      summary: Returns the username embedded in the caller's JWT access token. Reads the identity directly
        from the token claims rather than the database, so it still answers even if the user row backing
        the token has since been deleted.
      description: '**Access:** Any authenticated user.'
      operationId: whoami
      tags:
      - Authentication
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  logged_in_as:
                    type: string
                    example: bob
                example:
                  logged_in_as: bob
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/login:
    post:
      summary: Log in with username/password and obtain a one-time SSO token, redeemable once at GET /login/sso/{token}
        (expires after 2 minutes) for a real browser session cookie and a redirect to /dashboard. For
        integrations (e.g. a WHMCS "Login to Panel" button) that need to open an actual admin session
        instead of just an API token - avoids posting credentials to the CSRF-protected /login form, which
        an auto-submitting cross-origin form can't get past.
      description: '**Access:** No authentication (this is the login/health-check endpoint itself).'
      operationId: login
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: admin
                password:
                  type: string
                  example: secret
              example:
                username: admin
                password: secret
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: 5f2c...
                  login_path:
                    type: string
                    example: /login/sso/5f2c...
                  expires_in:
                    type: integer
                    example: 120
                example:
                  token: 5f2c...
                  login_path: /login/sso/5f2c...
                  expires_in: 120
        default:
          $ref: '#/components/responses/Error'
      security: []
  /api/users:
    get:
      summary: Lists user accounts. The underlying listing query depends on a page-scoped 'current user'
        concept that a bearer-token request never populates, so this always returns an empty users array
        regardless of caller role.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: get_users
      tags:
      - Users
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: string
                    example: []
                example:
                  users: []
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Creates a new user account by invoking 'opencli user-add' with the given username, password,
        email and plan. Rejects usernames listed in the forbidden-usernames file (case-insensitive) and
        requires email, username, password and plan_name.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: post_users
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: a@b.com
                username:
                  type: string
                  example: newuser
                password:
                  type: string
                  example: pw
                plan_name:
                  type: string
                  example: default
                webserver:
                  type: string
                  example: nginx
                sql_type:
                  type: string
                  example: mysql
              example:
                email: a@b.com
                username: newuser
                password: pw
                plan_name: default
                webserver: nginx
                sql_type: mysql
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  response:
                    type: object
                    properties:
                      message:
                        type: string
                        example: User newuser created successfully.
                    example:
                      message: User newuser created successfully.
                example:
                  success: true
                  response:
                    message: User newuser created successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}:
    get:
      summary: 'Returns detailed account information for a single user: profile fields, plan limits, owned
        domains, sites, and current disk/inode usage (read from the quota report, matched by exact username).'
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: get_users_username
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      user:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 12
                          username:
                            type: string
                            example: bob
                          email:
                            type: string
                            example: bob@example.com
                          owner:
                            type: string
                            example: admin
                          twofa_enabled:
                            type: integer
                            example: 0
                          registered_date:
                            type: string
                            example: '2025-01-10 12:00:00'
                          server:
                            type: string
                            example: server1
                        example:
                          id: 12
                          username: bob
                          email: bob@example.com
                          owner: admin
                          twofa_enabled: 0
                          registered_date: '2025-01-10 12:00:00'
                          server: server1
                      plan:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 1
                          name:
                            type: string
                            example: starter
                          description:
                            type: string
                            example: Starter plan
                          domains_limit:
                            type: integer
                            example: 5
                          websites_limit:
                            type: integer
                            example: 5
                          email_limit:
                            type: integer
                            example: 10
                          ftp_limit:
                            type: integer
                            example: 5
                          disk_limit:
                            type: string
                            example: '5000'
                          inodes_limit:
                            type: string
                            example: '100000'
                          db_limit:
                            type: integer
                            example: 5
                          cpu:
                            type: string
                            example: '1'
                          ram:
                            type: string
                            example: '1024'
                          bandwidth:
                            type: string
                            example: '1000'
                          feature_set:
                            type: string
                            example: default
                        example:
                          id: 1
                          name: starter
                          description: Starter plan
                          domains_limit: 5
                          websites_limit: 5
                          email_limit: 10
                          ftp_limit: 5
                          disk_limit: '5000'
                          inodes_limit: '100000'
                          db_limit: 5
                          cpu: '1'
                          ram: '1024'
                          bandwidth: '1000'
                          feature_set: default
                      domains:
                        type: array
                        items:
                          type: object
                          properties:
                            domain_id:
                              type: integer
                              example: 3
                            docroot:
                              type: string
                              example: /var/www/html/example.com
                            domain_url:
                              type: string
                              example: example.com
                            php_version:
                              type: string
                              example: '8.2'
                          example:
                            domain_id: 3
                            docroot: /var/www/html/example.com
                            domain_url: example.com
                            php_version: '8.2'
                        example:
                        - domain_id: 3
                          docroot: /var/www/html/example.com
                          domain_url: example.com
                          php_version: '8.2'
                      sites:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 7
                            site_name:
                              type: string
                              example: example.com
                            domain_id:
                              type: integer
                              example: 3
                            admin_email:
                              type: string
                              example: bob@example.com
                            version:
                              type: string
                              example: '6.4'
                            created_date:
                              type: string
                              example: '2025-01-10 12:00:00'
                            type:
                              type: string
                              example: wordpress
                            ports:
                              type: string
                              example: '8080'
                            path:
                              type: string
                              example: /var/www/html/example.com
                            container:
                              type: string
                              example: bob_example_com
                          example:
                            id: 7
                            site_name: example.com
                            domain_id: 3
                            admin_email: bob@example.com
                            version: '6.4'
                            created_date: '2025-01-10 12:00:00'
                            type: wordpress
                            ports: '8080'
                            path: /var/www/html/example.com
                            container: bob_example_com
                        example:
                        - id: 7
                          site_name: example.com
                          domain_id: 3
                          admin_email: bob@example.com
                          version: '6.4'
                          created_date: '2025-01-10 12:00:00'
                          type: wordpress
                          ports: '8080'
                          path: /var/www/html/example.com
                          container: bob_example_com
                      disk_usage:
                        type: object
                        properties:
                          disk_used:
                            type: string
                            example: '120'
                          disk_soft:
                            type: string
                            example: '5000'
                          disk_hard:
                            type: string
                            example: '5500'
                          inodes_used:
                            type: string
                            example: '3000'
                          inodes_soft:
                            type: string
                            example: '100000'
                          inodes_hard:
                            type: string
                            example: '110000'
                          home_path:
                            type: string
                            example: /home/bob
                        example:
                          disk_used: '120'
                          disk_soft: '5000'
                          disk_hard: '5500'
                          inodes_used: '3000'
                          inodes_soft: '100000'
                          inodes_hard: '110000'
                          home_path: /home/bob
                    example:
                      user:
                        id: 12
                        username: bob
                        email: bob@example.com
                        owner: admin
                        twofa_enabled: 0
                        registered_date: '2025-01-10 12:00:00'
                        server: server1
                      plan:
                        id: 1
                        name: starter
                        description: Starter plan
                        domains_limit: 5
                        websites_limit: 5
                        email_limit: 10
                        ftp_limit: 5
                        disk_limit: '5000'
                        inodes_limit: '100000'
                        db_limit: 5
                        cpu: '1'
                        ram: '1024'
                        bandwidth: '1000'
                        feature_set: default
                      domains:
                      - domain_id: 3
                        docroot: /var/www/html/example.com
                        domain_url: example.com
                        php_version: '8.2'
                      sites:
                      - id: 7
                        site_name: example.com
                        domain_id: 3
                        admin_email: bob@example.com
                        version: '6.4'
                        created_date: '2025-01-10 12:00:00'
                        type: wordpress
                        ports: '8080'
                        path: /var/www/html/example.com
                        container: bob_example_com
                      disk_usage:
                        disk_used: '120'
                        disk_soft: '5000'
                        disk_hard: '5500'
                        inodes_used: '3000'
                        inodes_soft: '100000'
                        inodes_hard: '110000'
                        home_path: /home/bob
                example:
                  user:
                    user:
                      id: 12
                      username: bob
                      email: bob@example.com
                      owner: admin
                      twofa_enabled: 0
                      registered_date: '2025-01-10 12:00:00'
                      server: server1
                    plan:
                      id: 1
                      name: starter
                      description: Starter plan
                      domains_limit: 5
                      websites_limit: 5
                      email_limit: 10
                      ftp_limit: 5
                      disk_limit: '5000'
                      inodes_limit: '100000'
                      db_limit: 5
                      cpu: '1'
                      ram: '1024'
                      bandwidth: '1000'
                      feature_set: default
                    domains:
                    - domain_id: 3
                      docroot: /var/www/html/example.com
                      domain_url: example.com
                      php_version: '8.2'
                    sites:
                    - id: 7
                      site_name: example.com
                      domain_id: 3
                      admin_email: bob@example.com
                      version: '6.4'
                      created_date: '2025-01-10 12:00:00'
                      type: wordpress
                      ports: '8080'
                      path: /var/www/html/example.com
                      container: bob_example_com
                    disk_usage:
                      disk_used: '120'
                      disk_soft: '5000'
                      disk_hard: '5500'
                      inodes_used: '3000'
                      inodes_soft: '100000'
                      inodes_hard: '110000'
                      home_path: /home/bob
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Creates a new user account. Behaves identically to POST /api/users -- the {username} path
        segment is ignored, only the JSON body's own 'username' field is used.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: post_users_username
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: a@b.com
                username:
                  type: string
                  example: bodyuser
                password:
                  type: string
                  example: pw
                plan_name:
                  type: string
                  example: default
              example:
                email: a@b.com
                username: bodyuser
                password: pw
                plan_name: default
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  response:
                    type: object
                    properties:
                      message:
                        type: string
                        example: User bodyuser created successfully.
                    example:
                      message: User bodyuser created successfully.
                example:
                  success: true
                  response:
                    message: User bodyuser created successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    put:
      summary: Changes a user's plan by invoking 'opencli user-change_plan' with the new plan name.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: put_users_username
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                plan_name:
                  type: string
                  example: pro
              example:
                plan_name: pro
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  response:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Plan for user bob changed to pro.
                    example:
                      message: Plan for user bob changed to pro.
                example:
                  success: true
                  response:
                    message: Plan for user bob changed to pro.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    patch:
      summary: Updates a user's password (via 'opencli user-password') or suspends/unsuspends the account
        (via 'opencli user-suspend'/'user-unsuspend'), depending on which of 'password' or 'action' is
        present in the body.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: patch_users_username
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: suspend
              example:
                action: suspend
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  response:
                    type: object
                    properties:
                      message:
                        type: string
                        example: User bob suspended successfully.
                    example:
                      message: User bob suspended successfully.
                example:
                  success: true
                  response:
                    message: User bob suspended successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    delete:
      summary: Deletes a user account by invoking 'opencli user-delete <username> -y'. Requires a JSON
        Content-Type even though no body fields are read.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: delete_users_username
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  response:
                    type: object
                    properties:
                      message:
                        type: string
                        example: User bob deleted successfully.
                    example:
                      message: User bob deleted successfully.
                example:
                  success: true
                  response:
                    message: User bob deleted successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/autologin:
    post:
      summary: Generates a one-time admin_token file and returns a signed autologin link that the user-panel's
        /login_autologin route uses to sign the caller in as this user. Exists as a dedicated route rather
        than an HTTP-method dispatch on /api/users/{username} because CONNECT-style addressing doesn't
        fit an ordinary path-based resource.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_autologin
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    type: string
                    example: http://203.0.113.10:2083/login_autologin?username=bob&admin_token=aBcD1234...
                example:
                  link: http://203.0.113.10:2083/login_autologin?username=bob&admin_token=aBcD1234...
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/permissions/reset:
    post:
      summary: Deletes the user's per-account permission overrides, so their permissions follow their
        plan's feature-set defaults again.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_permissions_reset
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                example:
                  success: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/export/status:
    get:
      summary: Whether a full-account backup (opencli user-backup) is running for the user, plus the existing
        backup archives (name, size, created time).
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_export_status
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/export/create:
    post:
      summary: Starts a new full-account backup in the background, the same one the user's own Backup
        Wizard makes. 409 if one is already running.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_export_create
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/export/download/{filename}:
    get:
      summary: Downloads a full-account backup archive.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_export_download_filename
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: filename
        in: path
        required: true
        schema:
          type: string
        description: May contain '/' - this segment matches the rest of the path.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/export/delete:
    post:
      summary: Deletes a full-account backup archive.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_export_delete
      tags:
      - Users
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  example: alice_backup_2026-08-20_23-31-03.tar.gz
              example:
                filename: alice_backup_2026-08-20_23-31-03.tar.gz
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/domains:
    get:
      summary: Lists all domains registered on the server.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: domains
      tags:
      - Domains
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  domains:
                    type: array
                    items:
                      type: object
                      properties:
                        domain_id:
                          type: integer
                          example: 3
                        domain_url:
                          type: string
                          example: example.com
                        user_id:
                          type: integer
                          example: 12
                        docroot:
                          type: string
                          example: /var/www/html/example.com
                        php_version:
                          type: string
                          example: '8.2'
                      example:
                        domain_id: 3
                        domain_url: example.com
                        user_id: 12
                        docroot: /var/www/html/example.com
                        php_version: '8.2'
                    example:
                    - domain_id: 3
                      domain_url: example.com
                      user_id: 12
                      docroot: /var/www/html/example.com
                      php_version: '8.2'
                example:
                  domains:
                  - domain_id: 3
                    domain_url: example.com
                    user_id: 12
                    docroot: /var/www/html/example.com
                    php_version: '8.2'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/domains/new:
    post:
      summary: Adds a new domain for a user by invoking 'opencli domains-add <domain> <username> --docroot
        <docroot>'. docroot defaults to /var/www/html/<domain> if omitted, and must always fall under
        /var/www/html/.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: domains_new
      tags:
      - Domains
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: bob
                domain:
                  type: string
                  example: example.com
                docroot:
                  type: string
                  example: /var/www/html/example.com
              example:
                username: bob
                domain: example.com
                docroot: /var/www/html/example.com
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  stdout:
                    type: string
                    example: |
                      Domain example.com added successfully for user bob.
                  stderr:
                    type: string
                    example: ''
                  returncode:
                    type: integer
                    example: 0
                example:
                  stdout: |
                    Domain example.com added successfully for user bob.
                  stderr: ''
                  returncode: 0
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/domains/{seg2}/{seg3}:
    get:
      summary: 'Manual dispatcher for two-segment /api/domains/* routes that would otherwise overlap in
        Go''s ServeMux. Based on the seg2/seg3 values it delegates to: GET docroot for a domain (seg2=''docroot''),
        the DNS zone file (seg3=''dns''), the Caddy config snippet (seg3=''caddy''), SSL status/info (seg3=''ssl''),
        or the JSON access log (seg3=''log''); any other combination returns 404. Each sub-route has its
        own response shape -- see the docroot example below for the ''docroot'' case.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_domains_seg2_seg3
      tags:
      - Domains
      parameters:
      - name: seg2
        in: path
        required: true
        schema:
          type: string
      - name: seg3
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  stdout:
                    type: string
                    example: |
                      /var/www/html/example.com
                  stderr:
                    type: string
                    example: ''
                  returncode:
                    type: integer
                    example: 0
                example:
                  stdout: |
                    /var/www/html/example.com
                  stderr: ''
                  returncode: 0
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Manual dispatcher for two-segment /api/domains/* POST routes. Based on the seg2/seg3 values
        it delegates to: setting a domain''s docroot (seg2=''docroot''), saving the DNS zone file (seg3=''dns''),
        saving the Caddy config (seg3=''caddy''), managing SSL (seg3=''ssl''), or -- as the default/fallback
        case -- a domain lifecycle action (suspend/unsuspend/delete) where seg2 is the action and seg3
        is the domain, invoking ''opencli domains-<action> <domain>''.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_domains_seg2_seg3
      tags:
      - Domains
      parameters:
      - name: seg2
        in: path
        required: true
        schema:
          type: string
      - name: seg3
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                docroot:
                  type: string
                  example: /var/www/html/example.com
              example:
                docroot: /var/www/html/example.com
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  stdout:
                    type: string
                    example: |
                      Domain example.com suspended successfully.
                  stderr:
                    type: string
                    example: ''
                  returncode:
                    type: integer
                    example: 0
                example:
                  stdout: |
                    Domain example.com suspended successfully.
                  stderr: ''
                  returncode: 0
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/domains/{domain_name}/vhost/{username}:
    get:
      summary: Returns the raw webserver vhost config file content for a domain, read from the user's
        docker-data webserver volume (404 if the user has no resolvable context or the file doesn't exist).
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: get_domains_domain_name_vhost_username
      tags:
      - Domain Files
      parameters:
      - name: domain_name
        in: path
        required: true
        schema:
          type: string
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: string
                    example: example.com
                  content:
                    type: string
                    example: |
                      server {
                          listen 80;
                          server_name example.com;
                      }
                example:
                  domain: example.com
                  content: |
                    server {
                        listen 80;
                        server_name example.com;
                    }
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Replaces the raw webserver vhost config file for a domain and restarts the user's webserver
        container to apply it (a failed restart still counts as a successful save).
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: post_domains_domain_name_vhost_username
      tags:
      - Domain Files
      parameters:
      - name: domain_name
        in: path
        required: true
        schema:
          type: string
      - name: username
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                  example: |
                    server {
                        listen 80;
                        server_name example.com;
                    }
              example:
                content: |
                  server {
                      listen 80;
                      server_name example.com;
                  }
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: VirtualHosts file for example.com saved successfully and nginx restarted.
                example:
                  success: true
                  message: VirtualHosts file for example.com saved successfully and nginx restarted.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/domains/file-templates:
    get:
      summary: Returns the current contents of the default nginx/openresty/apache/varnish/caddy domain
        config templates and the default/suspended-user/suspended-website landing pages used for new domains.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_domains_file_templates
      tags:
      - Domain Files
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  default_page:
                    type: string
                    example: <html>...</html>
                  suspended_user:
                    type: string
                    example: <html>...</html>
                  suspended_website:
                    type: string
                    example: <html>...</html>
                  docker_nginx_domain:
                    type: string
                    example: server { ... }
                  docker_openresty_domain:
                    type: string
                    example: server { ... }
                  docker_apache_domain:
                    type: string
                    example: <VirtualHost *:80> ... </VirtualHost>
                  docker_varnish:
                    type: string
                    example: vcl 4.1; ...
                  docker_caddy:
                    type: string
                    example: '{$DOMAIN} { ... }'
                example:
                  default_page: <html>...</html>
                  suspended_user: <html>...</html>
                  suspended_website: <html>...</html>
                  docker_nginx_domain: server { ... }
                  docker_openresty_domain: server { ... }
                  docker_apache_domain: <VirtualHost *:80> ... </VirtualHost>
                  docker_varnish: vcl 4.1; ...
                  docker_caddy: '{$DOMAIN} { ... }'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates one or more of the domain config templates. Each present, non-null key must be
        a string; any subset of the known template keys may be supplied and only those are written to
        disk.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_domains_file_templates
      tags:
      - Domain Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                docker_nginx_domain:
                  type: string
                  example: server { listen 80; ... }
              example:
                docker_nginx_domain: server { listen 80; ... }
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Templates updated successfully!
                example:
                  success: true
                  message: Templates updated successfully!
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/domains/vhost-templates:
    get:
      summary: 'VirtualHost configuration templates used for new domains: docker_nginx_domain, docker_openresty_domain,
        docker_apache_domain, docker_varnish, docker_caddy.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_domains_vhost_templates
      tags:
      - Domain Files
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates VirtualHost templates for new domains, send only the keys to change.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_domains_vhost_templates
      tags:
      - Domain Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                docker_nginx_domain:
                  type: string
                  example: server { ... }
              example:
                docker_nginx_domain: server { ... }
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/domains/{domain_name}/stats/{username}:
    get:
      summary: Returns the pre-generated GoAccess HTML stats report for a domain, read from the user's
        stats directory. Data is regenerated every 24 hours; a 404 is returned if no report has been generated
        yet.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: domains_domain_name_stats_username
      tags:
      - Domain Stats
      parameters:
      - name: domain_name
        in: path
        required: true
        schema:
          type: string
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: string
                    example: example.com
                  html:
                    type: string
                    example: <html>...GoAccess report...</html>
                example:
                  domain: example.com
                  html: <html>...GoAccess report...</html>
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/plans:
    get:
      summary: Lists hosting plans. Admins see every plan; a reseller only sees the plans in their allowed_plans,
        same as the Plans page.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: get_plans
      tags:
      - Plans
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  plans:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: starter
                        description:
                          type: string
                          example: Starter plan
                        domains_limit:
                          type: integer
                          example: 5
                        websites_limit:
                          type: integer
                          example: 5
                        email_limit:
                          type: integer
                          example: 10
                        disk_limit:
                          type: string
                          example: '5000'
                        inodes_limit:
                          type: string
                          example: '100000'
                        db_limit:
                          type: integer
                          example: 5
                        cpu:
                          type: string
                          example: '1'
                        ram:
                          type: string
                          example: '1024'
                        bandwidth:
                          type: string
                          example: '1000'
                        feature_set:
                          type: string
                          example: default
                      example:
                        id: 1
                        name: starter
                        description: Starter plan
                        domains_limit: 5
                        websites_limit: 5
                        email_limit: 10
                        disk_limit: '5000'
                        inodes_limit: '100000'
                        db_limit: 5
                        cpu: '1'
                        ram: '1024'
                        bandwidth: '1000'
                        feature_set: default
                    example:
                    - id: 1
                      name: starter
                      description: Starter plan
                      domains_limit: 5
                      websites_limit: 5
                      email_limit: 10
                      disk_limit: '5000'
                      inodes_limit: '100000'
                      db_limit: 5
                      cpu: '1'
                      ram: '1024'
                      bandwidth: '1000'
                      feature_set: default
                example:
                  plans:
                  - id: 1
                    name: starter
                    description: Starter plan
                    domains_limit: 5
                    websites_limit: 5
                    email_limit: 10
                    disk_limit: '5000'
                    inodes_limit: '100000'
                    db_limit: 5
                    cpu: '1'
                    ram: '1024'
                    bandwidth: '1000'
                    feature_set: default
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Creates a new hosting plan by invoking 'opencli plan-create' with the given fields (all
        default to 0/'1'/'default' when omitted). If the acting token belongs to a reseller, the plan
        is created scoped to that reseller.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: post_plans
      tags:
      - Plans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: pro
                description:
                  type: string
                  example: Pro plan
                email_limit:
                  type: integer
                  example: 50
                max_email_quota:
                  type: integer
                  example: 1000
                max_hourly_email:
                  type: integer
                  example: 100
                ftp_limit:
                  type: integer
                  example: 10
                domains_limit:
                  type: integer
                  example: 20
                websites_limit:
                  type: integer
                  example: 20
                disk_limit:
                  type: integer
                  example: 20000
                inodes_limit:
                  type: integer
                  example: 500000
                db_limit:
                  type: integer
                  example: 20
                cpu:
                  type: integer
                  example: 2
                ram:
                  type: integer
                  example: 2048
                bandwidth:
                  type: integer
                  example: 5000
                feature_set:
                  type: string
                  example: default
              example:
                name: pro
                description: Pro plan
                email_limit: 50
                max_email_quota: 1000
                max_hourly_email: 100
                ftp_limit: 10
                domains_limit: 20
                websites_limit: 20
                disk_limit: 20000
                inodes_limit: 500000
                db_limit: 20
                cpu: 2
                ram: 2048
                bandwidth: 5000
                feature_set: default
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Plan created successfully.
                example:
                  success: true
                  message: Plan created successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/plans/resellers:
    get:
      summary: Lists reseller plans (packages) with their account and disk limits, the user plans resellers
        on them may assign, and the resellers currently on each plan.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_plans_resellers
      tags:
      - Plans
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Creates, updates or deletes a reseller plan (action create/update/delete); updating a plan
        reapplies its limits to the resellers on it. allowed_plans accepts [1,2], ["1","2"] or "1,2".
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_plans_resellers
      tags:
      - Plans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: create
                name:
                  type: string
                  example: reseller_basic
                description:
                  type: string
                  example: 10 accounts, 50 GB
                max_accounts:
                  type: integer
                  example: 10
                max_disk_blocks:
                  type: integer
                  example: 51200000
                allowed_plans:
                  type: array
                  items:
                    type: integer
                    example: 1
                  example:
                  - 1
                  - 2
              example:
                action: create
                name: reseller_basic
                description: 10 accounts, 50 GB
                max_accounts: 10
                max_disk_blocks: 51200000
                allowed_plans:
                - 1
                - 2
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: OK
                  plan:
                    type: object
                    properties:
                      name:
                        type: string
                        example: reseller_basic
                      description:
                        type: string
                        example: 10 accounts, 50 GB
                      max_accounts:
                        type: integer
                        example: 10
                      max_disk_blocks:
                        type: integer
                        example: 51200000
                      allowed_plans:
                        type: array
                        items:
                          type: integer
                          example: 1
                        example:
                        - 1
                        - 2
                    example:
                      name: reseller_basic
                      description: 10 accounts, 50 GB
                      max_accounts: 10
                      max_disk_blocks: 51200000
                      allowed_plans:
                      - 1
                      - 2
                example:
                  success: true
                  message: OK
                  plan:
                    name: reseller_basic
                    description: 10 accounts, 50 GB
                    max_accounts: 10
                    max_disk_blocks: 51200000
                    allowed_plans:
                    - 1
                    - 2
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/plans/{plan_id}:
    get:
      summary: Returns a single plan's details by numeric ID. Routes with a non-numeric plan_id never
        reach this handler and are reported as a plain 404. A reseller gets 404 for a plan outside their
        allowed_plans, and 403 when trying to change or delete a plan that also has other owners' accounts
        on it.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: get_plans_plan_id
      tags:
      - Plans
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      name:
                        type: string
                        example: starter
                      description:
                        type: string
                        example: Starter plan
                      domains_limit:
                        type: integer
                        example: 5
                      websites_limit:
                        type: integer
                        example: 5
                      email_limit:
                        type: integer
                        example: 10
                      disk_limit:
                        type: string
                        example: '5000'
                      inodes_limit:
                        type: string
                        example: '100000'
                      db_limit:
                        type: integer
                        example: 5
                      cpu:
                        type: string
                        example: '1'
                      ram:
                        type: string
                        example: '1024'
                      bandwidth:
                        type: string
                        example: '1000'
                      feature_set:
                        type: string
                        example: default
                    example:
                      id: 1
                      name: starter
                      description: Starter plan
                      domains_limit: 5
                      websites_limit: 5
                      email_limit: 10
                      disk_limit: '5000'
                      inodes_limit: '100000'
                      db_limit: 5
                      cpu: '1'
                      ram: '1024'
                      bandwidth: '1000'
                      feature_set: default
                example:
                  plan:
                    id: 1
                    name: starter
                    description: Starter plan
                    domains_limit: 5
                    websites_limit: 5
                    email_limit: 10
                    disk_limit: '5000'
                    inodes_limit: '100000'
                    db_limit: 5
                    cpu: '1'
                    ram: '1024'
                    bandwidth: '1000'
                    feature_set: default
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    put:
      summary: Edits an existing plan by invoking 'opencli plan-edit' with the given fields. name/description
        fall back to the literal string 'None' when omitted (mirroring the CLI's own convention); other
        numeric fields default to '0'/'1'/'100'/'default'. A reseller gets 404 for a plan outside their
        allowed_plans, and 403 when trying to change or delete a plan that also has other owners' accounts
        on it.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: put_plans_plan_id
      tags:
      - Plans
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: pro
                description:
                  type: string
                  example: Updated pro plan
                disk_limit:
                  type: integer
                  example: 25000
                cpu:
                  type: integer
                  example: 2
                ram:
                  type: integer
                  example: 2048
              example:
                name: pro
                description: Updated pro plan
                disk_limit: 25000
                cpu: 2
                ram: 2048
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Plan updated successfully.
                example:
                  success: true
                  message: Plan updated successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    patch:
      summary: Same handler as PUT /api/plans/{plan_id} -- partially or fully edits an existing plan via
        'opencli plan-edit'. A reseller gets 404 for a plan outside their allowed_plans, and 403 when
        trying to change or delete a plan that also has other owners' accounts on it.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: patch_plans_plan_id
      tags:
      - Plans
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                disk_limit:
                  type: integer
                  example: 30000
              example:
                disk_limit: 30000
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Plan updated successfully.
                example:
                  success: true
                  message: Plan updated successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    delete:
      summary: Deletes a plan by numeric ID via 'opencli plan-delete <plan name> --json'. A reseller gets
        404 for a plan outside their allowed_plans, and 403 when trying to change or delete a plan that
        also has other owners' accounts on it.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: delete_plans_plan_id
      tags:
      - Plans
      parameters:
      - name: plan_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Plan deleted successfully.
                  output:
                    type: string
                    example: '{"deleted": true}'
                example:
                  success: true
                  message: Plan deleted successfully.
                  output: '{"deleted": true}'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/containers:
    get:
      summary: Returns the user's rendered podman-compose configuration (the raw 'podman-compose ... config'
        output, passed through as-is), or -- when a non-empty ?stats= query value is given -- a live 'podman
        stats' snapshot of all the user's containers instead. On lookup/config failure this still returns
        200 with an {"error":...} body rather than a JSON error status, mirroring the underlying CLI helper.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_containers
      tags:
      - Containers
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: stats
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  services:
                    type: object
                    properties:
                      web:
                        type: object
                        properties:
                          image:
                            type: string
                            example: openpanel/nginx:latest
                          ports:
                            type: array
                            items:
                              type: string
                              example: 8080:80
                            example:
                            - 8080:80
                        example:
                          image: openpanel/nginx:latest
                          ports:
                          - 8080:80
                    example:
                      web:
                        image: openpanel/nginx:latest
                        ports:
                        - 8080:80
                example:
                  services:
                    web:
                      image: openpanel/nginx:latest
                      ports:
                      - 8080:80
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/users/{username}/containers/{action}/{container_name}:
    post:
      summary: Manages a single container. action must be one of start, stop, restart, cpu, ram, or pids.
        start/stop toggle the container (start optionally accepts 'pull' to re-pull the image first);
        restart restarts it; cpu/ram/pids set the corresponding resource limit from the JSON or form field
        'value'.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: users_username_containers_action_container_name
      tags:
      - Containers
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      - name: action
        in: path
        required: true
        schema:
          type: string
      - name: container_name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: string
                  example: 512m
              example:
                value: 512m
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  response:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      message:
                        type: string
                        example: Container bob_example_com started successfully.
                    example:
                      success: true
                      message: Container bob_example_com started successfully.
                example:
                  success: true
                  response:
                    success: true
                    message: Container bob_example_com started successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/dns/cluster:
    get:
      summary: 'Returns the current DNS cluster configuration: the allow-transfer and also-notify IP lists
        parsed from the BIND config, whether clustering is enabled, and the raw config file content. If
        the config can''t be read, still returns 200 with an {"error":...} body.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_dns_cluster
      tags:
      - DNS
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  allow_transfer:
                    type: array
                    items:
                      type: string
                      example: 192.0.2.10
                    example:
                    - 192.0.2.10
                    - 192.0.2.11
                  also_notify:
                    type: array
                    items:
                      type: string
                      example: 192.0.2.10
                    example:
                    - 192.0.2.10
                    - 192.0.2.11
                  enabled:
                    type: boolean
                    example: true
                  raw_content:
                    type: string
                    example: |
                      options {
                          allow-transfer { 192.0.2.10; 192.0.2.11; };
                          also-notify { 192.0.2.10; 192.0.2.11; };
                      };
                example:
                  allow_transfer:
                  - 192.0.2.10
                  - 192.0.2.11
                  also_notify:
                  - 192.0.2.10
                  - 192.0.2.11
                  enabled: true
                  raw_content: |
                    options {
                        allow-transfer { 192.0.2.10; 192.0.2.11; };
                        also-notify { 192.0.2.10; 192.0.2.11; };
                    };
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Manages the DNS cluster based on the ''action'' field: ''enable''/''disable'' toggle clustering,
        ''create'' adds a slave IP (validated as a reachable IPv4 address via rndc, then triggers an async
        zone sync to it), and ''delete'' removes a slave IP from the config. Restarts the DNS service
        after enable/disable/create/delete.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_dns_cluster
      tags:
      - DNS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: create
                ip:
                  type: string
                  example: 192.0.2.12
              example:
                action: create
                ip: 192.0.2.12
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: IP 192.0.2.12 added to DNS cluster successfully.
                example:
                  success: true
                  message: IP 192.0.2.12 added to DNS cluster successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/dns/cluster/{ip}:
    get:
      summary: 'Checks reachability/status of a DNS cluster slave node: first tries ''rndc status'' against
        it, then falls back to running ''uname -a'' over SSH if rndc doesn''t respond with a recognizable
        status.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: dns_cluster_ip
      tags:
      - DNS
      parameters:
      - name: ip
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ip:
                    type: string
                    example: 192.0.2.12
                  status:
                    type: string
                    example: success
                  output:
                    type: string
                    example: 'number of zones: 42'
                  error:
                    type: string
                    example: null
                  method:
                    type: string
                    example: rndc
                example:
                  ip: 192.0.2.12
                  status: success
                  output: 'number of zones: 42'
                  error: null
                  method: rndc
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/dns/zone-templates:
    get:
      summary: Returns the default IPv4 and IPv6 BIND zone file templates used for new domains.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_dns_zone_templates
      tags:
      - DNS
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  zone_template_ipv4:
                    type: string
                    example: |-
                      $TTL 86400
                      @ IN SOA ns1.example.com. ...
                  zone_template_ipv6:
                    type: string
                    example: |-
                      $TTL 86400
                      @ IN SOA ns1.example.com. ...
                example:
                  zone_template_ipv4: |-
                    $TTL 86400
                    @ IN SOA ns1.example.com. ...
                  zone_template_ipv6: |-
                    $TTL 86400
                    @ IN SOA ns1.example.com. ...
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates the default IPv4 and/or IPv6 zone file templates. Either or both of zone_template_ipv4/zone_template_ipv6
        may be supplied; only the supplied ones are written to disk.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_dns_zone_templates
      tags:
      - DNS
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                zone_template_ipv4:
                  type: string
                  example: |-
                    $TTL 86400
                    @ IN SOA ns1.example.com. ...
              example:
                zone_template_ipv4: |-
                  $TTL 86400
                  @ IN SOA ns1.example.com. ...
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Template updated successfully!
                example:
                  success: true
                  message: Template updated successfully!
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/emails/settings:
    get:
      summary: 'Returns the mail server''s overall status: webmail status/domain, mailserver container
        status, total email account count, the parsed mailserver.env configuration, and the current email
        storage location.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_emails_settings
      tags:
      - Email
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webmail-status:
                    type: string
                    example: running
                  webmail-domain:
                    type: string
                    example: webmail.example.com
                  webmail-selected:
                    type: array
                    items:
                      type: string
                      example: roundcube
                    example:
                    - roundcube
                  mailserver-status:
                    type: string
                    example: running
                  emails:
                    type: integer
                    example: 12
                  config_data:
                    type: object
                    properties:
                      ENABLE_CLAMAV:
                        type: string
                        example: '1'
                      ENABLE_FAIL2BAN:
                        type: string
                        example: '1'
                      ENABLE_POP3:
                        type: string
                        example: '1'
                    example:
                      ENABLE_CLAMAV: '1'
                      ENABLE_FAIL2BAN: '1'
                      ENABLE_POP3: '1'
                  email_storage_location:
                    type: string
                    example: user_dir
                example:
                  webmail-status: running
                  webmail-domain: webmail.example.com
                  webmail-selected:
                  - roundcube
                  mailserver-status: running
                  emails: 12
                  config_data:
                    ENABLE_CLAMAV: '1'
                    ENABLE_FAIL2BAN: '1'
                    ENABLE_POP3: '1'
                  email_storage_location: user_dir
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Updates one recognized mail server setting per call: storage_type/email_storage_location,
        webmail_domain, webmail_software, or one or more ENABLE_* checkbox flags (e.g. ENABLE_CLAMAV,
        ENABLE_FAIL2BAN, ENABLE_POP3). Toggling a checkbox flag restarts the mailserver in the background.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_emails_settings
      tags:
      - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ENABLE_CLAMAV:
                  type: string
                  example: '1'
                ENABLE_FAIL2BAN:
                  type: string
                  example: '1'
              example:
                ENABLE_CLAMAV: '1'
                ENABLE_FAIL2BAN: '1'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Configuration updated! Fail2Ban and ClamAV require Mailserver to be recreated.
                      Make sure to stop&start the service.
                example:
                  success: true
                  message: Configuration updated! Fail2Ban and ClamAV require Mailserver to be recreated.
                    Make sure to stop&start the service.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/emails/accounts:
    get:
      summary: Lists all mailserver email accounts with their quotas; returns an empty list with a non-running
        status if the mailserver container isn't up.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_emails_accounts
      tags:
      - Email
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: running
                  emails:
                    type: array
                    items:
                      type: object
                      properties:
                        Email:
                          type: string
                          example: info@example.com
                        Quota:
                          type: string
                          example: '1024'
                      example:
                        Email: info@example.com
                        Quota: '1024'
                    example:
                    - Email: info@example.com
                      Quota: '1024'
                example:
                  status: running
                  emails:
                  - Email: info@example.com
                    Quota: '1024'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Performs one account-management action, selected by the ''action'' field: ''password''
        (change password), ''quota-set'', ''quota-del'', or ''restrict'' (add/remove a send or receive
        restriction).'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_emails_accounts
      tags:
      - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: password
                email:
                  type: string
                  example: info@example.com
                password:
                  type: string
                  example: NewStrongPass123
              example:
                action: password
                email: info@example.com
                password: NewStrongPass123
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Password updated.
                example:
                  message: Password updated.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    delete:
      summary: Deletes one or more email accounts given in the 'emails' array.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: delete_emails_accounts
      tags:
      - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    example: info@example.com
                  example:
                  - info@example.com
                  - sales@example.com
              example:
                emails:
                - info@example.com
                - sales@example.com
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Deleted 2 account(s).
                example:
                  message: Deleted 2 account(s).
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/emails/queue:
    get:
      summary: Returns the current Postfix mail queue contents along with the mailserver's running status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_emails_queue
      tags:
      - Email
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  queue:
                    type: array
                    items:
                      type: string
                    example: []
                  mailserver_status:
                    type: string
                    example: running
                example:
                  queue: []
                  mailserver_status: running
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Retries or deletes queued mail. 'action' is 'retry' or 'delete'; 'scope' is 'all' or 'selected'
        (with 'queue_ids' listing specific queue IDs when scope is 'selected').
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_emails_queue
      tags:
      - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: retry
                scope:
                  type: string
                  example: selected
                queue_ids:
                  type: array
                  items:
                    type: string
                    example: ABC123DEF
                  example:
                  - ABC123DEF
              example:
                action: retry
                scope: selected
                queue_ids:
                - ABC123DEF
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                example:
                  success: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/emails/domain-limits:
    get:
      summary: Returns configured postfwd rate-limit rules and known usernames, plus the raw postfwd config
        content. If a '?hits=<domain>' query parameter is given instead, returns the recent rate-limit
        hit log lines for that domain.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_emails_domain_limits
      tags:
      - Email
      parameters:
      - name: hits
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  rules:
                    type: array
                    items:
                      type: object
                      properties:
                        Username:
                          type: string
                          example: acme
                        Domain:
                          type: string
                          example: acme.com
                        Limit:
                          type: integer
                          example: 30
                        Current:
                          type: integer
                          example: 5
                      example:
                        Username: acme
                        Domain: acme.com
                        Limit: 30
                        Current: 5
                    example:
                    - Username: acme
                      Domain: acme.com
                      Limit: 30
                      Current: 5
                  usernames:
                    type: array
                    items:
                      type: string
                      example: acme
                    example:
                    - acme
                  raw_content:
                    type: string
                    example: id=limit_acme_acme_com ; sender=~.+@acme.com ; protocol_state==RCPT ; rate=30/3600
                      ; action=550 Rate limit exceeded
                example:
                  rules:
                  - Username: acme
                    Domain: acme.com
                    Limit: 30
                    Current: 5
                  usernames:
                  - acme
                  raw_content: id=limit_acme_acme_com ; sender=~.+@acme.com ; protocol_state==RCPT ; rate=30/3600
                    ; action=550 Rate limit exceeded
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Manages postfwd rate-limit rules: either writes raw postfwd config directly via ''raw_content'',
        or performs an ''action'' of update-domain, reset-domain, reset-user, reset-all, delete-domain,
        delete-user, or delete-all.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_emails_domain_limits
      tags:
      - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: update-domain
                domain:
                  type: string
                  example: acme.com
                username:
                  type: string
                  example: acme
                limit:
                  type: integer
                  example: 30
              example:
                action: update-domain
                domain: acme.com
                username: acme
                limit: 30
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Rule saved.
                example:
                  ok: true
                  message: Rule saved.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/basic-auth:
    get:
      summary: Returns the current HTTP Basic Auth protection settings configured for OpenAdmin itself.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_security_basic_auth
      tags:
      - Security
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  basic_auth:
                    type: string
                    example: 'yes'
                  basic_auth_username:
                    type: string
                    example: admin
                  basic_auth_password:
                    type: string
                    example: secret123
                example:
                  basic_auth: 'yes'
                  basic_auth_username: admin
                  basic_auth_password: secret123
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates HTTP Basic Auth settings for OpenAdmin (enabled flag, username, password); any
        provided fields are written to config and OpenAdmin is flagged for restart.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_security_basic_auth
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                basic_auth:
                  type: string
                  example: 'yes'
                basic_auth_username:
                  type: string
                  example: admin
                basic_auth_password:
                  type: string
                  example: secret123
              example:
                basic_auth: 'yes'
                basic_auth_username: admin
                basic_auth_password: secret123
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Basic_auth settings for OpenAdmin edited successfully.
                example:
                  success: true
                  message: Basic_auth settings for OpenAdmin edited successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/blacklist-useragents:
    get:
      summary: Returns whether the blacklisted-useragents feature is enabled and the current blacklist
        file contents.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_security_blacklist_useragents
      tags:
      - Security
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  blacklist_useragents_enabled:
                    type: string
                    example: 'yes'
                  blacklist_useragents:
                    type: string
                    example: |-
                      sqlmap
                      nikto
                      masscan
                example:
                  blacklist_useragents_enabled: 'yes'
                  blacklist_useragents: |-
                    sqlmap
                    nikto
                    masscan
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates the blacklisted user-agents list and/or the enabled flag; flags OpenPanel for restart
        if anything changed.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_security_blacklist_useragents
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                blacklist_useragents:
                  type: string
                  example: |-
                    sqlmap
                    nikto
                    masscan
                enabled:
                  type: string
                  example: 'yes'
              example:
                blacklist_useragents: |-
                  sqlmap
                  nikto
                  masscan
                enabled: 'yes'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Saved blacklisted useragents.
                  blacklist_useragents_enabled:
                    type: string
                    example: 'yes'
                example:
                  success: true
                  message: Saved blacklisted useragents.
                  blacklist_useragents_enabled: 'yes'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/disable-admin:
    post:
      summary: Disables OpenAdmin entirely (runs 'opencli admin off' in the background), after which OpenAdmin
        must be managed via terminal.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: security_disable_admin
      tags:
      - Security
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: OpenAdmin is now disabled and all further actions need to be performed via
                      terminal.
                example:
                  success: true
                  message: OpenAdmin is now disabled and all further actions need to be performed via
                    terminal.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/firewall:
    get:
      summary: Reports whether the ConfigServer Firewall (csf) command is available on the host.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_security_firewall
      tags:
      - Security
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  available:
                    type: boolean
                    example: true
                example:
                  available: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Passes an arbitrary set of key=value parameters through to csf.pl (written to a temp file
        and executed) and returns its raw output; mirrors the CSF admin iframe's query-string plumbing.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_security_firewall
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: ka
                ip:
                  type: string
                  example: 203.0.113.9
              example:
                action: ka
                ip: 203.0.113.9
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  output:
                    type: string
                    example: 'ConfigServer Firewall: IP added to allow list'
                example:
                  output: 'ConfigServer Firewall: IP added to allow list'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/bot-control:
    get:
      summary: 'AI & bot control state: whether the bot_control module is on, the rate limit (requests
        per minute per AI crawler per domain), the policy of every domain and the "Who''s hitting the
        server" traffic report from the Caddy access logs. A reseller only gets the domains of their own
        users and their logs.'
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: get_security_bot_control
      tags:
      - Security
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  module_enabled:
                    type: boolean
                    example: true
                  rate_limit:
                    type: integer
                    example: 10
                  domains:
                    type: array
                    items:
                      type: object
                      properties:
                        domain:
                          type: string
                          example: example.com
                        owner:
                          type: string
                          example: stefan
                        policy:
                          type: string
                          example: ratelimit
                        requests:
                          type: integer
                          example: 1520
                        ai_requests:
                          type: integer
                          example: 312
                        blocked_count:
                          type: integer
                          example: 40
                      example:
                        domain: example.com
                        owner: stefan
                        policy: ratelimit
                        requests: 1520
                        ai_requests: 312
                        blocked_count: 40
                    example:
                    - domain: example.com
                      owner: stefan
                      policy: ratelimit
                      requests: 1520
                      ai_requests: 312
                      blocked_count: 40
                  policy_counts:
                    type: object
                    properties:
                      allow:
                        type: integer
                        example: 3
                      ratelimit:
                        type: integer
                        example: 1
                      block:
                        type: integer
                        example: 0
                    example:
                      allow: 3
                      ratelimit: 1
                      block: 0
                  report:
                    type: object
                    properties:
                      window:
                        type: string
                        example: 24h
                      scope:
                        type: string
                        example: All domains
                      total_requests:
                        type: integer
                        example: 1520
                      ai_requests:
                        type: integer
                        example: 312
                      blocked_count:
                        type: integer
                        example: 40
                    example:
                      window: 24h
                      scope: All domains
                      total_requests: 1520
                      ai_requests: 312
                      blocked_count: 40
                example:
                  module_enabled: true
                  rate_limit: 10
                  domains:
                  - domain: example.com
                    owner: stefan
                    policy: ratelimit
                    requests: 1520
                    ai_requests: 312
                    blocked_count: 40
                  policy_counts:
                    allow: 3
                    ratelimit: 1
                    block: 0
                  report:
                    window: 24h
                    scope: All domains
                    total_requests: 1520
                    ai_requests: 312
                    blocked_count: 40
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Change AI & bot control. action set_policy sets one domain to allow, ratelimit or block;
        apply_all sets every domain (a reseller's own users' domains only); set_rate_limit changes the
        requests per minute (1-100000, default 10) saved in /etc/openpanel/caddy/botcontrol.conf; enable_module
        and disable_module toggle the bot_control module, disabling puts every domain back on allow. set_rate_limit,
        enable_module and disable_module are administrator only, a reseller gets 403. Caddy is reloaded
        and the files are put back if it rejects the change.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: post_security_bot_control
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: set_policy
                domain:
                  type: string
                  example: example.com
                policy:
                  type: string
                  example: block
              example:
                action: set_policy
                domain: example.com
                policy: block
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Updated AI & bot policy for example.com to 'block'.
                  rate_limit:
                    type: integer
                    example: 10
                example:
                  success: true
                  message: Updated AI & bot policy for example.com to 'block'.
                  rate_limit: 10
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/waf:
    get:
      summary: Returns whether CorazaWAF is enabled and a summary count of total/active/inactive WAF rule
        sets.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_security_waf
      tags:
      - Security
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'on'
                  total_sets:
                    type: integer
                    example: 5
                  active_sets:
                    type: integer
                    example: 4
                  inactive_sets:
                    type: integer
                    example: 1
                example:
                  status: 'on'
                  total_sets: 5
                  active_sets: 4
                  inactive_sets: 1
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Enables or disables CorazaWAF, given status 'yes' or 'no'; then returns the same status/rule-set
        summary as the GET.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_security_waf
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  example: 'yes'
              example:
                status: 'yes'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: 'on'
                  total_sets:
                    type: integer
                    example: 5
                  active_sets:
                    type: integer
                    example: 5
                  inactive_sets:
                    type: integer
                    example: 0
                example:
                  status: 'on'
                  total_sets: 5
                  active_sets: 5
                  inactive_sets: 0
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/waf/rules:
    get:
      summary: Lists every WAF rule set file with its name, path, non-empty line count, and on/off status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_security_waf_rules
      tags:
      - Security
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Enables or disables a single WAF rule set by name, renaming its .conf/.conf.disabled file
        accordingly. Caddy must be restarted afterward to apply changes.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_security_waf_rules
      tags:
      - Security
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rule_name:
                  type: string
                  example: xss
                action:
                  type: string
                  example: 'on'
              example:
                rule_name: xss
                action: 'on'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Rules set enabled. Restart Caddy to apply changes.
                example:
                  success: true
                  message: Rules set enabled. Restart Caddy to apply changes.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/2fa:
    get:
      summary: Returns the caller's own TOTP 2FA status. If 2FA is already enabled, returns only that
        flag; if not, mints and returns a brand-new TOTP secret and QR code data URI for enrollment on
        every call (stateless, no session caching).
      description: '**Access:** Any authenticated user.'
      operationId: security_2fa
      tags:
      - Two-Factor Authentication
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  totp_enabled:
                    type: boolean
                    example: false
                  secret:
                    type: string
                    example: JBSWY3DPEHPK3PXP
                  qr_data_uri:
                    type: string
                    example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
                example:
                  totp_enabled: false
                  secret: JBSWY3DPEHPK3PXP
                  qr_data_uri: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/2fa/enable:
    post:
      summary: Enables TOTP 2FA for the caller's own account after validating the submitted code against
        the given secret.
      description: '**Access:** Any authenticated user.'
      operationId: security_2fa_enable
      tags:
      - Two-Factor Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                secret:
                  type: string
                  example: JBSWY3DPEHPK3PXP
                code:
                  type: string
                  example: '123456'
              example:
                secret: JBSWY3DPEHPK3PXP
                code: '123456'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Two-factor authentication has been enabled.
                example:
                  success: true
                  message: Two-factor authentication has been enabled.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/2fa/disable:
    post:
      summary: Disables TOTP 2FA for the caller's own account after verifying the account password.
      description: '**Access:** Any authenticated user.'
      operationId: security_2fa_disable
      tags:
      - Two-Factor Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  example: CurrentPassword123
              example:
                password: CurrentPassword123
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Two-factor authentication has been disabled.
                example:
                  success: true
                  message: Two-factor authentication has been disabled.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/security/passkeys:
    get:
      summary: Lists the caller's own registered passkeys (id, optional name, created_at), newest first.
        Registering a new passkey isn't supported over this JSON API since it requires a browser/authenticator
        round trip.
      description: '**Access:** Any authenticated user.'
      operationId: get_security_passkeys
      tags:
      - Passkeys
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  passkeys:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 4
                        name:
                          type: string
                          example: YubiKey 5
                        created_at:
                          type: string
                          example: '2026-05-01T12:00:00Z'
                      example:
                        id: 4
                        name: YubiKey 5
                        created_at: '2026-05-01T12:00:00Z'
                    example:
                    - id: 4
                      name: YubiKey 5
                      created_at: '2026-05-01T12:00:00Z'
                    - id: 3
                      name: null
                      created_at: '2026-01-10T09:30:00Z'
                example:
                  passkeys:
                  - id: 4
                    name: YubiKey 5
                    created_at: '2026-05-01T12:00:00Z'
                  - id: 3
                    name: null
                    created_at: '2026-01-10T09:30:00Z'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Renames one of the caller's own passkeys, identified by id (must belong to the caller).
      description: '**Access:** Any authenticated user.'
      operationId: post_security_passkeys
      tags:
      - Passkeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  example: 4
                name:
                  type: string
                  example: Work laptop
              example:
                id: 4
                name: Work laptop
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Passkey renamed.
                example:
                  success: true
                  message: Passkey renamed.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    delete:
      summary: Deletes one of the caller's own passkeys, identified by id (must belong to the caller).
      description: '**Access:** Any authenticated user.'
      operationId: delete_security_passkeys
      tags:
      - Passkeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  example: 4
              example:
                id: 4
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Passkey removed.
                example:
                  success: true
                  message: Passkey removed.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services:
    get:
      summary: Returns the raw parsed contents of the monitored-services config file (services.json) verbatim,
        whatever shape it happens to be.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_services
      tags:
      - Services
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    put:
      summary: Overwrites the monitored-services config file wholesale with the JSON request body (pretty-printed
        before writing).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: put_services
      tags:
      - Services
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: Caddy
                  real_name:
                    type: string
                    example: caddy
                  type:
                    type: string
                    example: docker
                  on_dashboard:
                    type: boolean
                    example: true
                example:
                  name: Caddy
                  real_name: caddy
                  type: docker
                  on_dashboard: true
              example:
              - name: Caddy
                real_name: caddy
                type: docker
                on_dashboard: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: /etc/openadmin/services.json updated successfully
                example:
                  message: /etc/openadmin/services.json updated successfully
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/status:
    get:
      summary: 'Returns every monitored service flagged on_dashboard, each as its full config entry plus
        a live ''status'' field (''Active'', ''Inactive'', or ''Error: ...'' if the underlying check failed).
        Docker-type services are checked via a single ''podman ps'' call; others via systemctl is-active.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_status
      tags:
      - Services
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/service/{action}/{service_name}:
    post:
      summary: Starts, stops, or restarts one monitored service by name (action is one of start/restart/stop).
        Docker-backed services (e.g. caddy, openpanel, mailserver) are managed via podman-compose up/down;
        all others via the generic 'service <name> <action>' command. Only services flagged on_dashboard
        in services.json may be targeted.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: service_action_service_name
      tags:
      - Services
      parameters:
      - name: action
        in: path
        required: true
        schema:
          type: string
      - name: service_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: string
                    example: Caddy started successfully
                example:
                  success: Caddy started successfully
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman:
    get:
      summary: podman info text, every image, volume and network, and disk usage in one call.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman
      tags:
      - Podman
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/images:
    get:
      summary: Every image in the shared podman store, with system/user container usage, update-check
        and vulnerability-scan status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_images
      tags:
      - Podman
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/volumes:
    get:
      summary: Every podman volume.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_volumes
      tags:
      - Podman
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/networks:
    get:
      summary: Every podman network.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_networks
      tags:
      - Podman
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/disk-usage:
    get:
      summary: 'podman system df: disk used by images, containers and volumes.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_disk_usage
      tags:
      - Podman
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/images/{action}/{id}:
    post:
      summary: action is delete (id = full image ID) or pull (id = repository:tag). Runs in the background,
        poll /api/services/podman/images/action-status. Never affects running containers.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_images_action_id
      tags:
      - Podman
      parameters:
      - name: action
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: May contain '/' - this segment matches the rest of the path.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/images/action-status:
    get:
      summary: Progress of an image delete/pull.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_images_action_status
      tags:
      - Podman
      parameters:
      - name: id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/images/check-update:
    get:
      summary: Compares the local manifest digest of an image with the registry, only runs on demand.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_images_check_update
      tags:
      - Podman
      parameters:
      - name: ref
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/images/bulk/{action}:
    post:
      summary: action is pull-missing, delete-unused, check-updates or check-vulnerabilities (Trivy HIGH/CRITICAL
        scan, Trivy is installed on first use). Runs in the background across all applicable images, poll
        /api/services/podman/images/bulk-status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_images_bulk_action
      tags:
      - Podman
      parameters:
      - name: action
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/images/bulk-status:
    get:
      summary: Progress of the running bulk image action.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_images_bulk_status
      tags:
      - Podman
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/services/podman/images/vulnerabilities:
    get:
      summary: Cached findings of the last check-vulnerabilities run for an image, never starts a scan.
        checked is false if the image was never scanned.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: services_podman_images_vulnerabilities
      tags:
      - Podman
      parameters:
      - name: ref
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  checked:
                    type: boolean
                    example: true
                  details:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: CVE-2024-12345
                        package:
                          type: string
                          example: openssl
                        installed_version:
                          type: string
                          example: 1.1.1
                        fixed_version:
                          type: string
                          example: 1.1.2
                        severity:
                          type: string
                          example: CRITICAL
                        title:
                          type: string
                          example: Buffer overflow in OpenSSL
                        url:
                          type: string
                          example: https://avd.aquasec.com/nvd/cve-2024-12345
                      example:
                        id: CVE-2024-12345
                        package: openssl
                        installed_version: 1.1.1
                        fixed_version: 1.1.2
                        severity: CRITICAL
                        title: Buffer overflow in OpenSSL
                        url: https://avd.aquasec.com/nvd/cve-2024-12345
                    example:
                    - id: CVE-2024-12345
                      package: openssl
                      installed_version: 1.1.1
                      fixed_version: 1.1.2
                      severity: CRITICAL
                      title: Buffer overflow in OpenSSL
                      url: https://avd.aquasec.com/nvd/cve-2024-12345
                example:
                  checked: true
                  details:
                  - id: CVE-2024-12345
                    package: openssl
                    installed_version: 1.1.1
                    fixed_version: 1.1.2
                    severity: CRITICAL
                    title: Buffer overflow in OpenSSL
                    url: https://avd.aquasec.com/nvd/cve-2024-12345
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/system:
    get:
      summary: System (config-only) backup destination and retention settings, run history and existing
        archives.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_system
      tags:
      - Backups
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/system/settings:
    post:
      summary: Saves the system backup destination and retention.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_system_settings
      tags:
      - Backups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destination:
                  type: string
                  example: /var/backups/openpanel
                retention_days:
                  type: string
                  example: '30'
              example:
                destination: /var/backups/openpanel
                retention_days: '30'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/system/run:
    post:
      summary: Starts a new config-only system backup (opencli backup) in the background, poll /api/backups/system/action-status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_system_run
      tags:
      - Backups
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/system/restore/{filename}:
    post:
      summary: Restores a system backup archive in the background, poll /api/backups/system/action-status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_system_restore_filename
      tags:
      - Backups
      parameters:
      - name: filename
        in: path
        required: true
        schema:
          type: string
        description: May contain '/' - this segment matches the rest of the path.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/system/delete/{filename}:
    post:
      summary: Deletes a system backup archive.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_system_delete_filename
      tags:
      - Backups
      parameters:
      - name: filename
        in: path
        required: true
        schema:
          type: string
        description: May contain '/' - this segment matches the rest of the path.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/system/action-status:
    get:
      summary: Progress of the running system backup or restore.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_system_action_status
      tags:
      - Backups
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/user:
    get:
      summary: 'The central per-user backup schedule: disabled (each user manages their own backups),
        daily, weekly or monthly.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_user
      tags:
      - Backups
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/user/settings:
    post:
      summary: Sets the central per-user backup schedule.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_user_settings
      tags:
      - Backups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                schedule_choice:
                  type: string
                  example: daily
              example:
                schedule_choice: daily
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/user/configuration:
    get:
      summary: Raw contents of the backup.env template new accounts are provisioned with.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_backups_user_configuration
      tags:
      - Backups
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Saves the backup.env template, applies to new users only.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_backups_user_configuration
      tags:
      - Backups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                backup_env:
                  type: string
                  example: '...'
              example:
                backup_env: '...'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/user/run:
    post:
      summary: Starts a central opencli docker-backup run in the background. 400 unless the schedule is
        daily, weekly or monthly. Poll /api/backups/user/action-status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_user_run
      tags:
      - Backups
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/backups/user/action-status:
    get:
      summary: Progress of the running central user backup.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: backups_user_action_status
      tags:
      - Backups
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/docker/info:
    get:
      summary: Returns the raw JSON output of 'podman info --format json', passed through unmodified.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: docker_info
      tags:
      - System
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  host:
                    type: object
                    properties:
                      os:
                        type: string
                        example: linux
                      kernel:
                        type: string
                        example: 5.15.0-generic
                    example:
                      os: linux
                      kernel: 5.15.0-generic
                  store:
                    type: object
                    properties:
                      graphDriverName:
                        type: string
                        example: overlay
                    example:
                      graphDriverName: overlay
                example:
                  host:
                    os: linux
                    kernel: 5.15.0-generic
                  store:
                    graphDriverName: overlay
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/ips:
    get:
      summary: Returns every account's dedicated IP address, keyed by username, read from each account's
        own ip.json file (accounts with no such file are omitted).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: ips
      tags:
      - System
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alice:
                    type: string
                    example: 203.0.113.9
                  bob:
                    type: string
                    example: 203.0.113.10
                example:
                  alice: 203.0.113.9
                  bob: 203.0.113.10
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/system:
    get:
      summary: 'Returns a snapshot of host system information: hostname, OS, kernel version, CPU model,
        uptime (seconds), running process count, OpenPanel version, and available package updates count.'
      description: '**Access:** Any authenticated user.'
      operationId: system
      tags:
      - System
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  hostname:
                    type: string
                    example: server1
                  os:
                    type: string
                    example: Ubuntu 22.04.3 LTS
                  time:
                    type: string
                    example: '2026-08-12 10:15:30'
                  kernel:
                    type: string
                    example: 5.15.0-91-generic
                  cpu:
                    type: string
                    example: Intel(R) Xeon(R) CPU E5-2690 v4
                  openpanel_version:
                    type: string
                    example: 1.4.2
                  uptime:
                    type: string
                    example: '384210'
                  running_processes:
                    type: string
                    example: '187'
                  package_updates:
                    type: string
                    example: '3'
                example:
                  hostname: server1
                  os: Ubuntu 22.04.3 LTS
                  time: '2026-08-12 10:15:30'
                  kernel: 5.15.0-91-generic
                  cpu: Intel(R) Xeon(R) CPU E5-2690 v4
                  openpanel_version: 1.4.2
                  uptime: '384210'
                  running_processes: '187'
                  package_updates: '3'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/usage/cpu:
    get:
      summary: Returns per-core CPU usage percentages from a 1-second blocking sample, keyed by core name.
      description: '**Access:** Any authenticated user.'
      operationId: usage_cpu
      tags:
      - System
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cpu0:
                    type: number
                    example: 12.5
                  cpu1:
                    type: number
                    example: 8.3
                example:
                  cpu0: 12.5
                  cpu1: 8.3
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/usage/memory:
    get:
      summary: 'Returns current RAM usage: raw byte figures (total/available/used/percent) plus a human-readable
        version of the same figures.'
      description: '**Access:** Any authenticated user.'
      operationId: usage_memory
      tags:
      - System
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ram_info:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 16777216000
                      available:
                        type: integer
                        example: 8388608000
                      used:
                        type: integer
                        example: 8388608000
                      percent:
                        type: number
                        example: 50.0
                    example:
                      total: 16777216000
                      available: 8388608000
                      used: 8388608000
                      percent: 50.0
                  human_readable_info:
                    type: object
                    properties:
                      total:
                        type: string
                        example: 15.63 GB
                      available:
                        type: string
                        example: 7.81 GB
                      used:
                        type: string
                        example: 7.81 GB
                      percent:
                        type: string
                        example: 50%
                    example:
                      total: 15.63 GB
                      available: 7.81 GB
                      used: 7.81 GB
                      percent: 50%
                example:
                  ram_info:
                    total: 16777216000
                    available: 8388608000
                    used: 8388608000
                    percent: 50.0
                  human_readable_info:
                    total: 15.63 GB
                    available: 7.81 GB
                    used: 7.81 GB
                    percent: 50%
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/usage/server:
    get:
      summary: Returns disk usage for every mounted filesystem (excluding pseudo-filesystems, /snap, and
        podman storage), each with device, mountpoint, fstype, and total/used/free bytes plus used percent.
      description: '**Access:** Any authenticated user.'
      operationId: usage_server
      tags:
      - System
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/usage/disk:
    get:
      summary: Returns per-user disk and inode quota usage, keyed by username, read from the quota report
        file (generated on demand via 'opencli user-quota' if missing). Bandwidth fields are always hardcoded
        to 0. A reseller only gets the accounts they own.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: usage_disk
      tags:
      - System
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  alice:
                    type: object
                    properties:
                      diskusage:
                        type: integer
                        example: 100
                      disklimit:
                        type: integer
                        example: 1000
                      inodesusage:
                        type: integer
                        example: 5
                      inodeslimit:
                        type: integer
                        example: 0
                      bwusage:
                        type: integer
                        example: 0
                      bwlimit:
                        type: integer
                        example: 0
                    example:
                      diskusage: 100
                      disklimit: 1000
                      inodesusage: 5
                      inodeslimit: 0
                      bwusage: 0
                      bwlimit: 0
                example:
                  alice:
                    diskusage: 100
                    disklimit: 1000
                    inodesusage: 5
                    inodeslimit: 0
                    bwusage: 0
                    bwlimit: 0
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/notifications:
    get:
      summary: Returns all notification log lines, newest first, with blank lines skipped; creates an
        empty log file if none exists yet.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: notifications
      tags:
      - Notifications
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  notifications:
                    type: array
                    items:
                      type: string
                      example: '2026-08-12 10:00:00 UNREAD New user registered: alice'
                    example:
                    - '2026-08-12 10:00:00 UNREAD New user registered: alice'
                    - 2026-08-11 09:30:00 READ Backup completed successfully
                example:
                  success: true
                  notifications:
                  - '2026-08-12 10:00:00 UNREAD New user registered: alice'
                  - 2026-08-11 09:30:00 READ Backup completed successfully
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/notifications/{line_number}/read:
    post:
      summary: Marks one notification as read, identified by its 1-indexed line_number counted from the
        newest (bottom-of-file) entry; if a 'command=mark_all_as_read' query param or JSON body field
        is given instead, marks every notification as read.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: notifications_line_number_read
      tags:
      - Notifications
      parameters:
      - name: line_number
        in: path
        required: true
        schema:
          type: string
      - name: command
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                example:
                  success: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/notifications/{line_number}:
    delete:
      summary: Deletes one notification, identified by its 1-indexed line_number counted from the newest
        entry; if a 'command=delete_all' query param or JSON body field is given instead, deletes every
        notification.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: notifications_line_number
      tags:
      - Notifications
      parameters:
      - name: line_number
        in: path
        required: true
        schema:
          type: string
      - name: command
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                example:
                  success: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/notifications/pause:
    get:
      summary: Returns whether email/webhook notifications are currently paused and, if so, the unix timestamp
        they resume at. Paused state is a flag file at /tmp/openpanel_notifications_paused that opencli
        sentinel.sh checks before sending an alert, and cleans up itself once expired.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_notifications_pause
      tags:
      - Notifications
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  paused:
                    type: boolean
                    example: true
                  until:
                    type: integer
                    example: 1789999382
                example:
                  paused: true
                  until: 1789999382
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Pauses email/webhook notifications for the given duration; the notification log itself
        keeps recording events as usual, only the email/webhook sends are skipped while paused.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_notifications_pause
      tags:
      - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                duration:
                  type: string
                  example: 10m
              example:
                duration: 10m
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  paused:
                    type: boolean
                    example: true
                  until:
                    type: integer
                    example: 1789999382
                example:
                  success: true
                  paused: true
                  until: 1789999382
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/notifications/resume:
    post:
      summary: Resumes email/webhook notifications immediately by removing the pause flag file.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: notifications_resume
      tags:
      - Notifications
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                example:
                  success: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/crons:
    get:
      summary: Lists every parsed line of the managed crontab (line number, schedule, command, and logging
        flag); returns null if the crontab file is missing.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_server_crons
      tags:
      - Cron Jobs
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Rewrites the schedule and logging flag of one or more existing crontab lines, identified
        by line number, reusing the same cron-line rewriting logic as the HTML /server/crons page.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_server_crons
      tags:
      - Cron Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jobs:
                  type: array
                  items:
                    type: object
                    properties:
                      line_number:
                        type: integer
                        example: 1
                      schedule:
                        type: string
                        example: 0 4 * * *
                      logging:
                        type: boolean
                        example: false
                    example:
                      line_number: 1
                      schedule: 0 4 * * *
                      logging: false
                  example:
                  - line_number: 1
                    schedule: 0 4 * * *
                    logging: false
              example:
                jobs:
                - line_number: 1
                  schedule: 0 4 * * *
                  logging: false
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Cron jobs updated successfully
                example:
                  success: true
                  message: Cron jobs updated successfully
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/ssh:
    get:
      summary: Returns the current sshd service status, the raw sshd_config contents, the list of authorized_keys
        entries, and the parsed basic settings (port, password/pubkey auth, permit root login).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_server_ssh
      tags:
      - SSH
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: active
                  config:
                    type: string
                    example: |
                      Port 22
                      PasswordAuthentication yes
                      PubkeyAuthentication no
                      PermitRootLogin yes
                  keys:
                    type: array
                    items:
                      type: object
                      properties:
                        comment:
                          type: string
                          example: user@laptop
                        key:
                          type: string
                          example: ssh-ed25519 AAAA... user@laptop
                      example:
                        comment: user@laptop
                        key: ssh-ed25519 AAAA... user@laptop
                    example:
                    - comment: user@laptop
                      key: ssh-ed25519 AAAA... user@laptop
                  port:
                    type: string
                    example: '22'
                  password_auth:
                    type: string
                    example: 'yes'
                  pubkey_auth:
                    type: string
                    example: 'no'
                  permit_root_login:
                    type: string
                    example: 'yes'
                example:
                  status: active
                  config: |
                    Port 22
                    PasswordAuthentication yes
                    PubkeyAuthentication no
                    PermitRootLogin yes
                  keys:
                  - comment: user@laptop
                    key: ssh-ed25519 AAAA... user@laptop
                  port: '22'
                  password_auth: 'yes'
                  pubkey_auth: 'no'
                  permit_root_login: 'yes'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Performs exactly one SSH-management action per request, chosen by priority order from
        the body: control the sshd service (action), overwrite the raw sshd_config (config), add an authorized
        key (new_key), remove an authorized key (key_to_remove), or update basic settings (port/password_auth/pubkey_auth/permit_root_login).
        Unlike the HTML form equivalent, only the first matching field is acted on and the response names
        exactly which operation ran.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_server_ssh
      tags:
      - SSH
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: restart
              example:
                action: restart
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: SSH service has been restarted.
                example:
                  success: true
                  message: SSH service has been restarted.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/ssh/config:
    get:
      summary: Returns the raw contents of sshd_config as a single string.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_server_ssh_config
      tags:
      - SSH
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  config:
                    type: string
                    example: |
                      Port 22
                      PasswordAuthentication yes
                      PubkeyAuthentication no
                      PermitRootLogin yes
                example:
                  config: |
                    Port 22
                    PasswordAuthentication yes
                    PubkeyAuthentication no
                    PermitRootLogin yes
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Overwrites sshd_config with the supplied raw text and restarts the SSH service to apply
        it.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_server_ssh_config
      tags:
      - SSH
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  type: string
                  example: |
                    Port 22
                    PasswordAuthentication yes
                    PubkeyAuthentication no
                    PermitRootLogin yes
              example:
                config: |
                  Port 22
                  PasswordAuthentication yes
                  PubkeyAuthentication no
                  PermitRootLogin yes
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: SSH configuration updated and service restarted.
                example:
                  success: true
                  message: SSH configuration updated and service restarted.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/timezone:
    get:
      summary: Returns the server's currently configured timezone (read via `timedatectl`, falling back
        to /etc/localtime) plus the full list of available IANA timezone names.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_server_timezone
      tags:
      - Server
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  current_timezone:
                    type: string
                    example: UTC
                  available_timezones:
                    type: array
                    items:
                      type: string
                      example: Africa/Abidjan
                    example:
                    - Africa/Abidjan
                    - America/New_York
                example:
                  current_timezone: UTC
                  available_timezones:
                  - Africa/Abidjan
                  - America/New_York
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Changes the server's system timezone via `timedatectl set-timezone`, after validating the
        requested value is a known timezone name.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_server_timezone
      tags:
      - Server
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                timezone:
                  type: string
                  example: America/New_York
              example:
                timezone: America/New_York
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  timezone:
                    type: string
                    example: America/New_York
                example:
                  success: true
                  timezone: America/New_York
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/memory/drop-cache:
    post:
      summary: Drops the Linux page/dentry/inode caches by running `sync; echo 3 > /proc/sys/vm/drop_caches`,
        freeing cached (but reclaimable) RAM.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: server_memory_drop_cache
      tags:
      - Server
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Cache dropped successfully.
                example:
                  status: success
                  message: Cache dropped successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/memory/drop-swap:
    post:
      summary: Clears swap by running `swapoff -a && swapon -a` in the background (fire-and-forget); the
        response is returned immediately with HTTP 202 before the cycle necessarily completes.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: server_memory_drop_swap
      tags:
      - Server
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Swap clearing started in background.
                example:
                  status: success
                  message: Swap clearing started in background.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/swap:
    get:
      summary: Swap total/used/free/percent, every active swap device, the alert threshold and whether
        a managed swap file exists.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: server_swap
      tags:
      - Server
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/swap/action/{action}:
    post:
      summary: action is resize (recreate the managed swap file at size_mb, minimum 128, and enable it,
        adding it to /etc/fstab if needed) or drop (swapoff -a; swapon -a). Runs in the background, poll
        /api/server/swap/action-status.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: server_swap_action_action
      tags:
      - Server
      parameters:
      - name: action
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                size_mb:
                  type: integer
                  example: 2048
              example:
                size_mb: 2048
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/swap/action-status:
    get:
      summary: Progress of the running swap resize/drop.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: server_swap_action_status
      tags:
      - Server
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/processes:
    get:
      summary: 'Lists all running system processes parsed from /proc (PID, name, CPU%, memory%, priority,
        owner, command), sorted by the given criterion (default: CPU descending).'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: server_processes
      tags:
      - Processes
      parameters:
      - name: sort
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/processes/{pid}/{action}:
    post:
      summary: Performs an action on a specific process by PID. Only the 'kill' action is permitted via
        this API route (no strace/streaming support here, unlike the HTML process manager page).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: server_processes_pid_action
      tags:
      - Processes
      parameters:
      - name: pid
        in: path
        required: true
        schema:
          type: string
      - name: action
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Process with PID 1234 killed successfully
                example:
                  success: true
                  message: Process with PID 1234 killed successfully
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/root-password:
    post:
      summary: 'DANGEROUS: changes the server''s root Linux user password (via `passwd root`) and verifies
        the change took effect. Restricted to the super-admin role since it grants full root shell/SSH
        access to whoever knows the new password.'
      description: '**Access:** The Super Admin (role must be exactly "admin") only.'
      operationId: server_root_password
      tags:
      - Power & Root Access
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  example: a-strong-new-root-password
              example:
                password: a-strong-new-root-password
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: SSH password changed successfully!
                example:
                  success: true
                  message: SSH password changed successfully!
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/reboot:
    post:
      summary: 'DANGEROUS: reboots or hard-crashes the physical/virtual server. ''graceful'' schedules
        a normal `reboot` after a 15s delay; ''hard'' schedules writing to /proc/sysrq-trigger after a
        10s delay, forcibly resetting the machine without a clean shutdown. This call blocks until the
        delay elapses and the command runs, and can be disabled entirely via a flag file (/root/disable_openadmin_reboot_ui),
        in which case it returns 403.'
      description: '**Access:** The Super Admin (role must be exactly "admin") only.'
      operationId: server_reboot
      tags:
      - Power & Root Access
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reboot_type:
                  type: string
                  example: graceful
              example:
                reboot_type: graceful
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  reboot_started:
                    type: boolean
                    example: true
                example:
                  success: true
                  reboot_started: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/reboot/status:
    get:
      summary: Lightweight liveness probe used to detect when the server has come back up after a reboot;
        simply confirms the OpenAdmin API is reachable and responding.
      description: '**Access:** Any authenticated user.'
      operationId: server_reboot_status
      tags:
      - Power & Root Access
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: up
                example:
                  status: up
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/server/migrate:
    get:
      summary: 'Polls the status of a background `opencli server-migrate` run: ''running'' while the recorded
        PID is still alive, ''finished'' once it has exited, or ''unknown'' if no migration has been started
        (no pid file). Also returns the accumulated log output.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_server_migrate
      tags:
      - Migration
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: running
                  output:
                    type: string
                    example: |
                      Connecting to 1.2.3.4...
                      Syncing accounts...
                example:
                  status: running
                  output: |
                    Connecting to 1.2.3.4...
                    Syncing accounts...
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Starts a background server-to-server migration (`opencli server-migrate`) that copies data
        from a remote source server to this one, given the remote host, its root user, and its password.
        All three fields are required.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_server_migrate
      tags:
      - Migration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                host:
                  type: string
                  example: 1.2.3.4
                root:
                  type: string
                  example: root
                password:
                  type: string
                  example: remote-root-password
              example:
                host: 1.2.3.4
                root: root
                password: remote-root-password
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Migration process started.
                example:
                  success: true
                  message: Migration process started.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/administrators:
    get:
      summary: Lists all administrator accounts (users with a non-reseller role), including last login
        IP/time, 2FA status, and whether passkeys are registered.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_administrators
      tags:
      - Settings - Administrators
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Runs one administrator-account action (create/reset_password/rename_user/suspend/unsuspend/delete/disable_2fa/disable_passkeys)
        selected by the 'action' field, reusing the same opencli/admindb plumbing as the HTML administrators
        page.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_administrators
      tags:
      - Settings - Administrators
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: create
                username:
                  type: string
                  example: newadmin
                password:
                  type: string
                  example: S3cret1
                new_password:
                  type: string
                  example: ''
                new_username:
                  type: string
                  example: ''
              example:
                action: create
                username: newadmin
                password: S3cret1
                new_password: ''
                new_username: ''
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: 'Successfully created a new admin user: newadmin'
                example:
                  success: true
                  message: 'Successfully created a new admin user: newadmin'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/resellers:
    get:
      summary: Lists all reseller accounts with account/disk quota usage and allowed plans; a reseller
        caller is rejected with 403 (only admins may list other resellers).
      description: '**Access:** Any authenticated user.'
      operationId: get_settings_resellers
      tags:
      - Settings - Resellers
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Runs one reseller-account action (create/reset_password/rename_user/update/change_plan/update_branding/suspend/unsuspend/delete/disable_2fa/disable_passkeys);
        create and change_plan accept a reseller plan name in plan; delete moves the reseller's accounts
        to admin, or deletes them too when with_users is true; suspend also suspends the reseller's active
        accounts and unsuspend wakes only those; a caller with the reseller role can only ever reset their
        own password through this endpoint regardless of the submitted action/username.
      description: '**Access:** Any authenticated user.'
      operationId: post_settings_resellers
      tags:
      - Settings - Resellers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: update
                username:
                  type: string
                  example: reseller1
                allowed_plans:
                  type: string
                  example: 1,2,3
                max_accounts:
                  type: string
                  example: '50'
                max_disk_blocks:
                  type: string
                  example: '1048576'
              example:
                action: update
                username: reseller1
                allowed_plans: 1,2,3
                max_accounts: '50'
                max_disk_blocks: '1048576'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: OK
                example:
                  success: true
                  message: OK
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/resellers/{username}:
    get:
      summary: Returns one reseller account with its package, limits and usage (same fields as the list),
        404 if the user doesn't exist or isn't a reseller.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: settings_resellers_username
      tags:
      - Settings - Resellers
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    example: reseller1
                  is_active:
                    type: boolean
                    example: true
                  role:
                    type: string
                    example: reseller
                  last_ip:
                    type: string
                    example: 203.0.113.9
                  last_login:
                    type: string
                    example: '2026-08-09 14:02:11'
                  totp_enabled:
                    type: boolean
                    example: false
                  passkeys_enabled:
                    type: boolean
                    example: false
                  max_accounts:
                    type: integer
                    example: 50
                  current_accounts:
                    type: integer
                    example: 12
                  current_disk_blocks:
                    type: integer
                    example: 204800
                  max_disk_blocks:
                    type: integer
                    example: 1048576
                  allowed_plans:
                    type: array
                    items:
                      type: integer
                      example: 1
                    example:
                    - 1
                    - 2
                    - 3
                  logo_url:
                    type: string
                    example: ''
                  reseller_plan:
                    type: string
                    example: reseller_basic
                example:
                  username: reseller1
                  is_active: true
                  role: reseller
                  last_ip: 203.0.113.9
                  last_login: '2026-08-09 14:02:11'
                  totp_enabled: false
                  passkeys_enabled: false
                  max_accounts: 50
                  current_accounts: 12
                  current_disk_blocks: 204800
                  max_disk_blocks: 1048576
                  allowed_plans:
                  - 1
                  - 2
                  - 3
                  logo_url: ''
                  reseller_plan: reseller_basic
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/resellers/{username}/login:
    post:
      summary: Issues a one-time OpenAdmin login link for a reseller without their password, for billing
        integrations; open login_path on the panel within expires_in seconds. 404 if not a reseller, 403
        if suspended.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: settings_resellers_username_login
      tags:
      - Settings - Resellers
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    example: 3f9c...
                  login_path:
                    type: string
                    example: /login/sso/3f9c...
                  expires_in:
                    type: integer
                    example: 120
                example:
                  token: 3f9c...
                  login_path: /login/sso/3f9c...
                  expires_in: 120
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/resellers/enabled:
    get:
      summary: Whether reseller accounts can be created (off by default).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_resellers_enabled
      tags:
      - Settings - Resellers
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                    example: false
                example:
                  enabled: false
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Turns reseller accounts on or off. Turning it off is refused with 409 while any reseller
        account exists.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_resellers_enabled
      tags:
      - Settings - Resellers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                  example: true
              example:
                enabled: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  enabled:
                    type: boolean
                    example: true
                example:
                  success: true
                  enabled: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/general:
    get:
      summary: 'Returns the current general server settings: the user-panel and admin-panel ports, the
        reverse-proxy backend, the forced admin domain, and whether dev mode is on.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_general
      tags:
      - Settings - General
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  port:
                    type: string
                    example: '2083'
                  admin_port:
                    type: string
                    example: '2087'
                  proxy:
                    type: string
                    example: openpanel
                  force_domain:
                    type: string
                    example: panel.example.com
                  dev_mode:
                    type: string
                    example: 'off'
                example:
                  port: '2083'
                  admin_port: '2087'
                  proxy: openpanel
                  force_domain: panel.example.com
                  dev_mode: 'off'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates general server settings (domain, ports, proxy backend, dev mode); applies only
        the values that changed, writes OpenPanel/OpenAdmin restart-needed flag files as appropriate,
        and reports which settings were changed.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_general
      tags:
      - Settings - General
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                force_domain:
                  type: string
                  example: panel.example.com
                2087_port:
                  type: string
                  example: '2087'
                2083_port:
                  type: string
                  example: '2083'
                openpanel_proxy:
                  type: string
                  example: openpanel
                dev_mode:
                  type: string
                  example: 'off'
              example:
                force_domain: panel.example.com
                2087_port: '2087'
                2083_port: '2083'
                openpanel_proxy: openpanel
                dev_mode: 'off'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  changes:
                    type: array
                    items:
                      type: string
                      example: user-panel port
                    example:
                    - user-panel port
                    - domain
                  message:
                    type: string
                    example: 'Settings updated: user-panel port, domain'
                example:
                  success: true
                  changes:
                  - user-panel port
                  - domain
                  message: 'Settings updated: user-panel port, domain'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/defaults:
    get:
      summary: Returns the grouped default .env values for new accounts, the available PHP versions data,
        and the list of available vs. currently active autostart services.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_defaults
      tags:
      - Settings - Defaults
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  defaults:
                    type: object
                    properties:
                      DEFAULTS:
                        type: object
                        properties:
                          VARNISH:
                            type: boolean
                            example: false
                          CPU:
                            type: string
                            example: '1'
                          RAM:
                            type: string
                            example: '512'
                        example:
                          VARNISH: false
                          CPU: '1'
                          RAM: '512'
                    example:
                      DEFAULTS:
                        VARNISH: false
                        CPU: '1'
                        RAM: '512'
                  php_versions_data:
                    type: object
                    properties: {}
                    example: {}
                  autostart_available_services:
                    type: array
                    items:
                      type: string
                      example: nginx
                    example:
                    - nginx
                    - clamav
                    - phpmyadmin
                  autostart_active_services:
                    type: array
                    items:
                      type: string
                      example: nginx
                    example:
                    - nginx
                example:
                  defaults:
                    DEFAULTS:
                      VARNISH: false
                      CPU: '1'
                      RAM: '512'
                  php_versions_data: {}
                  autostart_available_services:
                  - nginx
                  - clamav
                  - phpmyadmin
                  autostart_active_services:
                  - nginx
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates key/value entries in the default .env file (rewriting matching keys in place, uncommenting/commenting
        PROXY_HTTP_PORT based on VARNISH) and, if 'services' is provided, replaces the autostart-services
        file with the valid subset of the submitted list.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_defaults
      tags:
      - Settings - Defaults
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                values:
                  type: object
                  properties:
                    VARNISH:
                      type: string
                      example: '1'
                    SOME_RAM:
                      type: string
                      example: '1024'
                  example:
                    VARNISH: '1'
                    SOME_RAM: '1024'
                services:
                  type: array
                  items:
                    type: string
                    example: nginx
                  example:
                  - nginx
                  - clamav
              example:
                values:
                  VARNISH: '1'
                  SOME_RAM: '1024'
                services:
                - nginx
                - clamav
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: New defaults saved successfully!
                example:
                  success: true
                  message: New defaults saved successfully!
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/defaults/files:
    get:
      summary: Returns the raw contents of the default account-template .env and docker-compose.yml files.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_defaults_files
      tags:
      - Settings - Defaults
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  env:
                    type: string
                    example: |
                      VARNISH="0"
                      CPU="1"
                  compose:
                    type: string
                    example: |
                      version: "3"
                      services:
                        web:
                          image: openpanel/openpanel
                example:
                  env: |
                    VARNISH="0"
                    CPU="1"
                  compose: |
                    version: "3"
                    services:
                      web:
                        image: openpanel/openpanel
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Overwrites the default .env and/or docker-compose.yml template files with the submitted
        raw content (each field applied only when present and non-null).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_defaults_files
      tags:
      - Settings - Defaults
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                env:
                  type: string
                  example: |
                    VARNISH="1"
                    CPU="2"
                compose:
                  type: string
                  example: |
                    version: "3"
                    services:
                      web:
                        image: openpanel/openpanel
              example:
                env: |
                  VARNISH="1"
                  CPU="2"
                compose: |
                  version: "3"
                  services:
                    web:
                      image: openpanel/openpanel
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Files updated successfully!
                example:
                  success: true
                  message: Files updated successfully!
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    delete:
      summary: Resets the default .env and docker-compose.yml template files by re-fetching both from
        their canonical GitHub source; reports per-file errors instead of failing outright if only one
        fetch fails.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: delete_settings_defaults_files
      tags:
      - Settings - Defaults
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Defaults reset successfully from remote source!
                example:
                  success: true
                  message: Defaults reset successfully from remote source!
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/defaults/files/{username}:
    get:
      summary: Returns the raw .env and docker-compose.yml contents from a specific user's home directory
        (resolved from {username} via their docker context).
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: get_settings_defaults_files_username
      tags:
      - Settings - Defaults
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  env:
                    type: string
                    example: |
                      VARNISH="0"
                  compose:
                    type: string
                    example: |
                      version: "3"
                      services:
                        web:
                          image: openpanel/openpanel
                example:
                  env: |
                    VARNISH="0"
                  compose: |
                    version: "3"
                    services:
                      web:
                        image: openpanel/openpanel
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Overwrites the .env and/or docker-compose.yml files in a specific user's home directory
        with the submitted content, then returns the resulting file contents.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: post_settings_defaults_files_username
      tags:
      - Settings - Defaults
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                env:
                  type: string
                  example: |
                    VARNISH="1"
                compose:
                  type: string
                  example: |
                    version: "3"
                    services:
                      web:
                        image: openpanel/openpanel
              example:
                env: |
                  VARNISH="1"
                compose: |
                  version: "3"
                  services:
                    web:
                      image: openpanel/openpanel
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  env:
                    type: string
                    example: |
                      VARNISH="1"
                  compose:
                    type: string
                    example: |
                      version: "3"
                      services:
                        web:
                          image: openpanel/openpanel
                example:
                  env: |
                    VARNISH="1"
                  compose: |
                    version: "3"
                    services:
                      web:
                        image: openpanel/openpanel
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/features:
    get:
      summary: 'Lists the names of all feature sets visible to the acting user: global feature sets plus
        the acting reseller''s own (a reseller only sees their own sets).'
      description: '**Access:** Any authenticated user.'
      operationId: get_settings_features
      tags:
      - Settings - Plan Features
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Creates a new, empty feature set file named by 'feature_name' (in the global directory
        for admins, or the acting reseller's own directory for resellers); fails if a set with that name
        already exists.
      description: '**Access:** Any authenticated user.'
      operationId: post_settings_features
      tags:
      - Settings - Plan Features
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                feature_name:
                  type: string
                  example: premium
              example:
                feature_name: premium
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Feature set created successfully.
                example:
                  success: true
                  message: Feature set created successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/features/{plan}:
    get:
      summary: Returns the enabled modules for the given feature set plus the full feature/plugin catalog,
        each entry annotated with its enabled ('status') and module-availability ('module_enabled') state.
      description: '**Access:** Any authenticated user.'
      operationId: get_settings_features_plan
      tags:
      - Settings - Plan Features
      parameters:
      - name: plan
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled_modules:
                    type: array
                    items:
                      type: string
                      example: wordpress
                    example:
                    - wordpress
                    - backups
                  plan:
                    type: string
                    example: premium
                  features:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: wordpress
                        status:
                          type: boolean
                          example: true
                        module_enabled:
                          type: boolean
                          example: true
                      example:
                        name: wordpress
                        status: true
                        module_enabled: true
                    example:
                    - name: wordpress
                      status: true
                      module_enabled: true
                  plugins:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: custom-plugin
                        status:
                          type: boolean
                          example: false
                        module_enabled:
                          type: boolean
                          example: true
                      example:
                        name: custom-plugin
                        status: false
                        module_enabled: true
                    example:
                    - name: custom-plugin
                      status: false
                      module_enabled: true
                example:
                  enabled_modules:
                  - wordpress
                  - backups
                  plan: premium
                  features:
                  - name: wordpress
                    status: true
                    module_enabled: true
                  plugins:
                  - name: custom-plugin
                    status: false
                    module_enabled: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Applies an action to a feature set: ''update'' replaces its enabled feature list, ''enable_all''/''disable_all''
        toggle every known feature, or ''delete'' removes the set (rejected for the ''default'' set or
        a set still in use by a hosting package).'
      description: '**Access:** Any authenticated user.'
      operationId: post_settings_features_plan
      tags:
      - Settings - Plan Features
      parameters:
      - name: plan
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  example: update
                features:
                  type: array
                  items:
                    type: string
                    example: wordpress
                  example:
                  - wordpress
                  - backups
                  - ssl
              example:
                action: update
                features:
                - wordpress
                - backups
                - ssl
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Feature set premium updated (update).
                example:
                  success: true
                  message: Feature set premium updated (update).
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/locales:
    get:
      summary: Lists translation locales available on GitHub, marking which are installed locally and
        which one is the current default. update_available is true when the installed file differs from
        the latest version on GitHub.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_locales
      tags:
      - Settings - Locales
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  default_locale:
                    type: string
                    example: en
                  translations:
                    type: array
                    items:
                      type: object
                      properties:
                        locale:
                          type: string
                          example: en
                        provider:
                          type: string
                          example: OpenPanel
                        path:
                          type: string
                          example: /etc/openpanel/openadmin/translations/en
                        installed:
                          type: boolean
                          example: true
                        is_default:
                          type: boolean
                          example: true
                        update_available:
                          type: boolean
                          example: false
                      example:
                        locale: en
                        provider: OpenPanel
                        path: /etc/openpanel/openadmin/translations/en
                        installed: true
                        is_default: true
                        update_available: false
                    example:
                    - locale: en
                      provider: OpenPanel
                      path: /etc/openpanel/openadmin/translations/en
                      installed: true
                      is_default: true
                      update_available: false
                    - locale: de-DE
                      provider: Community
                      path: ''
                      installed: false
                      is_default: false
                      update_available: false
                example:
                  default_locale: en
                  translations:
                  - locale: en
                    provider: OpenPanel
                    path: /etc/openpanel/openadmin/translations/en
                    installed: true
                    is_default: true
                    update_available: false
                  - locale: de-DE
                    provider: Community
                    path: ''
                    installed: false
                    is_default: false
                    update_available: false
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Installs a locale (''locale'' field), updates an installed one (''update'' field), deletes
        one (''delete'' field), or sets the panel''s default locale (''default'' field); exactly one field
        is expected per call. Pass ''all'' to ''locale'' to install every available locale, or to ''update''
        to update every locale that has an update available. With {"locale": "all"} or any ''update''
        value the response also carries ''installed'' and ''failed'' arrays, and success is false if any
        locale failed to download. The default locale can''t be deleted.'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_locales
      tags:
      - Settings - Locales
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                locale:
                  type: string
                  example: de-DE
                update:
                  type: string
                  example: ''
                delete:
                  type: string
                  example: ''
                default:
                  type: string
                  example: ''
              example:
                locale: de-DE
                update: ''
                delete: ''
                default: ''
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Locale 'de-DE' installed successfully.
                  installed:
                    type: array
                    items:
                      type: string
                      example: de-de
                    example:
                    - de-de
                    - sr-rs
                  failed:
                    type: array
                    items:
                      type: string
                    example: []
                example:
                  success: true
                  message: Locale 'de-DE' installed successfully.
                  installed:
                  - de-de
                  - sr-rs
                  failed: []
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/modules:
    get:
      summary: Returns the full module/feature catalog (each entry annotated with its enabled status)
        and the list of installed plugins.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_modules
      tags:
      - Settings - Modules
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  features:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: phpmyadmin
                        status:
                          type: boolean
                          example: true
                      example:
                        name: phpmyadmin
                        status: true
                    example:
                    - name: phpmyadmin
                      status: true
                  plugins:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          example: custom-plugin
                      example:
                        name: custom-plugin
                    example:
                    - name: custom-plugin
                example:
                  features:
                  - name: phpmyadmin
                    status: true
                  plugins:
                  - name: custom-plugin
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Replaces the enabled_modules list in the modules config file, toggles the phpmyadmin/clamav
        docker-compose services to match, generates the DNS rndc key if a DNS module was newly enabled,
        and flags OpenPanel for restart.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_modules
      tags:
      - Settings - Modules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled_modules:
                  type: array
                  items:
                    type: string
                    example: phpmyadmin
                  example:
                  - phpmyadmin
                  - malware_scan
                  - dns
              example:
                enabled_modules:
                - phpmyadmin
                - malware_scan
                - dns
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Modules updated successfully.
                example:
                  success: true
                  message: Modules updated successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/custom-code:
    get:
      summary: Returns the raw contents of every custom-code file (custom CSS/JS, header/footer snippets,
        startup/post-update scripts, forbidden usernames, restricted domains, how-to guides, WordPress
        theme/plugin sets, PageSpeed API key), keyed by field name.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_custom_code
      tags:
      - Settings - Custom Code
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  custom_css:
                    type: string
                    example: '.brand { color: #123; }'
                  custom_js:
                    type: string
                    example: ''
                  in_header:
                    type: string
                    example: ''
                  in_footer:
                    type: string
                    example: ''
                  post_update:
                    type: string
                    example: ''
                  pre_startup:
                    type: string
                    example: ''
                  custom_section:
                    type: string
                    example: ''
                  forbidden_usernames:
                    type: string
                    example: |
                      admin
                      root
                  restricted_domains:
                    type: string
                    example: ''
                  howto_guides:
                    type: string
                    example: ''
                  wp_themes:
                    type: string
                    example: ''
                  wp_plugins:
                    type: string
                    example: ''
                  pagespeed_api_key:
                    type: string
                    example: ''
                example:
                  custom_css: '.brand { color: #123; }'
                  custom_js: ''
                  in_header: ''
                  in_footer: ''
                  post_update: ''
                  pre_startup: ''
                  custom_section: ''
                  forbidden_usernames: |
                    admin
                    root
                  restricted_domains: ''
                  howto_guides: ''
                  wp_themes: ''
                  wp_plugins: ''
                  pagespeed_api_key: ''
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Writes any of the custom-code fields present as string values in the body to their corresponding
        files and flags OpenPanel for restart. Unlike the HTML page, this API endpoint applies no Enterprise-license/reseller-role
        gating on the Enterprise-only fields (custom_css, custom_js, in_header, in_footer, custom_section,
        howto_guides).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_custom_code
      tags:
      - Settings - Custom Code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                custom_css:
                  type: string
                  example: '.brand { color: #123; }'
                forbidden_usernames:
                  type: string
                  example: |
                    admin
                    root
              example:
                custom_css: '.brand { color: #123; }'
                forbidden_usernames: |
                  admin
                  root
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Files updated successfully!
                example:
                  success: true
                  message: Files updated successfully!
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/php:
    get:
      summary: Returns the raw contents of the global PHP options.txt file plus each PHP version's php.ini
        file, keyed by 'options' and version keys like 'php81'.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_php
      tags:
      - Settings - PHP
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  options:
                    type: string
                    example: |
                      max_execution_time=30
                  php56:
                    type: string
                    example: |
                      memory_limit=128M
                  php74:
                    type: string
                    example: |
                      memory_limit=256M
                  php81:
                    type: string
                    example: |
                      memory_limit=512M
                example:
                  options: |
                    max_execution_time=30
                  php56: |
                    memory_limit=128M
                  php74: |
                    memory_limit=256M
                  php81: |
                    memory_limit=512M
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Overwrites the global PHP options.txt and/or one or more per-version php.ini files with
        the submitted string content; reports which keys were actually updated.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_php
      tags:
      - Settings - PHP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                options:
                  type: string
                  example: |
                    max_execution_time=60
                php81:
                  type: string
                  example: |
                    memory_limit=1024M
              example:
                options: |
                  max_execution_time=60
                php81: |
                  memory_limit=1024M
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  updated:
                    type: array
                    items:
                      type: string
                      example: options
                    example:
                    - options
                    - php81
                example:
                  success: true
                  updated:
                  - options
                  - php81
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/caddy/metrics:
    get:
      summary: Proxies Caddy's local admin API /metrics endpoint verbatim as a text/plain Prometheus-format
        body; a fetch failure or non-2xx upstream status is reported as a 500 plaintext error message
        instead.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: settings_caddy_metrics
      tags:
      - Settings - Caddy
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: string
                example: |
                  # HELP caddy_admin_http_requests_total Counter of requests made to the Admin API's HTTP endpoints.
                  caddy_admin_http_requests_total{...} 42
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/updates:
    get:
      summary: Returns the current update config (autoupdate/autopatch settings), the latest available
        panel version, and the recent update log entries.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_updates
      tags:
      - Settings - Updates
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  config_data:
                    type: object
                    properties:
                      DEFAULT:
                        type: object
                        properties:
                          autoupdate:
                            type: string
                            example: 'on'
                          autopatch:
                            type: string
                            example: 'on'
                        example:
                          autoupdate: 'on'
                          autopatch: 'on'
                    example:
                      DEFAULT:
                        autoupdate: 'on'
                        autopatch: 'on'
                  latest_version:
                    type: string
                    example: 3.4.2
                  update_logs:
                    type: array
                    items:
                      type: object
                      properties:
                        file:
                          type: string
                          example: update_20260810.log
                        log_dir:
                          type: string
                          example: /var/log/openpanel/updates
                        timestamp:
                          type: integer
                          example: 1786435200
                        human_readable_timestamp:
                          type: string
                          example: '2026-08-10 12:00:00'
                      example:
                        file: update_20260810.log
                        log_dir: /var/log/openpanel/updates
                        timestamp: 1786435200
                        human_readable_timestamp: '2026-08-10 12:00:00'
                    example:
                    - file: update_20260810.log
                      log_dir: /var/log/openpanel/updates
                      timestamp: 1786435200
                      human_readable_timestamp: '2026-08-10 12:00:00'
                example:
                  config_data:
                    DEFAULT:
                      autoupdate: 'on'
                      autopatch: 'on'
                  latest_version: 3.4.2
                  update_logs:
                  - file: update_20260810.log
                    log_dir: /var/log/openpanel/updates
                    timestamp: 1786435200
                    human_readable_timestamp: '2026-08-10 12:00:00'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Sets the auto-update preference (one of minor_and_major, minor_only, major_only, none),
        rewriting the corresponding autoupdate/autopatch on/off flags in the update config file.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_updates
      tags:
      - Settings - Updates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                preference:
                  type: string
                  example: minor_and_major
              example:
                preference: minor_and_major
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Update preferences saved successfully.
                example:
                  success: true
                  message: Update preferences saved successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/updates/now:
    post:
      summary: Kicks off an immediate panel update in the background (no request body); returns immediately
        once the update process has been started, not once it has finished.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: settings_updates_now
      tags:
      - Settings - Updates
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Update process started successfully.
                example:
                  success: true
                  message: Update process started successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/updates/tags:
    get:
      summary: Lists available OpenPanel docker image tags/versions fetched from Docker Hub.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_updates_tags
      tags:
      - Settings - Updates
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: 'Pins the panel to a specific version: writes the version into the compose .env file, pulls
        that image tag, and runs docker-compose up to switch to it (used for downgrades as well as pinned
        upgrades).'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_updates_tags
      tags:
      - Settings - Updates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  example: 3.4.1
              example:
                version: 3.4.1
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Downgraded to version 3.4.1 successfully.
                example:
                  success: true
                  message: Downgraded to version 3.4.1 successfully.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/settings/notifications:
    get:
      summary: Returns the notification email/SMTP settings, the SSH allowlist, and the full notifications
        config (thresholds, HTTP limits, per-action toggles).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_settings_notifications
      tags:
      - Settings - Notifications
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email_address:
                    type: string
                    example: admin@example.com
                  mail_server:
                    type: string
                    example: smtp.example.com
                  mail_port:
                    type: string
                    example: '465'
                  mail_use_tls:
                    type: string
                    example: 'no'
                  mail_use_ssl:
                    type: string
                    example: 'yes'
                  mail_debug:
                    type: string
                    example: 'no'
                  mail_username:
                    type: string
                    example: admin@example.com
                  mail_password:
                    type: string
                    example: ''
                  mail_default_sender:
                    type: string
                    example: admin@example.com
                  ssh_whitelist:
                    type: string
                    example: |
                      203.0.113.0/24
                  settings:
                    type: object
                    properties:
                      DEFAULT:
                        type: object
                        properties:
                          load:
                            type: string
                            example: '90'
                          cpu:
                            type: string
                            example: '90'
                          ram:
                            type: string
                            example: '90'
                          du:
                            type: string
                            example: '90'
                          swap:
                            type: string
                            example: '90'
                          update:
                            type: string
                            example: 'yes'
                          attack:
                            type: string
                            example: 'yes'
                        example:
                          load: '90'
                          cpu: '90'
                          ram: '90'
                          du: '90'
                          swap: '90'
                          update: 'yes'
                          attack: 'yes'
                      HTTP:
                        type: object
                        properties:
                          max_total_conn:
                            type: string
                            example: '1000'
                          max_conn_per_ip:
                            type: string
                            example: '50'
                        example:
                          max_total_conn: '1000'
                          max_conn_per_ip: '50'
                      ACTIONS:
                        type: object
                        properties:
                          admin_create:
                            type: string
                            example: 'yes'
                          user_create:
                            type: string
                            example: 'yes'
                        example:
                          admin_create: 'yes'
                          user_create: 'yes'
                    example:
                      DEFAULT:
                        load: '90'
                        cpu: '90'
                        ram: '90'
                        du: '90'
                        swap: '90'
                        update: 'yes'
                        attack: 'yes'
                      HTTP:
                        max_total_conn: '1000'
                        max_conn_per_ip: '50'
                      ACTIONS:
                        admin_create: 'yes'
                        user_create: 'yes'
                example:
                  email_address: admin@example.com
                  mail_server: smtp.example.com
                  mail_port: '465'
                  mail_use_tls: 'no'
                  mail_use_ssl: 'yes'
                  mail_debug: 'no'
                  mail_username: admin@example.com
                  mail_password: ''
                  mail_default_sender: admin@example.com
                  ssh_whitelist: |
                    203.0.113.0/24
                  settings:
                    DEFAULT:
                      load: '90'
                      cpu: '90'
                      ram: '90'
                      du: '90'
                      swap: '90'
                      update: 'yes'
                      attack: 'yes'
                    HTTP:
                      max_total_conn: '1000'
                      max_conn_per_ip: '50'
                    ACTIONS:
                      admin_create: 'yes'
                      user_create: 'yes'
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Updates notification thresholds, HTTP connection limits, webhook URL, notification email,
        SMTP settings, per-action/default toggles, and the SSH allowlist -- each field is applied only
        when present (and changed) in the JSON body, and a malformed SSH allowlist entry (invalid IP/CIDR)
        fails the whole request with a 400.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_settings_notifications
      tags:
      - Settings - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                load:
                  type: integer
                  example: 90
                cpu:
                  type: integer
                  example: 90
                ram:
                  type: integer
                  example: 90
                du:
                  type: integer
                  example: 90
                swap:
                  type: integer
                  example: 90
                max_total_conn:
                  type: integer
                  example: 1000
                max_conn_per_ip:
                  type: integer
                  example: 50
                webhook_url:
                  type: string
                  example: https://hooks.example.com/notify
                email:
                  type: string
                  example: admin@example.com
                mail_server:
                  type: string
                  example: smtp.example.com
                mail_port:
                  type: string
                  example: '465'
                mail_use_tls:
                  type: string
                  example: 'no'
                mail_use_ssl:
                  type: string
                  example: 'yes'
                mail_username:
                  type: string
                  example: admin@example.com
                mail_password:
                  type: string
                  example: s3cret
                mail_default_sender:
                  type: string
                  example: admin@example.com
                update:
                  type: string
                  example: 'yes'
                attack:
                  type: string
                  example: 'yes'
                admin_create:
                  type: string
                  example: 'yes'
                ssh_whitelist:
                  type: string
                  example: |
                    203.0.113.0/24
                    198.51.100.10/32
              example:
                load: 90
                cpu: 90
                ram: 90
                du: 90
                swap: 90
                max_total_conn: 1000
                max_conn_per_ip: 50
                webhook_url: https://hooks.example.com/notify
                email: admin@example.com
                mail_server: smtp.example.com
                mail_port: '465'
                mail_use_tls: 'no'
                mail_use_ssl: 'yes'
                mail_username: admin@example.com
                mail_password: s3cret
                mail_default_sender: admin@example.com
                update: 'yes'
                attack: 'yes'
                admin_create: 'yes'
                ssh_whitelist: |
                  203.0.113.0/24
                  198.51.100.10/32
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Notification settings updated.
                example:
                  success: true
                  message: Notification settings updated.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/license:
    get:
      summary: Reads the currently configured license key by running `opencli license key --json` and
        returns it verbatim (trimmed).
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_license
      tags:
      - License
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  key:
                    type: string
                    example: enterprise-abc123
                example:
                  key: enterprise-abc123
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Sets/activates a new license key by running `opencli license <key> --json --no-restart`,
        which validates the key against the licensing server before applying it.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_license
      tags:
      - License
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                  example: enterprise-xyz
              example:
                key: enterprise-xyz
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                    example: activated
                example:
                  response: activated
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    delete:
      summary: Removes the currently configured license key by running `opencli license delete --json`.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: delete_license
      tags:
      - License
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  delete:
                    type: string
                    example: deleted
                example:
                  delete: deleted
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/license/info:
    get:
      summary: Returns details about the currently active license by running `opencli license info --json`.
        Wired directly to LicensePage.ServeLicenseInfo, whose JSON shape is identical to this API route.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: license_info
      tags:
      - License
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  info:
                    type: string
                    example: info-output
                example:
                  info: info-output
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/license/verify:
    post:
      summary: Re-verifies the current license against the licensing server by running `opencli license
        verify --json`. Wired directly to LicensePage.ServeLicenseVerify, whose JSON shape is identical
        to this API route.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: license_verify
      tags:
      - License
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  verify:
                    type: string
                    example: verify-output
                example:
                  verify: verify-output
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/support/report:
    get:
      summary: 'Generates a public, non-interactive diagnostics report by running `opencli report --public
        --non-interactive` and returns its output as JSON text (not a downloadable file -- writeJSON sets
        Content-Type: application/json and the report text is embedded in the "message" field).'
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: support_report
      tags:
      - Support
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: report contents
                example:
                  success: true
                  message: report contents
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/import/{panel_type}:
    get:
      summary: Lists import log files (with derived status) for a given backup panel type. `panel_type`
        must be one of "cpanel" or "cyberpanel" (unlike the HTML /import/{panel_type} route, "openpanel"
        restores are not exposed here -- see /user/import instead); any other value returns 400.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_import_panel_type
      tags:
      - Import & Transfers
      parameters:
      - name: panel_type
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Starts an import of a cPanel or CyberPanel backup into a new OpenPanel account, cloning/running
        the import script for the given backup path and target hosting plan in the background.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_import_panel_type
      tags:
      - Import & Transfers
      parameters:
      - name: panel_type
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
                  example: /root/backup-user.tar.gz
                plan_name:
                  type: string
                  example: default_plan_apache
              example:
                path: /root/backup-user.tar.gz
                plan_name: default_plan_apache
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Import process from /root/backup-user.tar.gz (CyberPanel backup) has started.
                example:
                  success: true
                  message: Import process from /root/backup-user.tar.gz (CyberPanel backup) has started.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/import/logs/account/{log_filename}:
    get:
      summary: Returns the raw contents of a single account-import log file as JSON. `{log_filename...}`
        is a Go 1.22+ wildcard path segment and may contain slashes (a nested relative path under the
        import log directory); a path that resolves outside that directory, or a missing/non-file target,
        returns 404.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: import_logs_account_log_filename
      tags:
      - Import & Transfers
      parameters:
      - name: log_filename
        in: path
        required: true
        schema:
          type: string
        description: May contain '/' - this segment matches the rest of the path.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  log:
                    type: string
                    example: hello log
                example:
                  status: success
                  log: hello log
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/import/backup-files:
    get:
      summary: Performs a shallow (non-recursive) scan of /, /home, and /root for cPanel/CyberPanel (backup-*.tar.gz)
        or OpenPanel (<user>_<date>_<time>.tar.gz) style backup archives and returns the matched absolute
        paths as a flat array. Delegates to the same logic as the HTML admin /json/backup-files route.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: import_backup_files
      tags:
      - Import & Transfers
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/import/transfers:
    get:
      summary: Lists every OpenPanel-to-OpenPanel transfer log file (*.log) directly under the transfer
        log directory, as a flat array of file paths. Delegates to the same logic as the HTML admin /json/transfers
        route.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: get_import_transfers
      tags:
      - Import & Transfers
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
    post:
      summary: Starts a live OpenPanel-to-OpenPanel account transfer in the background by running `opencli
        user-transfer` with the given target account, host, and SSH credentials. If the target server
        is an IP (not a domain), it also configures iptables for the transfer.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: post_import_transfers
      tags:
      - Import & Transfers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                openpanel_username:
                  type: string
                  example: newuser
                server:
                  type: string
                  example: example.com
                username:
                  type: string
                  example: root
                password:
                  type: string
                  example: secret
                port:
                  type: integer
                  example: 2222
                live_transfer:
                  type: boolean
                  example: true
              example:
                openpanel_username: newuser
                server: example.com
                username: root
                password: secret
                port: 2222
                live_transfer: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Transfer process for account newuser started in the background.
                example:
                  success: true
                  message: Transfer process for account newuser started in the background.
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/import/transfers/{username}:
    get:
      summary: Scans the transfer log directory for logs belonging to a given OpenPanel username and reports
        each transfer's current status (derived from the log's PID/SUCCESS markers and whether that PID
        is still alive). A "SUSPENDED_" prefix on the username is stripped before scanning, mirroring
        the suspended-account naming convention used elsewhere.
      description: '**Access:** Administrator/user role, or a reseller who owns the target account.'
      operationId: import_transfers_username
      tags:
      - Import & Transfers
      parameters:
      - name: username
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/import/logs/transfer/{log_filename}:
    get:
      summary: Returns the raw contents of a single transfer log file as JSON. `{log_filename...}` is
        a Go 1.22+ wildcard path segment and may contain slashes (a nested relative path under the transfer
        log directory); a path that resolves outside that directory, or a missing/non-file target, returns
        404.
      description: '**Access:** Administrator or user role (the reseller role is blocked).'
      operationId: import_logs_transfer_log_filename
      tags:
      - Import & Transfers
      parameters:
      - name: log_filename
        in: path
        required: true
        schema:
          type: string
        description: May contain '/' - this segment matches the rest of the path.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  log:
                    type: string
                    example: transfer log
                example:
                  status: success
                  log: transfer log
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
  /api/import/upload:
    post:
      summary: Uploads an OpenPanel backup (.tar.gz in a multipart 'file' field) to /home/reseller_imports/<username>/;
        the response has the path to pass to POST /api/import/openpanel.
      description: '**Access:** Administrator/user role, or a reseller limited to their own accounts and
        assigned plans.'
      operationId: import_upload
      tags:
      - Import & Transfers
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties: {}
                example: {}
        default:
          $ref: '#/components/responses/Error'
      security:
      - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Obtain a token via `POST /api/` (username/password login). Tokens expire after 15 minutes.
  responses:
    Error:
      description: An error occurred. See the `error` field for details.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: 'Forbidden: administrator role required'
            required:
            - error
security:
- bearerAuth: []
