Cloudbrowser Browsers API

openapi: 3.2.0
info:
  title: Cloudbrowser REST Browsers API
  version: 0.6.0
  description: Next.js API with Sandbox0 Chrome, PostgreSQL and Auth0. Billing endpoints require configured Stripe; check billingEnabled. API-key authentication remains supported. Go CLI x-cli entries are design examples only. Fork requires a paused source.
servers:
- url: http://localhost:3000/api/v1
  description: Local development server
- url: https://cloudbrowser.tv/api/v1
  description: Production origin (private preview)
security:
- ApiKey: []
tags:
- name: Browsers
paths:
  /browsers:
    post:
      operationId: createBrowser
      summary: Create a browser
      description: Reserves a concurrent slot atomically. Returns an operation. Links can be created before the browser is running; connecting requires a running browser.
      x-cli: cloudbrowser create --name research --wait
      parameters:
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: Replays with the same payload return the same operation. Different payload returns 409.
      responses:
        '202':
          description: Accepted asynchronous operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBrowser'
      x-implementation: local
      tags:
      - Browsers
    get:
      operationId: listBrowsers
      summary: List browsers
      description: ''
      x-cli: cloudbrowser list --output json
      parameters:
      - name: cursor
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Browser'
                  nextCursor:
                    type:
                    - string
                    - 'null'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}:
    get:
      operationId: getBrowser
      summary: Get a browser
      description: ''
      x-cli: cloudbrowser get br_123
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Browser'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
    delete:
      operationId: deleteBrowser
      summary: Delete a browser
      description: Revoke all grants and stop connections. Deletion is terminal.
      x-cli: cloudbrowser delete br_123 --yes
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Accepted asynchronous operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}/pause:
    post:
      operationId: pauseBrowser
      summary: Pause a browser
      description: Pause disconnects active transports and invalidates runtime viewer sessions/tickets. CDP and reusable Live View links remain valid. After resume reconnect with the same URL. Chrome profiles persist; live page memory is not guaranteed. No implicit resume on access. Pause flushes Chrome profile writes before requesting provider pause.
      x-cli: cloudbrowser pause br_123 --wait
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Accepted asynchronous operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}/resume:
    post:
      operationId: resumeBrowser
      summary: Resume a browser
      description: Pause disconnects active transports and invalidates runtime viewer sessions/tickets. CDP and reusable Live View links remain valid. After resume reconnect with the same URL. Chrome profiles persist; live page memory is not guaranteed. No implicit resume on access. Pause flushes Chrome profile writes before requesting provider pause.
      x-cli: cloudbrowser resume br_123 --wait
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Accepted asynchronous operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}/fork:
    post:
      operationId: forkBrowser
      summary: Fork a browser
      description: Create independent browser ID and profile from a consistent snapshot. No access grants are inherited. Snapshot consistency must be qualified before implementation ships. The source must be paused; a running source returns 409 pause_required. Paused-source inheritance and independent writes passed the live test. Never treat a failed operation as a successful child snapshot.
      x-cli: cloudbrowser fork br_123 --name research-copy --wait
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: true
        schema:
          type: string
        description: Replays with the same payload return the same operation. Different payload returns 409.
      responses:
        '202':
          description: Accepted asynchronous operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForkBrowser'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}/grants:
    post:
      operationId: createGrant
      summary: Create connection access
      description: Create a permanent browser-scoped link, valid until revoked. CDP provides full control. Live View requires sign-in and defaults to read-only. URLs survive pause/resume; runtime connections must reconnect. The secret URL is returned once.
      x-cli: cloudbrowser connect br_123 --name research --output json
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantIssue'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGrant'
            examples:
              cdp:
                value:
                  audience: cdp
                  permission: control
              liveView:
                value:
                  audience: live-view
                  mode: share
                  permission: view
      x-implementation: local
      tags:
      - Browsers
    get:
      operationId: listGrants
      summary: List access grants
      description: List metadata only, never bearer URLs, share secrets, refresh cookies or entry tickets. Live View metadata includes permission, expiresAt (null for never), lastOpenedAt, activeSessions and revision. Filter by audience/status; paginate with cursor/limit. Local implementation returns all matching entries with nextCursor=null; pagination is pending.
      x-cli: cloudbrowser tokens list br_123
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: audience
        in: query
        schema:
          type: string
          enum:
          - cdp
          - live-view
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - expired
          - revoked
          - used
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Grant'
                  nextCursor:
                    type:
                    - string
                    - 'null'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}/grants/{grantId}:
    delete:
      operationId: revokeGrant
      summary: Revoke access
      description: Permanently revoke this grant, close its streams, and invalidate all tickets and refresh families. Reusable URL can no longer create sessions. Idempotent; revoked grants cannot be revived. Does not delete the browser.
      x-cli: cloudbrowser tokens revoke br_123 grant_123 --yes
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: grantId
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Grant'
      x-implementation: local
      tags:
      - Browsers
    patch:
      operationId: updateLiveViewLink
      summary: Change a Live View share link policy
      description: Change link name or Live View permission. Policy updates invalidate existing viewer sessions. Only the owner can manage links.
      x-cli: cloudbrowser links update br_123 grant_123 --permission view
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: grantId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLiveViewGrant'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveViewGrant'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}/grants/{grantId}/sessions:
    get:
      operationId: listLiveViewSessions
      summary: List a link’s authorized viewer sessions
      description: Workspace authorization required. Return metadata only; no cookies, tokens or private page content. Expired/ended sessions are excluded. Local implementation returns all matching entries with nextCursor=null; pagination is pending.
      x-cli: cloudbrowser links sessions br_123 grant_123
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: grantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ViewerSession'
                  nextCursor:
                    type:
                    - string
                    - 'null'
                required:
                - items
                - nextCursor
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-implementation: local
      tags:
      - Browsers
    delete:
      operationId: endLiveViewSessions
      summary: End all sessions for a Live View link
      description: Workspace authorization required. Invalidate all current sessions, refresh families and outstanding entry tickets; close streams. The reusable share URL stays valid for future visits. Use revokeGrant to prevent future visits too. Does not operate on CDP.
      x-cli: cloudbrowser links end-sessions br_123 grant_123 --yes
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: grantId
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Grant'
      x-implementation: local
      tags:
      - Browsers
  /browsers/{browserId}/grants/{grantId}/secret:
    get:
      operationId: revealGrantSecret
      summary: Reveal a saved owner link
      description: Owner-only action. Returns the decrypted URL and, for CDP grants, the short prompt for an agent. List endpoints never return the bearer secret. Grants created before encrypted secret storage may return 409 secret_unavailable.
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: grantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Owner link URL and optional agent prompt
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                  prompt:
                    type:
                    - string
                    - 'null'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: Secret unavailable or revoked
      tags:
      - Browsers
