> ## Documentation Index
> Fetch the complete documentation index at: https://docs.server.express/llms.txt
> Use this file to discover all available pages before exploring further.

# Open a VNC console

> Mints a short-lived console handle for this VM. Connect a noVNC client (WebSocket) to `path` on the API origin within
`expiresInMs` and authenticate with `password` — the relay holds the hypervisor side, so no Proxmox address or credential
is exposed. Proxmox expires the VNC password about 30 seconds after this call. Needs the operate role. Blocked while
PENDING/SUSPENDED (403); 409 while busy, still being built, or powered off; 503 if the platform has no console
credentials configured. Writes an `OPEN_CLOUD_CONSOLE` audit entry.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/cloud/{id}/console
openapi: 3.1.0
info:
  title: Server.Express API
  version: 1.0.0
  description: >-
    The customer-facing Server.Express API: auth, billing, tickets, cloud and
    dedicated servers, hosting, reselling and account management. Every response
    uses the `{ success, data | error }` envelope.
  contact:
    name: Server.Express
    url: https://server.express
servers:
  - url: https://my.server.express/api
    description: Production
security:
  - bearerAuth: []
  - apiToken: []
tags:
  - name: API Tokens
  - name: Account
  - name: Auth
  - name: Cloud
  - name: Coupons
  - name: Credits
  - name: Dashboard
  - name: Dedicated
  - name: Health
  - name: Hosting
  - name: Integrations
  - name: Invoices
  - name: Livechat
  - name: Notifications
  - name: Passkeys
  - name: Payments
  - name: Products
  - name: Public
  - name: Public Invoices
  - name: Public Tools
  - name: Reseller
  - name: SSH Keys
  - name: Services
  - name: Tasks
  - name: Teams
  - name: Tickets
  - name: Web Hosting
  - name: Webhooks
paths:
  /v1/cloud/{id}/console:
    post:
      tags:
        - Cloud
      summary: Open a VNC console
      description: >-
        Mints a short-lived console handle for this VM. Connect a noVNC client
        (WebSocket) to `path` on the API origin within

        `expiresInMs` and authenticate with `password` — the relay holds the
        hypervisor side, so no Proxmox address or credential

        is exposed. Proxmox expires the VNC password about 30 seconds after this
        call. Needs the operate role. Blocked while

        PENDING/SUSPENDED (403); 409 while busy, still being built, or powered
        off; 503 if the platform has no console

        credentials configured. Writes an `OPEN_CLOUD_CONSOLE` audit entry.
      operationId: publicCloudOpenConsole
      parameters:
        - name: id
          in: path
          required: true
          description: Service id of the cloud server.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Console handle.
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    required:
                      - path
                      - password
                      - expiresInMs
                    properties:
                      path:
                        type: string
                        description: >-
                          WebSocket path on the API origin, e.g.
                          `/v1/cloud/console/ws?handle=…`.
                      password:
                        type: string
                        description: VNC protocol password for the RFB handshake.
                      expiresInMs:
                        type: integer
                        description: How long the handle stays valid (currently 20000).
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            Conflicts with the server's current state — most often another task
            (reinstall, snapshot…) is running, in which case `data.taskId` names
            it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicCloudBusyError'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          description: Consoles aren't configured on this platform yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
        - apiToken: []
components:
  responses:
    Unauthorized:
      description: Missing, invalid or expired credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        Authenticated but not allowed (missing scope, not an admin, or not your
        resource).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The resource doesn't exist or isn't visible to you.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    PublicCloudBusyError:
      type: object
      description: >-
        The 409 sent while another job runs on the server; `data.taskId` names
        it so a client can watch it.
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
        data:
          type: object
          properties:
            taskId:
              type:
                - string
                - 'null'
            limit:
              type: integer
              description: Snapshot cap (snapshot-limit refusals only).
            used:
              type: integer
              description: Snapshots held (snapshot-limit refusals only).
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
          description: Human-readable error message.
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Session access token (JWT) from POST /v1/auth/login or /v1/auth/refresh.
        A session satisfies every API scope.
    apiToken:
      type: http
      scheme: bearer
      bearerFormat: se_live_<prefix>_<secret>
      description: >-
        Personal API token created under Settings → API tokens. Only routes
        guarded by verifyApiAuth accept it, and the token must carry the scope
        named in the operation's x-required-scope.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.