openapi: 3.1.0
info:
  title: MineStrator API
  version: 1.0.0
  summary: Official REST API of MineStrator.com
  termsOfService: 'https://minestrator.com/en/terms/and/conditions'
  x-overview: |
    MineStrator context (for AI assistants, not shown in the HTML docs):

    MineStrator is a server host — mainly game servers (Minecraft, etc.), but also other
    services: databases, tools (Grafana, Prometheus…) or runtimes (Node.js, Python,
    Ruby…). A customer subscribes to a MyBox (a plan with a resource quota: CPU, RAM,
    disk, databases) and creates one or more servers inside it that share those resources.

    - User: the customer account; it owns MyBoxes and servers (or accesses them as a
      sub-user with delegated permissions).
    - MyBox: a customer's plan, a pool of resources (CPU / RAM / disk / databases). A
      MyBox contains one or more servers.
    - Server: an instance hosted inside a MyBox — most often a game server, but also a
      database, a tool or a runtime — with its allocated share of resources.

    This API lets you control your servers (status, power, commands, settings) and read
    your account and MyBoxes.
  description: |
    ## Authentication

    Every request must include your API key **base64-encoded** in the `Authorization`
    header:

    ```
    Authorization: Bearer base64(YOUR_KEY)
    ```

    Find your key in your panel: [Account → API keys](https://minestrator.com/my/account?section=api).

    ## Terms of use

    The API is available to all MineStrator.com customers.
    Use from an external application must be controlled, reasonable
    and within the scope of standard use of MineStrator.com services.
    In case of abuse, API access may be disabled and the associated account suspended.

    Use of the API is subject to MineStrator's [terms of use](https://minestrator.com/en/terms/and/conditions).
  contact:
    name: MineStrator
    url: 'https://minestrator.com'
servers:
  - url: 'https://mine.sttr.io'
    description: Production
security:
  - BearerAuth: []
tags:
  - name: User
    description: Account and user data
  - name: Server
    description: Manage and control servers
  - name: MyBox
    description: MyBox plans and associated servers
  - name: Snapshots
    description: Snapshots de serveurs (sauvegardes complètes)
paths:
  /user:
    get:
      tags:
        - User
      summary: Get your profile
      description: |
        Retrieves **your own account** information: profile, credit balance and linked
        game accounts.

        **Access**: authentication required. The endpoint always returns the account
        associated with your API key.
      operationId: getUser
      responses:
        '200':
          description: User data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: User - Informations - Get user datas
                      endpoint:
                        type: string
                        example: /user
                      code:
                        type: integer
                        example: 200
                      data:
                        $ref: '#/components/schemas/UserData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/user/{id_user}/servers':
    get:
      tags:
        - User
      summary: List your MyBoxes and servers
      description: |
        Retrieves **your own servers**: the MyBoxes you can access (`servers_groups`, keyed
        by ID) and the flat list of your servers (`servers`), owned or accessible as a
        sub-user.

        **Access**: authentication required. You can only list your own servers (`id_user`
        must match your account).
      operationId: getUserServers
      parameters:
        - name: id_user
          in: path
          required: true
          description: Your user ID.
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: User servers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: User - Servers - Get user servers
                      endpoint:
                        type: string
                        example: /user/12345/servers
                      code:
                        type: integer
                        example: 200
                      data:
                        $ref: '#/components/schemas/UserServersData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/mybox/{id_mybox}':
    get:
      tags:
        - MyBox
      summary: Get a MyBox's information
      description: |
        Retrieves a MyBox's information: status, plan and resources, and the list of its
        servers.

        **Access**: MyBox owner, or sub-user with the `view` permission.
      operationId: getMyBox
      parameters:
        - name: id_mybox
          in: path
          required: true
          description: MyBox ID.
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: MyBox data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: MyBox - Actions - Get datas
                      endpoint:
                        type: string
                        example: /mybox/12345
                      code:
                        type: integer
                        example: 200
                      data:
                        $ref: '#/components/schemas/MyBoxData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/mybox/{id_mybox}/server':
    post:
      tags:
        - MyBox
      summary: Create a server
      description: |
        Creates a new server inside a MyBox and starts its installation. The server
        shares the MyBox resources (CPU / RAM / disk).

        Specify the server type via `id_egg` **or** `id_egg_experimental` (one of the
        two is required). On a still-empty MyBox, if `cpu` and `ram` are omitted, all of
        the plan's resources are allocated to the server — unless `force_settings` is set.

        Valid `id` values are obtained via `GET /server/catalog/locations` (the
        `location` field) and `GET /server/catalog/eggs` (the `id_egg` field).

        **Access**: MyBox owner, or sub-user with the `server_create` permission.
      operationId: createMyBoxServer
      parameters:
        - name: id_mybox
          in: path
          required: true
          description: MyBox ID.
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - location
              properties:
                location:
                  type: integer
                  description: ID of the location (datacenter) where the server will be hosted.
                  example: 1
                id_egg:
                  type: integer
                  description: Server type (egg) ID. Required if `id_egg_experimental` is absent.
                  example: 1
                id_egg_experimental:
                  type: integer
                  description: Experimental egg ID. Required if `id_egg` is absent.
                  example: 0
                cpu:
                  type: integer
                  description: CPU cores to allocate. Optional for the first server of an empty MyBox.
                  example: 2
                ram:
                  type: integer
                  description: 'RAM to allocate, in GB. Optional for the first server of an empty MyBox.'
                  example: 4
                name:
                  type: string
                  maxLength: 100
                  description: Server name.
                  example: Mon serveur Survie
                required_fields:
                  type: array
                  description: Values for the fields required by the chosen egg.
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        example: SERVER_VERSION
                      value:
                        type: string
                        example: '1.21'
                force_settings:
                  type: integer
                  description: Prevents auto-allocating the whole plan to the first server.
                  example: 0
      responses:
        '200':
          description: Server created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: MyBox - Server - Create a server
                      endpoint:
                        type: string
                        example: /mybox/12345/server
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          id_mybox:
                            type: integer
                            description: MyBox ID.
                            example: 12345
                          id_server:
                            type: integer
                            description: ID of the created server.
                            example: 67890
                          ip:
                            type: string
                            description: 'Server connection address (IP:port).'
                            example: '51.83.42.10:25565'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
    patch:
      tags:
        - MyBox
      summary: Edit a server's resources
      description: |
        Updates the CPU and RAM allocated to a server, within the limit of the MyBox
        plan's resources.

        The server must be **powered off** to be resized.

        **Access**: MyBox owner, or sub-user with the `server_update` permission.
      operationId: updateMyBoxServerResources
      parameters:
        - name: id_mybox
          in: path
          required: true
          description: MyBox ID.
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id_server
                - cpu
                - ram
              properties:
                id_server:
                  type: integer
                  description: ID of the server to update.
                  example: 67890
                cpu:
                  type: integer
                  description: CPU cores to allocate.
                  example: 2
                ram:
                  type: integer
                  description: 'RAM to allocate, in GB.'
                  example: 4
      responses:
        '200':
          description: Server resources updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: MyBox - Server - Edit server resources
                      endpoint:
                        type: string
                        example: /mybox/12345/server
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/mybox/{id_mybox}/server/{id_server}':
    delete:
      tags:
        - MyBox
      summary: Delete a server
      description: |
        Permanently deletes a server from the MyBox. This action is **irreversible**:
        the server and its data are destroyed, and its resources are freed in the MyBox.

        **Access**: MyBox owner, or sub-user with the `server_delete` permission.
      operationId: deleteMyBoxServer
      parameters:
        - name: id_mybox
          in: path
          required: true
          description: MyBox ID.
          schema:
            type: integer
            example: 12345
        - name: id_server
          in: path
          required: true
          description: ID of the server to delete.
          schema:
            type: integer
            example: 67890
      responses:
        '200':
          description: Server deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: MyBox - Server - Delete a server
                      endpoint:
                        type: string
                        example: /mybox/12345/server/67890
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/mybox/{id_mybox}/server/enable':
    patch:
      tags:
        - MyBox
      summary: Enable a server
      description: |
        Re-enables a previously disabled server. The server reclaims its share of the
        MyBox resources — the plan must therefore have enough CPU / RAM available.

        **Access**: MyBox owner, or sub-user with the `server_status` permission.
      operationId: enableMyBoxServer
      parameters:
        - name: id_mybox
          in: path
          required: true
          description: MyBox ID.
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id_server
              properties:
                id_server:
                  type: integer
                  description: ID of the server to enable.
                  example: 67890
      responses:
        '200':
          description: Server enabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: MyBox - Server - Enable a server
                      endpoint:
                        type: string
                        example: /mybox/12345/server/enable
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/mybox/{id_mybox}/server/disable':
    patch:
      tags:
        - MyBox
      summary: Disable a server
      description: |
        Disables a server without deleting it: it is suspended and frees its share of
        the MyBox resources, which become available again to the other servers. Can be
        re-enabled at any time.

        **Access**: MyBox owner, or sub-user with the `server_status` permission.
      operationId: disableMyBoxServer
      parameters:
        - name: id_mybox
          in: path
          required: true
          description: MyBox ID.
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id_server
              properties:
                id_server:
                  type: integer
                  description: ID of the server to disable.
                  example: 67890
      responses:
        '200':
          description: Server disabled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: MyBox - Server - Disable a server
                      endpoint:
                        type: string
                        example: /mybox/12345/server/disable
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /server/catalog/locations:
    get:
      tags:
        - Server
      summary: List available locations
      description: |
        Lists the locations where a server can be created. Use the returned
        `id` as the `location` field when creating a server.

        **Access**: any authenticated customer.
      operationId: getServerCatalogLocations
      responses:
        '200':
          description: Locations retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Catalog - Available locations
                      endpoint:
                        type: string
                        example: /server/catalog/locations
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          locations:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  description: Location identifier (pass as `location`).
                                  example: 1
                                city:
                                  type: string
                                  description: Datacenter city.
                                  example: Toulouse
                                country:
                                  type: string
                                  description: Country.
                                  example: France
                                country_iso:
                                  type: string
                                  description: ISO 3166-1 alpha-2 country code.
                                  example: FR
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /server/catalog/eggs:
    get:
      tags:
        - Server
      summary: List available server types (eggs)
      description: |
        Lists the server types available for creation (games, databases, tools,
        runtimes…). Use the returned `id` as the `id_egg` field when creating.

        `required_fields` lists the fields the egg requires: pass each `key` in the
        create body's `required_fields` array.

        **Access**: any authenticated customer.
      operationId: getServerCatalogEggs
      responses:
        '200':
          description: Server types retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Catalog - Available eggs
                      endpoint:
                        type: string
                        example: /server/catalog/eggs
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          eggs:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: integer
                                  description: Server type identifier (pass as `id_egg`).
                                  example: 1
                                name:
                                  type: string
                                  description: Server type name.
                                  example: Minecraft
                                required_fields:
                                  type: array
                                  description: 'Fields the egg requires, to provide in `required_fields` at creation.'
                                  items:
                                    type: object
                                    properties:
                                      key:
                                        type: string
                                        example: STEAM_USER
                                      label:
                                        type: string
                                        example: '[Host] Steam Username'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}':
    get:
      tags:
        - Server
      summary: Get server information
      description: |
        Retrieves the full information of a server.

        **Access**: server owner, or sub-user with the `view` permission. Some response
        blocks require an additional permission: `ports` (`ports_view`), `sftp` (`sftp`),
        `livemap` (`livemap`) — without it, the block is absent.
      operationId: getServerDatas
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      responses:
        '200':
          description: Server data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Actions - Get datas
                      endpoint:
                        type: string
                        example: /server/67890
                      code:
                        type: integer
                        example: 200
                      data:
                        $ref: '#/components/schemas/ServerFullData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/live':
    get:
      tags:
        - Server
      summary: Get a server's real-time statistics
      description: |
        Returns the real-time state and statistics of a server. For an online server, the
        connected players and game information are also returned **if the game is
        supported** (some games do not allow retrieving this data).

        **Access**: server owner, or sub-user with the `view` permission.
      operationId: getServerLiveData
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      responses:
        '200':
          description: Real-time statistics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Actions - Get live datas
                      endpoint:
                        type: string
                        example: /server/67890/live
                      code:
                        type: integer
                        example: 200
                      data:
                        $ref: '#/components/schemas/ServerLiveData'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/live/light':
    get:
      tags:
        - Server
      summary: Get a server's complementary live data (light version)
      description: |
        Light version of `GET /server/{id_server}/live`, meant to complement the
        websocket connection. Game information (connected players, version…) is only
        available **if the game is supported** (some games do not allow retrieving this
        data).

        **Access**: server owner, or sub-user with the `view` permission.
      operationId: getServerLiveLight
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      responses:
        '200':
          description: Light live data retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Actions - Get live datas (light)
                      endpoint:
                        type: string
                        example: /server/67890/live/light
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          status:
                            type:
                              - string
                              - 'null'
                            description: Infrastructure-side status (e.g. `installing`); `null` if no particular state
                            example: null
                          cpu:
                            type: object
                            description: CPU limits (in hundredths of a core — 100 = 1 core). Instantaneous usage comes from the websocket.
                            properties:
                              dedicated:
                                type: integer
                                description: CPU dedicated to the server
                                example: 200
                              flexcore:
                                type: integer
                                description: Additional shared CPU (FlexCore) provided by the offer
                                example: 100
                              limit:
                                type: integer
                                description: Total available CPU (dedicated + FlexCore)
                                example: 300
                          disk:
                            type: object
                            description: Disk limit (MB)
                            properties:
                              limit:
                                type: integer
                                description: Disk limit (MB)
                                example: 10000
                          memory:
                            type: object
                            description: Memory limit (MB)
                            properties:
                              limit:
                                type: integer
                                description: Memory limit (MB)
                                example: 8000
                          players:
                            type: object
                            description: Connected players (present only if the server is queryable and returns players)
                            properties:
                              current:
                                type: integer
                                description: Number of connected players
                                example: 12
                              limit:
                                type: integer
                                description: Maximum number of slots
                                example: 100
                              list:
                                type: array
                                description: List of connected player names (capped at 300)
                                items:
                                  type: string
                                example:
                                  - Notch
                                  - jeb_
                          version:
                            type: string
                            description: 'Server version (present if queryable, depending on the game)'
                            example: 1.21.1
                          motd:
                            type: string
                            description: 'Message of the day, stripped of color codes (present if queryable, depending on the game)'
                            example: Bienvenue sur le serveur !
                          hostname:
                            type: string
                            description: 'Hostname announced by the server (present if queryable, depending on the game)'
                            example: play.example.com
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/console/logs':
    get:
      tags:
        - Server
      summary: Get console logs
      description: |
        Returns the **last 100 lines** of the server console, with their raw **ANSI color codes**.

        **Access**: server owner, or sub-user with the `view` permission.
      operationId: getServerConsoleLogs
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID.
          schema:
            type: integer
            example: 67890
      responses:
        '200':
          description: Logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Console - Get recent console logs
                      endpoint:
                        type: string
                        example: /server/67890/console/logs
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          logs:
                            type: array
                            description: The last 100 console lines (raw ANSI color codes preserved).
                            items:
                              type: string
                            example:
                              - '[12:00:03 INFO]: Done (5.123s)! For help, type "help"'
                              - '[12:00:14 INFO]: Steve a rejoint la partie'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/poweraction':
    put:
      tags:
        - Server
      summary: Send a power action
      description: |
        Start, restart, stop or force-stop a server. The `restart10` / `stop10` variants
        broadcast a 10-second countdown before acting (the request then stays blocked
        for ~10 s).

        **Access**: server owner, or sub-user with the permission matching the action
        (`poweraction_start`, `poweraction_restart`, `poweraction_stop`,
        `poweraction_kill`).
      operationId: sendServerPowerAction
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - poweraction
              properties:
                poweraction:
                  type: string
                  enum:
                    - start
                    - restart
                    - restart10
                    - stop
                    - stop10
                    - kill
                  description: |
                    Action to run:
                    - `start`: start the server
                    - `restart`: restart immediately
                    - `restart10`: restart with a 10 s countdown in the console
                    - `stop`: stop immediately
                    - `stop10`: stop with a 10 s countdown in the console
                    - `kill`: force-kill the process
                  example: start
      responses:
        '200':
          description: Action submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Actions - Send power action
                      endpoint:
                        type: string
                        example: /server/67890/poweraction
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command':
    put:
      tags:
        - Server
      summary: Send a command to the server
      description: |
        Sends a command to the server.

        **Access**: server owner, or sub-user with the `command` permission.

        The command only runs if the server is online. On a stopped server, the
        API still responds `200` but the command is ignored.
      operationId: sendServerCommand
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - command
              properties:
                command:
                  type: string
                  description: Command to send to the server
                  example: say Bonjour à tous !
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Actions - Send command
                      endpoint:
                        type: string
                        example: /server/67890/command
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command/minecraft/kick':
    put:
      tags:
        - Server
      summary: Kick a player
      description: |
        Kicks a player from the server (Minecraft servers; no effect if the server is
        offline).

        **Access**: server owner, or sub-user with the `players_kick` permission.
      operationId: kickServerPlayer
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - player
              properties:
                player:
                  type: string
                  description: Player name
                  example: Notch
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command/minecraft/ban':
    put:
      tags:
        - Server
      summary: Ban a player
      description: |
        Bans a player from the server (Minecraft servers; no effect if the server is
        offline).

        **Access**: server owner, or sub-user with the `players_ban` permission.
      operationId: banServerPlayer
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - player
              properties:
                player:
                  type: string
                  description: Player name
                  example: Notch
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command/minecraft/unban':
    put:
      tags:
        - Server
      summary: Unban a player
      description: |
        Lifts a player's ban (Minecraft servers; no effect if the server is offline).

        **Access**: server owner, or sub-user with the `players_ban` permission.
      operationId: unbanServerPlayer
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - player
              properties:
                player:
                  type: string
                  description: Player name
                  example: Notch
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command/minecraft/op/add':
    put:
      tags:
        - Server
      summary: Grant operator status (op)
      description: |
        Grants operator status to a player (Minecraft servers; no effect if the server
        is offline).

        **Access**: server owner, or sub-user with the `players_operator` permission.
      operationId: addServerOperator
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - player
              properties:
                player:
                  type: string
                  description: Player name
                  example: Notch
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command/minecraft/op/remove':
    put:
      tags:
        - Server
      summary: Remove operator status (deop)
      description: |
        Removes a player's operator status (Minecraft servers; no effect if the server
        is offline).

        **Access**: server owner, or sub-user with the `players_operator` permission.
      operationId: removeServerOperator
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - player
              properties:
                player:
                  type: string
                  description: Player name
                  example: Notch
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command/minecraft/whitelist/add':
    put:
      tags:
        - Server
      summary: Add a player to the whitelist
      description: |
        Adds a player to the server whitelist (Minecraft servers; no effect if the
        server is offline).

        **Access**: server owner, or sub-user with the `players_whitelist` permission.
      operationId: addServerWhitelistPlayer
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - player
              properties:
                player:
                  type: string
                  description: Player name
                  example: Notch
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/command/minecraft/whitelist/remove':
    put:
      tags:
        - Server
      summary: Remove a player from the whitelist
      description: |
        Removes a player from the server whitelist (Minecraft servers; no effect if the
        server is offline).

        **Access**: server owner, or sub-user with the `players_whitelist` permission.
      operationId: removeServerWhitelistPlayer
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - player
              properties:
                player:
                  type: string
                  description: Player name
                  example: Notch
      responses:
        '200':
          description: Command submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/name':
    patch:
      tags:
        - Server
      summary: Rename a server
      description: |
        Changes the server's display name. The change is applied
        **immediately**, without a restart.

        **Access**: server owner, or sub-user with the `server_name` permission.
      operationId: updateServerName
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 100
                  description: New server name.
                  example: Mon serveur Survie
      responses:
        '200':
          description: Server name updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Settings - Edit server name
                      endpoint:
                        type: string
                        example: /server/67890/name
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/properties':
    get:
      tags:
        - Server
      summary: Read a server's settings (server.properties)
      description: |
        Returns the server's configuration settings.

        **Access**: server owner, or sub-user with the `settings_view` permission.
      operationId: getServerProperties
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      responses:
        '200':
          description: Server settings retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Settings - Get server settings (server.properties)
                      endpoint:
                        type: string
                        example: /server/67890/properties
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          properties_type:
                            type: string
                            description: Type of settings returned
                            example: server_properties
                          properties:
                            type: object
                            description: Server settings dictionary (`key → value`).
                            additionalProperties: true
              examples:
                server_properties:
                  summary: Example response
                  value:
                    api:
                      description: Server - Settings - Get server settings (server.properties)
                      endpoint: /server/67890/properties
                      code: 200
                      data:
                        properties_type: server_properties
                        properties:
                          max-players: '20'
                          difficulty: easy
                          pvp: 'true'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      tags:
        - Server
      summary: Edit a server setting (server.properties)
      description: |
        Edits a **single** server setting; the setting must already exist.
        Applied on the next start.

        **Access**: server owner, or sub-user with the `settings_edit` permission. Two
        families of settings require an additional permission: `enable-rcon`/`rcon.*` →
        `command`; `op-permission-level` → `players_operator`.
      operationId: editServerProperties
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - property
              properties:
                property:
                  type: string
                  description: Name of the setting to edit (a `server.properties` key).
                  example: max-players
                value:
                  type: string
                  description: New value of the setting. An empty value is accepted (clears the setting).
                  example: '30'
      responses:
        '200':
          description: Setting edited successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Settings - Edit server settings (server.properties)
                      endpoint:
                        type: string
                        example: /server/67890/properties
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/poweraction/messages':
    patch:
      tags:
        - Server
      summary: Edit power action messages
      description: |
        Sets the messages broadcast in the console during the 10-second countdown of the
        `restart10` and `stop10` actions. The `$x` marker is replaced by the number of
        remaining seconds. Both `restart` and `stop` are required (empty value clears the
        message).

        **Access**: server owner, or sub-user with the `settings_edit` permission.
      operationId: updateServerPoweractionMessages
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - restart
                - stop
              properties:
                restart:
                  type: string
                  description: Countdown message before restart (`$x` = seconds remaining)
                  example: Redémarrage du serveur dans $x secondes...
                stop:
                  type: string
                  description: Countdown message before stop (`$x` = seconds remaining)
                  example: Arrêt du serveur dans $x secondes...
      responses:
        '200':
          description: Messages updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Settings - Edit power actions messages
                      endpoint:
                        type: string
                        example: /server/67890/poweraction/messages
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/icon':
    patch:
      tags:
        - Server
      summary: Edit a server's icon
      description: |
        Sets the server's icon (shown notably in the multiplayer server list for
        Minecraft servers).

        **Access**: server owner, or sub-user with the `settings_edit` permission.
      operationId: updateServerIcon
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  description: |
                    Image as a base64 data URI. Accepted types: `jpg`, `jpeg`, `png`, `bmp`.
                  example: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABA...'
      responses:
        '200':
          description: Icon updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Settings - Edit server icon
                      endpoint:
                        type: string
                        example: /server/67890/icon
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/user/{id_user}/snapshot':
    post:
      tags:
        - Snapshots
      summary: Create a snapshot
      description: |
        Creates a snapshot of one of your servers: a full backup that you can restore
        later, on this server or another one.

        Processing is **asynchronous**: the response returns a `job_id` identifying the
        job started in the background.

        **Access**: the account holder (the key must match `id_user`).
      operationId: createSnapshot
      parameters:
        - name: id_user
          in: path
          required: true
          description: User ID.
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id_server
                - name
              properties:
                id_server:
                  type: integer
                  description: ID of the server to back up.
                  example: 67890
                name:
                  type: string
                  maxLength: 64
                  description: Snapshot name.
                  example: Avant mise à jour
      responses:
        '200':
          description: Snapshot queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: User - Snapshots - Create snapshot
                      endpoint:
                        type: string
                        example: /user/12345/snapshot
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          job_id:
                            type: integer
                            description: Processing job ID (progress tracking).
                            example: 4567
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: An active paid offer is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                api:
                  description: ''
                  endpoint: ''
                  code: 402
                  error: API_ARCHIVE_NEED_PAID_OFFER
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: 'Snapshot limit reached, or a job is already running on this server'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                api:
                  description: ''
                  endpoint: ''
                  code: 409
                  error: API_SNAPSHOT_ALREADY_PROCESSING
        '429':
          $ref: '#/components/responses/RateLimited'
    put:
      tags:
        - Snapshots
      summary: Restore a snapshot
      description: |
        Restores a snapshot onto a target server: the server's current content is replaced
        with the snapshot's.

        Processing is **asynchronous**: the response returns a `job_id` identifying the
        job started in the background.

        **Access**: the account holder (the key must match `id_user`).
      operationId: restoreSnapshot
      parameters:
        - name: id_user
          in: path
          required: true
          description: User ID.
          schema:
            type: integer
            example: 12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id_snapshot
                - id_server
              properties:
                id_snapshot:
                  type: integer
                  description: ID of the snapshot to restore.
                  example: 321
                id_server:
                  type: integer
                  description: ID of the target server to restore onto.
                  example: 67890
      responses:
        '200':
          description: Restore queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: User - Snapshots - Restore snapshot
                      endpoint:
                        type: string
                        example: /user/12345/snapshot
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          job_id:
                            type: integer
                            description: Processing job ID (progress tracking).
                            example: 4568
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: An active paid offer is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                api:
                  description: ''
                  endpoint: ''
                  code: 402
                  error: API_ARCHIVE_NEED_PAID_OFFER
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: A job is already running on the target server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                api:
                  description: ''
                  endpoint: ''
                  code: 409
                  error: API_SNAPSHOT_ALREADY_PROCESSING
        '429':
          $ref: '#/components/responses/RateLimited'
  '/user/{id_user}/snapshot/{id_snapshot}':
    delete:
      tags:
        - Snapshots
      summary: Delete a snapshot
      description: |
        Permanently deletes a snapshot.

        Processing is **asynchronous**: the response returns a `job_id` identifying the
        job started in the background.

        **Access**: the account holder (the key must match `id_user`).
      operationId: deleteSnapshot
      parameters:
        - name: id_user
          in: path
          required: true
          description: User ID.
          schema:
            type: integer
            example: 12345
        - name: id_snapshot
          in: path
          required: true
          description: Snapshot ID.
          schema:
            type: integer
            example: 321
      responses:
        '200':
          description: Deletion queued for processing
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: User - Snapshots - Delete snapshot
                      endpoint:
                        type: string
                        example: /user/12345/snapshot/321
                      code:
                        type: integer
                        example: 200
                      data:
                        type: object
                        properties:
                          job_id:
                            type: integer
                            description: Processing job ID (progress tracking).
                            example: 4569
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  '/server/{id_server}/backup':
    put:
      tags:
        - Server
      summary: Restore a backup
      description: |
        Starts the **restore** of a backup onto a server. The operation is **asynchronous**:
        the **200** response only acknowledges that the request was accepted (the server is
        suspended for the duration of the restore). One restore at a time per server.

        **Access**: server owner, or sub-user with the `saves_restore` permission. The owner
        is notified if the action comes from a sub-user.

        **Maintenance**: if the backup system is under maintenance, the API returns **503**
        (`API_SMART_BACKUP_MAINTENANCE`).
      operationId: restoreServerBackup
      parameters:
        - name: id_server
          in: path
          required: true
          description: Server ID
          schema:
            type: integer
            example: 67890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id_backup
              properties:
                id_backup:
                  type: integer
                  description: ID of the backup to restore (among the server's backups)
                  example: 123
      responses:
        '200':
          description: Restore request accepted (asynchronous processing)
          content:
            application/json:
              schema:
                type: object
                properties:
                  api:
                    type: object
                    properties:
                      description:
                        type: string
                        example: Server - Backups - Restore backup
                      endpoint:
                        type: string
                        example: /server/67890/backup
                      code:
                        type: integer
                        example: 200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: A restore is already running on this server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                api:
                  description: ''
                  endpoint: ''
                  code: 409
                  error: API_BACKUP_ALREADY_IN_PROGRESS
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          description: Backup system under maintenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                api:
                  description: ''
                  endpoint: ''
                  code: 503
                  error: API_SMART_BACKUP_MAINTENANCE
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Base64-encoded API key.
  schemas:
    UserData:
      type: object
      properties:
        user:
          type: object
          properties:
            datas:
              type: object
              description: Account information.
              properties:
                id:
                  type: integer
                  example: 12345
                pseudo:
                  type: string
                  example: Steve
                mail:
                  type: string
                  example: steve@example.com
                mail_validated:
                  type: integer
                  description: 1 if the email is verified.
                  enum:
                    - 0
                    - 1
                  example: 1
                money:
                  type: number
                  description: Credit balance.
                  example: 12.5
                lang:
                  type: string
                  enum:
                    - fr
                    - en
                  example: fr
                register_date:
                  type: string
                  description: 'Registration date (`Y-m-d H:i:s`).'
                  example: '2024-01-15 18:42:10'
            linked_account:
              type: object
              description: Linked game accounts (key present only if the account is linked).
              properties:
                minecraft:
                  type: object
                  properties:
                    uuid:
                      type: string
                      example: 853c80ef3c3749fdaa49938b674adae6
                    name:
                      type: string
                      example: Steve
                discord:
                  type: object
                  properties:
                    id:
                      type: string
                      example: '123456789012345678'
                    name:
                      type: string
                      example: steve#0001
    ApiError:
      type: object
      properties:
        api:
          type: object
          properties:
            description:
              type: string
              description: Description of the called endpoint
            endpoint:
              type: string
              description: Path of the called endpoint
            code:
              type: integer
              description: HTTP response code
            error:
              type: string
              description: API error code
              example: API_MISSING_REQUIRED_FIELDS
            data:
              type: object
              description: 'Optional contextual data depending on the error (e.g. `id_mybox` on API_SERVER_EXPIRED, `reason` on API_SERVER_SUSPENDED).'
    UserServersData:
      type: object
      properties:
        servers_groups:
          type: object
          description: |
            MyBoxes the user can access, **keyed by MyBox ID**. Each value:
          additionalProperties:
            type: object
            properties:
              id:
                type: integer
                example: 12345
              name:
                type: string
                example: Ma MyBox
              owner:
                type: integer
                description: '1 if owner, 0 if sub-user.'
                enum:
                  - 0
                  - 1
                example: 1
              offer:
                type: string
                description: Plan name.
                example: MyBox 8
              resources:
                type: object
                description: 'Plan resources (cpu in cores, ram and disk in GB).'
                properties:
                  cpu:
                    type: integer
                    example: 4
                  ram:
                    type: integer
                    example: 8
                  disk:
                    type: integer
                    example: 50
              tend:
                type: string
                description: 'Expiration date (`Y-m-d H:i:s`).'
                example: '2026-09-01 00:00:00'
              tend_days:
                type: integer
                description: Days left before expiration (0 if expired).
                example: 74
              is_free:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              is_trial:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              is_pro:
                type: integer
                description: 1 if MyBox Pro (dedicated).
                enum:
                  - 0
                  - 1
                example: 0
              is_expired:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              is_suspended:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
        servers:
          type: array
          description: User's servers (owned + accessible as a sub-user).
          items:
            type: object
            properties:
              id:
                type: integer
                example: 67890
              name:
                type: string
                example: Survie 1.21
              id_mybox:
                type: integer
                description: Parent MyBox.
                example: 12345
              id_egg:
                type: integer
                description: Game type (egg).
                example: 1
              egg_name:
                type: string
                example: Minecraft Java
              egg_icon:
                type: string
                example: 'https://cdn.minestrator.com/eggs/minecraft.png'
              egg_uuid:
                type: string
                example: a1b2c3d4-0000-0000-0000-000000000000
              hashsupport:
                type: string
                description: Server support identifier.
                example: AB12CD
              ip:
                type: string
                example: '94.231.1.10:25565'
              port:
                type: integer
                example: 25565
              dns:
                type:
                  - string
                  - 'null'
                description: 'Full subdomain, if configured.'
                example: play.mondomaine.com
              tstart:
                type: string
                example: '2024-06-01 12:00:00'
              tend:
                type: string
                example: '2026-09-01 00:00:00'
              is_bedrock:
                type: integer
                description: 1 if Minecraft Bedrock server.
                enum:
                  - 0
                  - 1
                example: 0
              is_free:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              is_expired:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              is_suspended:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              is_disabled:
                type: integer
                description: 1 if the server is disabled within its MyBox.
                enum:
                  - 0
                  - 1
                example: 0
              hibernation:
                type: integer
                description: 1 if the server is hibernating.
                enum:
                  - 0
                  - 1
                example: 0
              owner:
                type: integer
                description: '1 if server owner, 0 if sub-user.'
                enum:
                  - 0
                  - 1
                example: 1
    MyBoxData:
      type: object
      properties:
        mybox:
          type: object
          description: MyBox information.
          properties:
            id:
              type: integer
              example: 12345
            name:
              type: string
              example: Ma MyBox
            hashsupport:
              type: string
              description: MyBox support identifier.
              example: WQ6KX
            tstart:
              type: string
              example: '2024-06-01 12:00:00'
            tend:
              type: string
              description: 'Expiration date (`Y-m-d H:i:s`).'
              example: '2026-09-01 00:00:00'
            tend_days:
              type: integer
              description: Days left before expiration (0 if expired).
              example: 74
            deletion_days:
              type: integer
              description: Days left before deletion (present only if expired).
              example: 14
            owner:
              type: integer
              description: '1 if owner, 0 if sub-user.'
              enum:
                - 0
                - 1
              example: 1
            subscription:
              type: integer
              description: 1 if an auto-renewal subscription is active.
              enum:
                - 0
                - 1
              example: 1
            is_free:
              type: integer
              enum:
                - 0
                - 1
              example: 0
            is_trial:
              type: integer
              enum:
                - 0
                - 1
              example: 0
            is_pro:
              type: integer
              description: 1 if MyBox Pro (dedicated).
              enum:
                - 0
                - 1
              example: 0
            is_expired:
              type: integer
              enum:
                - 0
                - 1
              example: 0
            is_suspended:
              type: integer
              enum:
                - 0
                - 1
              example: 0
            cpu_remaining:
              type: number
              description: CPU cores still available to allocate.
              example: 2
            ram_remaining:
              type: number
              description: RAM (GB) still available to allocate.
              example: 4
        offer:
          type: object
          description: MyBox plan (total resources).
          properties:
            id:
              type: integer
              example: 5
            name:
              type: string
              example: MyBox 8
            price:
              type: number
              example: 7.99
            cpu:
              type: integer
              description: CPU cores.
              example: 4
            ram:
              type: integer
              description: RAM (GB).
              example: 8
            disk:
              type: integer
              description: Disk included in the plan (GB).
              example: 50
            disk_total:
              type: integer
              description: 'Total disk (plan + add-ons), in GB.'
              example: 70
            dbsize:
              type: integer
              description: Max size per database (GB).
              example: 10
            dbnb:
              type: integer
              description: Number of allowed databases.
              example: 2
            pods:
              type: integer
              description: Number of dedicated IPs available on the plan.
              example: 1
        servers:
          type: array
          description: MyBox servers.
          items:
            type: object
            properties:
              id:
                type: integer
                example: 67890
              name:
                type: string
                example: Survie 1.21
              egg:
                type: integer
                description: Game type (egg).
                example: 1
              egg_name:
                type: string
                example: Minecraft Java
              egg_icon:
                type: string
                example: 'https://cdn.minestrator.com/eggs/minecraft.png'
              ip:
                type: string
                example: '94.231.1.10:25565'
              cpu:
                type: integer
                description: Allocated CPU cores.
                example: 2
              ram:
                type: integer
                description: Allocated RAM (GB).
                example: 4
              disabled:
                type: integer
                description: 1 if the server is disabled.
                enum:
                  - 0
                  - 1
                example: 0
              is_expired:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              is_suspended:
                type: integer
                enum:
                  - 0
                  - 1
                example: 0
              location:
                type: string
                description: Datacenter location.
                example: France
              country:
                type: string
                example: France
              country_iso:
                type: string
                example: fr
    ServerDatas:
      type: object
      description: Server data
      properties:
        id:
          type: integer
          example: 67890
        uuid:
          type: string
          description: Full server UUID
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
        id_daemon:
          type: integer
          description: ID of the physical node hosting the server
        id_mybox:
          type: integer
          description: Parent MyBox ID
          example: 12345
        offre:
          type: string
          description: Offer name
        is_free:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if free server
        hashsupport:
          type: string
          description: Short identifier to provide to support
          example: AB3CD
        tstart:
          type: string
          format: date-time
          description: Start of the current period
        tend:
          type: string
          format: date-time
          description: End of the current period (expiration)
        dedicated_ip:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if the server has a dedicated IP
        ip:
          type: string
          description: Server connection IP
          example: 94.231.203.18
        port:
          type: integer
          description: Main server port
          example: 25565
        dns:
          type:
            - string
            - 'null'
          description: Custom DNS subdomain (null if not configured)
          example: monserveur.myjeux.fr
        owner:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if the authenticated user is the owner
        name:
          type: string
          description: Server name
          example: Mon serveur Minecraft
        id_groupe:
          type:
            - integer
            - 'null'
          description: Organization group within the MyBox
        ordre:
          type: integer
          description: Display order within the MyBox
        permissions:
          type: array
          description: Sub-user permissions on this server (empty if owner)
          items:
            type: string
        hibernation:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if the server is hibernating
    ServerOffer:
      type: object
      description: Parent MyBox offer
      properties:
        name:
          type: string
          example: MyBox Diamond
        is_pro:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if MyBox Pro (dedicated server)
        is_trial:
          type: integer
          description: 1 if trial MyBox
          example: 0
        is_free:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if free MyBox
        cpu:
          type: integer
          description: Offer CPU (cores)
        ram:
          type: integer
          description: Offer RAM (GB)
        disk:
          type: integer
          description: Offer disk (GB)
        auto_shutdown_seconds:
          type: integer
          description: 'Only present for free servers: automatic shutdown delay in seconds. 14400 (4 h) by default, 86400 (24 h) if the account also has an active paid MyBox.'
          example: 14400
    ServerEgg:
      type: object
      description: Server game/egg
      properties:
        id:
          type: integer
          example: 5
        type:
          type: integer
          description: Egg type ID
        name:
          type: string
          example: Minecraft Vanilla
        icon:
          type: string
          example: minecraft.png
        uuid:
          type: string
          description: Egg UUID
    ServerSettings:
      type: object
      description: Server configuration
      properties:
        is_bedrock:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if Minecraft Bedrock Edition server
        is_bungeecord:
          type: integer
          enum:
            - 0
            - 1
          description: 1 if BungeeCord/proxy server
        java_memory:
          type: integer
          description: Allocated Java memory (MB)
        image:
          type: string
          description: Docker image used
          example: 'ghcr.io/pterodactyl/yolks:java_21'
        id_java_version:
          type:
            - integer
            - 'null'
          description: Java version ID (absent if the image is not recognized)
        startup:
          type: string
          description: Startup command
        startup_file:
          type:
            - string
            - 'null'
          description: Startup JAR file (if applicable)
          example: server.jar
        poweraction_message:
          type: object
          description: Custom messages shown during power actions with a countdown
          properties:
            restart:
              type: string
              example: Server restarting in $x seconds...
            stop:
              type: string
              example: Server stopping in $x seconds...
    ServerFullData:
      type: object
      properties:
        server:
          $ref: '#/components/schemas/ServerDatas'
        websocket:
          type: object
          description: Websocket connection for the real-time console (empty fields if the server is hibernating)
          properties:
            url:
              type: string
              example: 'wss://node1.mystrator.com:8080'
            token:
              type: string
              example: eyJhbGciOiJI...
        mybox:
          type: object
          description: Summary info of the parent MyBox
          properties:
            name:
              type: string
              example: Ma MyBox
            hashsupport:
              type: string
              description: Short MyBox identifier to provide to support
              example: WQ6KX
            refund_requested_at:
              type: string
              format: date-time
              description: Date of the last refund request (absent if none)
            reduction:
              type: integer
              description: Recurring promo discount percentage (absent if none)
            to_review:
              type: integer
              enum:
                - 0
                - 1
              description: 1 if the user can leave a review for this MyBox
            resources:
              type: object
              properties:
                cpu:
                  type: integer
                  description: CPU allocated to this server (cores)
                ram:
                  type: integer
                  description: RAM allocated to this server (GB)
                disk:
                  type: integer
                  description: Total MyBox disk (GB) — offer + subscribed options
        offer:
          $ref: '#/components/schemas/ServerOffer'
        egg:
          $ref: '#/components/schemas/ServerEgg'
        settings:
          $ref: '#/components/schemas/ServerSettings'
        options:
          type: array
          description: Options subscribed for this server
          items:
            type: object
            properties:
              name:
                type: string
                example: RAM +2 Go
              price:
                type: string
                example: '3.99'
        history:
          type: array
          description: Latest server actions (max 20)
          items:
            type: object
            properties:
              date:
                type: string
                format: date-time
              ip:
                type:
                  - string
                  - 'null'
                description: IP behind the action (null if staff/infrastructure action)
              is_staff:
                type: boolean
                description: true if the action was performed by staff or infrastructure
              action:
                type: string
                description: 'Action name (e.g. power.start, maintenance.reinstall)'
                example: power.start
        ports:
          type: array
          description: Additional allocated ports — present if owner or `ports_view` permission
          items:
            type: object
            properties:
              port:
                type: integer
                example: 25566
              ip:
                type: string
                example: 94.231.203.18
              description:
                type: string
                description: Free-text note associated with the port
                example: Dynmap
        sftp:
          type: object
          description: SFTP credentials — present if owner or `sftp` permission
          properties:
            protocol:
              type: string
              example: sftp
            host:
              type: string
              example: node1.mystrator.com
            port:
              type: integer
              example: 2022
            user:
              type: string
              example: player123.abc12345
            password:
              type: string
        livemap:
          type: object
          description: Livemap information — present if owner or `livemap` permission
          properties:
            option:
              type: integer
              enum:
                - 0
                - 1
              description: 1 if the livemap option is subscribed
            enabled:
              type: integer
              enum:
                - 0
                - 1
              description: 1 if the livemap is enabled
            generated:
              type: integer
              enum:
                - 0
                - 1
              description: 1 if the map is generated
            url:
              type: string
              example: 'https://node1.mystrator.com/s/abc12345-...'
            start:
              type: string
              format: date-time
              description: Start of the last generation
            end:
              type: string
              format: date-time
              description: End of the last generation
            is_free:
              type: integer
              enum:
                - 0
                - 1
              description: 1 if the livemap option would be free for this MyBox (offers ≥ €19.99)
        onboarding:
          type: object
          description: Server onboarding guide state
          properties:
            eligible:
              type: boolean
              description: true if the server is eligible for the guide (recent servers only)
            status:
              type: string
              description: Guide state for this server
              example: not_started
            user_disabled:
              type: boolean
              description: true if the user disabled guides on their account
    ServerLiveData:
      type: object
      properties:
        state:
          type: string
          enum:
            - online
            - starting
            - stopping
            - offline
          description: Current server state
        status:
          type:
            - string
            - 'null'
          description: Internal status (null if the server is offline with no reported state)
        stats:
          type: object
          description: |
            Real-time statistics. The `cpu`/`memory`/`disk`/`network` blocks are present
            as soon as the server is not offline. The `players`, `uptime`, `version`,
            `motd`, `hostname` blocks are only present when the server is `online`.
          properties:
            state:
              type: string
              enum:
                - online
                - starting
                - stopping
                - offline
            cpu:
              type: object
              description: CPU usage (units in hundredths of a core — 100 = 1 core)
              properties:
                current:
                  type: number
                  description: Instantaneous CPU usage
                dedicated:
                  type: integer
                  description: CPU dedicated to the server
                flexcore:
                  type: integer
                  description: Additional shared CPU (FlexCore) provided by the offer
                limit:
                  type: integer
                  description: Total available CPU (dedicated + FlexCore)
                percent:
                  type: integer
                  description: Rounded CPU usage (100 = 1 core)
                is_bursting:
                  type: boolean
                  description: true if usage exceeds the dedicated CPU (FlexCore in use)
            memory:
              type: object
              description: Memory (MB)
              properties:
                current:
                  type: integer
                  description: Used memory (MB)
                limit:
                  type: integer
                  description: Memory limit (MB)
                percent:
                  type: integer
                  description: Usage percentage
            disk:
              type: object
              description: Disk (MB)
              properties:
                current:
                  type: integer
                  description: Used disk space (MB)
                limit:
                  type: integer
                  description: Disk limit (MB)
                percent:
                  type: integer
                  description: Usage percentage
            network:
              type: object
              description: Cumulative network counters (bytes) reported by the daemon
              properties:
                rx_bytes:
                  type: integer
                  description: Bytes received
                tx_bytes:
                  type: integer
                  description: Bytes sent
            uptime:
              type: object
              description: Uptime (only present if `online`)
              properties:
                days:
                  type: integer
                hours:
                  type: integer
                minutes:
                  type: integer
                total_seconds:
                  type: integer
                  description: Total uptime in seconds
            players:
              type: object
              description: 'Connected players (only present if `online`, depending on the game)'
              properties:
                current:
                  type: integer
                  description: Number of connected players
                limit:
                  type: integer
                  description: Maximum number of slots
                list:
                  type: array
                  description: List of connected player names (capped at 300)
                  items:
                    type: string
            version:
              type: string
              description: 'Server version (only present if `online`, depending on the game)'
            motd:
              type: string
              description: 'Message of the day, stripped of color codes (only present if `online`, depending on the game)'
            hostname:
              type: string
              description: 'Hostname announced by the server (only present if `online`, depending on the game)'
  responses:
    Unauthorized:
      description: Invalid or missing token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            api:
              description: ''
              endpoint: ''
              code: 401
              error: API_INVALID_TOKEN
    Forbidden:
      description: 'Accès interdit (permissions insuffisantes, compte suspendu)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            api:
              description: ''
              endpoint: ''
              code: 403
              error: API_FORBIDDEN
    RateLimited:
      description: Too many requests — rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            api:
              description: ''
              endpoint: ''
              code: 429
              error: API_RATE_LIMITED
    BadRequest:
      description: Invalid request (missing or incorrect fields)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            api:
              description: ''
              endpoint: ''
              code: 400
              error: API_MISSING_REQUIRED_FIELDS
    NotFound:
      description: Ressource introuvable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            api:
              description: ''
              endpoint: ''
              code: 404
              error: API_EMPTY_RESOURCE
    ServerError:
      description: Erreur serveur interne
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
          example:
            api:
              description: ''
              endpoint: ''
              code: 500
              error: API_GENERIC_ERROR