components:
  schemas:
    LiveViewGrant:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        browserId:
          type: string
        audience:
          const: live-view
        mode:
          type: string
          enum:
          - share
          - one-time
        permission:
          type: string
          enum:
          - view
          - control
          default: view
          description: 'view is read-only: stream only, no mouse, keyboard, touch, clipboard writes, uploads, navigation commands or browser control. control allows browser interaction but no workspace, lifecycle or CDP administration. Enforced by the gateway, not just UI.'
        expiresAt:
          type:
          - string
          - 'null'
          description: Null for permanent links. Legacy revoked links may retain their former deadline.
        ticketTtlSeconds:
          type: integer
        entryExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Direct one-time URL only; null for reusable shares.
        autoRenew:
          type: boolean
          deprecated: true
          description: Legacy field. No link renewal is needed; viewer credentials refresh internally.
        createdAt:
          type: string
          format: date-time
        lastOpenedAt:
          type:
          - string
          - 'null'
          format: date-time
        activeSessions:
          type: integer
          minimum: 0
          description: Current authorized viewer sessions, not connected socket count.
        revision:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
          - active
          - expired
          - revoked
          - used
        revoked:
          type: boolean
        name:
          type: string
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
        visitors:
          type: array
          items:
            type: object
            properties:
              accountId:
                type: string
              name:
                type: string
              avatarUrl:
                type:
                - string
                - 'null'
              lastUsedAt:
                type: string
                format: date-time
              online:
                type: boolean
        hasSecret:
          type: boolean
          description: 'Owner metadata: whether repeat-copy is available. The secret is never returned by list endpoints.'
      required:
      - id
      - browserId
      - audience
      - mode
      - permission
      - expiresAt
      - ticketTtlSeconds
      - entryExpiresAt
      - autoRenew
      - createdAt
      - lastOpenedAt
      - activeSessions
      - revision
      - status
      - revoked
    CdpGrant:
      type: object
      required:
      - id
      - browserId
      - audience
      - permission
      - expiresAt
      - renewUntil
      - autoRenew
      - revoked
      properties:
        id:
          type: string
        browserId:
          type: string
        audience:
          const: cdp
        permission:
          const: control
        expiresAt:
          type:
          - string
          - 'null'
          description: Null for permanent links. Legacy revoked links may retain their former deadline.
        renewUntil:
          type:
          - string
          - 'null'
          format: date-time
          description: Legacy field, always null for permanent links.
        autoRenew:
          type: boolean
          deprecated: true
          description: Legacy field. No link renewal is needed; viewer credentials refresh internally.
        revoked:
          type: boolean
        name:
          type: string
        lastUsedAt:
          type:
          - string
          - 'null'
          format: date-time
        visitors:
          type: array
          items:
            type: object
            properties:
              accountId:
                type: string
              name:
                type: string
              avatarUrl:
                type:
                - string
                - 'null'
              lastUsedAt:
                type: string
                format: date-time
              online:
                type: boolean
        hasSecret:
          type: boolean
          description: 'Owner metadata: whether repeat-copy is available. The secret is never returned by list endpoints.'
    CreateCdpGrant:
      type: object
      required:
      - audience
      additionalProperties: false
      properties:
        audience:
          const: cdp
        permission:
          const: control
        name:
          type: string
          maxLength: 80
          default: ''
    UpdateLiveViewGrant:
      type: object
      additionalProperties: false
      properties:
        permission:
          type: string
          enum:
          - view
          - control
          default: view
          description: 'view is read-only: stream only, no mouse, keyboard, touch, clipboard writes, uploads, navigation commands or browser control. control allows browser interaction but no workspace, lifecycle or CDP administration. Enforced by the gateway, not just UI.'
        name:
          type: string
          maxLength: 80
      required: []
      minProperties: 1
      description: Share-mode Live View only. At least one property required. Every effective policy change invalidates all old sessions and tickets immediately and increments revision. The same reusable URL can then open a fresh session. Revoked grants cannot be revived. An expired share may be extended by its owner, but previous sessions stay ended.
    ForkBrowser:
      type: object
      required:
      - name
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
        startPaused:
          type: boolean
          default: true
          description: Paused forks do not reserve running capacity. They retain independent profile writes.
    CreateBrowser:
      type: object
      required:
      - name
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 50
    ViewerSession:
      type: object
      additionalProperties: false
      required:
      - id
      - grantId
      - browserId
      - permission
      - autoRenew
      - accessExpiresAt
      - idleExpiresAt
      - ended
      - authorizationExpiresAt
      - accountId
      properties:
        id:
          type: string
        grantId:
          type: string
        browserId:
          type: string
        permission:
          type: string
          enum:
          - view
          - control
          default: view
          description: 'view is read-only: stream only, no mouse, keyboard, touch, clipboard writes, uploads, navigation commands or browser control. control allows browser interaction but no workspace, lifecycle or CDP administration. Enforced by the gateway, not just UI.'
        autoRenew:
          type: boolean
        accessExpiresAt:
          type: string
          format: date-time
        idleExpiresAt:
          type: string
          format: date-time
        ended:
          type: boolean
        authorizationExpiresAt:
          type:
          - string
          - 'null'
          format: date-time
          default: null
          description: Absolute link authorization deadline, measured from issuance/update; null means no expiration. Applies to new visits AND all existing sessions. Automatic refresh never moves this deadline.
        accountId:
          type: string
          description: Recipient account binding; never infer identity from browserId alone.
    Operation:
      type: object
      required:
      - id
      - browserId
      - status
      properties:
        id:
          type: string
        browserId:
          type: string
        status:
          type: string
          enum:
          - pending
          - running
          - succeeded
          - failed
        error:
          $ref: '#/components/schemas/Error'
    Error:
      type: object
      required:
      - code
      - message
      - requestId
      properties:
        code:
          type: string
          examples:
          - CONCURRENCY_LIMIT
          - ALLOWANCE_EXHAUSTED
          - BROWSER_NOT_RUNNING
          - GRANT_EXPIRED
          - GRANT_REVOKED
          - RENEWAL_LIMIT
          - CONFLICT
        message:
          type: string
        requestId:
          type: string
    CreateLiveViewGrant:
      type: object
      additionalProperties: false
      properties:
        audience:
          const: live-view
        mode:
          const: share
          default: share
          description: New links are reusable. Existing one-time invitations retain their original claim rules.
        permission:
          type: string
          enum:
          - view
          - control
          default: view
          description: 'view is read-only: stream only, no mouse, keyboard, touch, clipboard writes, uploads, navigation commands or browser control. control allows browser interaction but no workspace, lifecycle or CDP administration. Enforced by the gateway, not just UI.'
        name:
          type: string
          maxLength: 80
          default: ''
      required:
      - audience
    GrantIssue:
      oneOf:
      - type: object
        additionalProperties: false
        required:
        - grant
        - cdpUrl
        properties:
          grant:
            $ref: '#/components/schemas/CdpGrant'
          cdpUrl:
            type: string
            description: Secret returned only on issuance.
      - type: object
        required:
        - grant
        - liveViewUrl
        properties:
          grant:
            $ref: '#/components/schemas/LiveViewGrant'
          liveViewUrl:
            type: string
            description: 'Public account-shell entry URL, returned only at issuance: https://cloudbrowser.tv/view/{grantId}#share=... (reusable) or #ticket=... (one-time invitation). Sign in and accept into your library, then open /browsers/{browserId} fullscreen in the same workspace. Viewer transport remains isolated at view.cloudbrowser.tv. Raw secrets never appear in listings.'
    Browser:
      type: object
      required:
      - id
      - name
      - status
      properties:
        id:
          type: string
          example: br_123
        name:
          type: string
        status:
          type: string
          enum:
          - starting
          - running
          - pausing
          - paused
          - resuming
          - failed
          - deleting
        parentId:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        error:
          type:
          - string
          - 'null'
        runtimeGeneration:
          type: integer
        pauseReason:
          type:
          - string
          - 'null'
          enum:
          - user
          - free_allowance_exhausted
          - payment_required
          - concurrency_limit
          - upstream
          - created_paused
          - null
          description: Recorded reason for the most recent pause. Null for unknown historical reasons and shared viewers. Does not indicate whether resume is currently allowed.
        pausedAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Time the pause completed. Null while pausing, for older records or shared viewers.
    CreateGrant:
      oneOf:
      - $ref: '#/components/schemas/CreateCdpGrant'
      - $ref: '#/components/schemas/CreateLiveViewGrant'
      discriminator:
        propertyName: audience
        mapping:
          cdp: '#/components/schemas/CreateCdpGrant'
          live-view: '#/components/schemas/CreateLiveViewGrant'
    Grant:
      oneOf:
      - $ref: '#/components/schemas/CdpGrant'
      - $ref: '#/components/schemas/LiveViewGrant'
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: Account/workspace API key. Distinct from a per-browser CDP token or viewer ticket.
    ViewerAccess:
      type: apiKey
      in: cookie
      name: __Secure-cb_viewer_access
      description: Viewer-origin HttpOnly cookie; actual name is session-suffixed (cb_access_{sessionId} or cb_refresh_{sessionId}). Exact Origin is required. Local HTTP only omits Secure.
    ViewerRefresh:
      type: apiKey
      in: cookie
      name: __Secure-cb_viewer_refresh
      description: Viewer-origin HttpOnly cookie; actual name is session-suffixed (cb_access_{sessionId} or cb_refresh_{sessionId}). Exact Origin is required. Local HTTP only omits Secure.
    AccountSession:
      type: apiKey
      in: cookie
      name: __Host-cb_account
      description: Signed-in account on cloudbrowser.tv; HttpOnly, Secure, host-only, SameSite=Lax; CSRF protection required. Not sent to viewer origin.
    AccountAccess:
      type: http
      scheme: bearer
      description: User-account access token issued by human CLI login. Not a workspace API key, CDP token or viewer refresh token.