VNC Cloud Addresses API

openapi: 3.1.0
info:
  title: VNC Cloud Cloud Addresses API
  description: The VNC Cloud REST API manages cloud addresses that allow devices to join VNC Cloud and establish remote connections through RealVNC's managed broker service. Cloud addresses serve as stable identifiers for devices participating in VNC Cloud connectivity. Supports creating, listing, updating, resetting, and deleting cloud addresses with access control via groups and allowlisted peer addresses.
  version: '1.1'
  contact:
    name: RealVNC Developer Support
    url: https://help.realvnc.com/
  license:
    name: RealVNC Commercial License
    url: https://www.realvnc.com/en/legal/
servers:
- url: https://api.vnc.com/cloud/1.1
  description: VNC Cloud API
security:
- BasicAuth: []
tags:
- name: Cloud Addresses
  description: Manage cloud addresses for VNC Cloud connectivity brokering.
paths:
  /static-address:
    post:
      operationId: createCloudAddress
      summary: Create Cloud Address
      description: Create a new static cloud address for a device to join VNC Cloud.
      tags:
      - Cloud Addresses
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloudAddressCreate'
      responses:
        '201':
          description: Cloud address created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudAddressCreated'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
    get:
      operationId: listCloudAddresses
      summary: List Cloud Addresses
      description: Retrieve a paginated list of all cloud addresses in the account.
      tags:
      - Cloud Addresses
      parameters:
      - name: limit
        in: query
        description: Maximum number of addresses to return per page (1–99, default 20).
        schema:
          type: integer
          minimum: 1
          maximum: 99
          default: 20
      responses:
        '200':
          description: Paginated list of cloud addresses.
          headers:
            Link:
              description: Pagination links (next/prev pages).
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudAddressList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /static-address/{cloudAddress}:
    parameters:
    - name: cloudAddress
      in: path
      required: true
      description: The cloud address identifier.
      schema:
        type: string
    get:
      operationId: getCloudAddress
      summary: Get Cloud Address
      description: Retrieve details of a specific cloud address.
      tags:
      - Cloud Addresses
      responses:
        '200':
          description: Cloud address details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudAddressDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCloudAddress
      summary: Update Cloud Address
      description: Update the configuration of a cloud address including groups and access control.
      tags:
      - Cloud Addresses
      parameters:
      - name: If-Match
        in: header
        description: ETag value for optimistic concurrency control.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloudAddressUpdate'
      responses:
        '200':
          description: Cloud address updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudAddressDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
    post:
      operationId: resetCloudAddressPassword
      summary: Reset Cloud Address Password
      description: Reset the cloud password for a specific cloud address.
      tags:
      - Cloud Addresses
      responses:
        '200':
          description: Password reset. New password returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudAddressCreated'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCloudAddress
      summary: Delete Cloud Address
      description: Remove a cloud address permanently from the account.
      tags:
      - Cloud Addresses
      responses:
        '204':
          description: Cloud address deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /static-address/{cloudAddress}/ready:
    parameters:
    - name: cloudAddress
      in: path
      required: true
      description: The cloud address identifier.
      schema:
        type: string
    get:
      operationId: checkCloudAddressReady
      summary: Check Cloud Address Readiness
      description: Check whether recent changes to a cloud address have been propagated.
      tags:
      - Cloud Addresses
      responses:
        '200':
          description: Readiness status for the cloud address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    AccessControl:
      type: object
      description: Access control configuration for a cloud address.
      properties:
        groups:
          type: array
          maxItems: 24
          items:
            type: string
          description: Groups allowed to connect to this cloud address.
        cloudAddresses:
          type: array
          maxItems: 8
          items:
            type: string
          description: Specific cloud addresses allowed to connect.
    CloudAddressCreate:
      type: object
      required:
      - allowedActions
      properties:
        allowedActions:
          type: string
          enum:
          - connect
          - listen
          description: Whether the address is used to initiate or accept connections.
        groups:
          type: array
          maxItems: 16
          items:
            type: string
            maxLength: 256
          description: Group names to associate with this cloud address.
        accessControl:
          $ref: '#/components/schemas/AccessControl'
    CloudAddressCreated:
      type: object
      properties:
        cloudAddress:
          type: string
          description: The newly created cloud address identifier.
        cloudPassword:
          type: string
          description: The cloud password for authenticating with this address.
    ReadinessStatus:
      type: object
      properties:
        changes:
          type: string
          enum:
          - none
          - pending
          description: Whether recent changes are still being propagated.
    CloudAddressDetails:
      type: object
      properties:
        cloudAddress:
          type: string
          description: The cloud address identifier.
        allowedActions:
          type: array
          items:
            type: string
            enum:
            - connect
            - listen
        groups:
          type: array
          items:
            type: string
        accessControl:
          $ref: '#/components/schemas/AccessControl'
    CloudAddressList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CloudAddressDetails'
    Error:
      type: object
      properties:
        errorCode:
          type: string
          description: Machine-readable error code.
        errorMessage:
          type: string
          description: Human-readable error description.
    CloudAddressUpdate:
      type: object
      properties:
        allowedActions:
          type: string
          enum:
          - connect
          - listen
        groups:
          type: array
          maxItems: 16
          items:
            type: string
            maxLength: 256
        accessControl:
          $ref: '#/components/schemas/AccessControl'
  responses:
    Unauthorized:
      description: Missing or invalid API credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    PreconditionFailed:
      description: ETag mismatch — resource was modified since last retrieved.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: Service temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Basic authentication using VNC Cloud API key (username) and secret (password) provided by RealVNC.