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

# Open Console Session

> Opens the server's console screen (VNC), the one the Console tab in the panel
shows, to show it to your own customers. Open `url` in a new window or an
`iframe`, or connect your own noVNC client to `websocket_url` with `password`.

A session is good for one connection, made within ten seconds (`expires_at`).
Open a new session for every connection, reconnects included. A connected
console stays open for up to four hours. The server must be running.

A Linux server needs the QXL display for its console, and switching to it
restarts the server once. Until then this answers `409` with
`needs_display_switch: true`; see `PUT /servers/{server}/console/display`.




## OpenAPI

````yaml post /servers/{server}/console/sessions
openapi: 3.1.0
info:
  title: APIFiddle Sample Definition
  version: 0.0.0
  description: Example workspace
servers:
  - url: https://rdp.sh/api/v1
    description: Default production endpoint.
security: []
paths:
  /servers/{server}/console/sessions:
    post:
      summary: Open a console session
      description: >
        Opens the server's console screen (VNC), the one the Console tab in the
        panel

        shows, to show it to your own customers. Open `url` in a new window or
        an

        `iframe`, or connect your own noVNC client to `websocket_url` with
        `password`.


        A session is good for one connection, made within ten seconds
        (`expires_at`).

        Open a new session for every connection, reconnects included. A
        connected

        console stays open for up to four hours. The server must be running.


        A Linux server needs the QXL display for its console, and switching to
        it

        restarts the server once. Until then this answers `409` with

        `needs_display_switch: true`; see `PUT
        /servers/{server}/console/display`.
      operationId: openServerConsoleSession
      parameters:
        - $ref: '#/components/parameters/server'
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                title: OpenServerConsoleSessionCreated
                required:
                  - status
                  - url
                  - websocket_url
                  - password
                  - expires_at
                properties:
                  status:
                    type: boolean
                    examples:
                      - true
                  url:
                    type: string
                    description: >
                      The console in the browser, to open in a new window or
                      embed in an

                      `iframe`. It connects as it loads. The password is in its
                      fragment,

                      which the browser never sends to a server.
                    examples:
                      - >-
                        https://terminal.rdp.sh/novnc/vnc.html?autoconnect=1&resize=scale&encrypt=1&host=terminal.rdp.sh&port=443&path=vnc%3Ftoken%3DeyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MjEzIiwic2VydmVyX2lkIjoxOTQwMjksImV4cCI6MTc5MzEwNzAyNywianRpIjoiMWIzOWZjYTQtM2QwNy00NWEwLTk4NmUtN2ExZDc2ZDZjYzY1In0.dWNUOGv-ghEZaq2tVb-7Bw46eZWfynJa9T_iUIAyTUY&quality=4&compression=8#password=x7%26Kq%232m
                  websocket_url:
                    type: string
                    description: >
                      The console's WebSocket, for a page that runs its own

                      [noVNC](https://github.com/novnc/noVNC) client instead of
                      `url`.

                      Connect to it and answer the VNC password prompt with
                      `password`.
                    examples:
                      - >-
                        wss://terminal.rdp.sh/vnc?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI0MjEzIiwic2VydmVyX2lkIjoxOTQwMjksImV4cCI6MTc5MzEwNzAyNywianRpIjoiMWIzOWZjYTQtM2QwNy00NWEwLTk4NmUtN2ExZDc2ZDZjYzY1In0.dWNUOGv-ghEZaq2tVb-7Bw46eZWfynJa9T_iUIAyTUY
                  password:
                    type: string
                    description: >-
                      The VNC password of this session. `url` already carries
                      it.
                    examples:
                      - x7&Kq#2m
                  expires_at:
                    type: string
                    format: date-time
                    description: >-
                      Connect before this time, ten seconds after the session
                      was opened.
                    examples:
                      - '2026-10-27T13:17:07+00:00'
          description: The session is open. Connect to it within ten seconds.
        '403':
          content:
            application/json:
              schema:
                type: object
                title: OpenServerConsoleSessionUnauthorized
                properties:
                  status:
                    type: boolean
                    examples:
                      - false
                  error:
                    type: string
                    examples:
                      - This action is unauthorized
          description: User does not own the server.
        '404':
          description: Server not found.
        '409':
          content:
            application/json:
              schema:
                type: object
                title: OpenServerConsoleSessionConflict
                properties:
                  status:
                    type: boolean
                    examples:
                      - false
                  error:
                    type: string
                    examples:
                      - >-
                        The console needs the QXL display first, and switching
                        to it restarts the server once. Switch it with PUT
                        /api/v1/servers/194029/console/display.
                  needs_display_switch:
                    type: boolean
                    description: >
                      Present, and `true`, when a Linux server needs the QXL
                      display first.

                      Switch it with `PUT /servers/{server}/console/display`.
                    examples:
                      - true
          description: >
            The server is stopped, a Linux server needs its console display
            switched

            first (`needs_display_switch`), or the server is suspended or busy.
        '429':
          content:
            application/json:
              schema:
                type: object
                title: OpenServerConsoleSessionTooManyRequests
                properties:
                  status:
                    type: boolean
                    examples:
                      - false
                  error:
                    type: string
                    examples:
                      - >-
                        You can open the console of this server at most 10 times
                        every 2 minutes. Please try again in 37 seconds.
          description: >
            Too many sessions: at most 10 every 2 minutes per server, and 60 a
            minute

            per account.
        '503':
          content:
            application/json:
              schema:
                type: object
                title: OpenServerConsoleSessionUnavailable
                properties:
                  status:
                    type: boolean
                    examples:
                      - false
                  error:
                    type: string
                    examples:
                      - >-
                        Could not open a console session. Please try again in a
                        moment.
          description: The session could not be opened.
      security:
        - Authorization: []
components:
  parameters:
    server:
      in: path
      name: server
      schema:
        type: string
      required: true
  securitySchemes:
    Authorization:
      in: header
      name: Authorization
      type: apiKey
      description: |
        Your API key as it is, without `Bearer`. API access is off for new
        accounts: until it is turned on under Settings > API, every request
        answers `403` with `API access is turned off for this account. Turn it
        on under Settings > API.` If the account lists allowed IPs, a request
        from any other address answers `403` with `This API key is not allowed
        from <address>`.

````

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