Cloudbrowser B API

openapi: 3.2.0
info:
  title: Cloudbrowser REST B 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: B
paths:
  /b/{browserId}/session/exchange:
    post:
      operationId: exchangeViewerTicket
      summary: Exchange a Live View link
      description: Consume an account-authorized, runtime-bound ticket once and issue short-lived HttpOnly viewer session cookies. Requires exact Origin and browser binding; rejects revoked source grants, changed permissions and inactive runtimes. Link authorization persists until revoked; session credentials refresh internally. No workspace key or anonymous sharing access is accepted.
      servers:
      - url: http://localhost:3001
        description: Isolated local viewer
      - url: https://view.cloudbrowser.tv
        description: Planned production viewer
      security: []
      parameters:
      - name: browserId
        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: Credentials are returned only via HttpOnly Set-Cookie; invalid/consumed tickets return 401.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewerSessionReceipt'
      x-viewer: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeViewerTicket'
      x-implementation: local
      tags:
      - B
  /b/{browserId}/session/refresh:
    post:
      operationId: refreshViewerSession
      summary: Refresh the viewer session
      description: Rotate short-lived viewer cookies with reuse detection. Reject revoked sessions, inactive grants, changed revision/runtime or expired idle deadline. Internal session refresh requires no CLI process. Reopen through the authenticated account library after session inactivity. Does not widen permissions.
      servers:
      - url: http://localhost:3001
        description: Isolated local viewer
      - url: https://view.cloudbrowser.tv
        description: Planned production viewer
      security:
      - ViewerRefresh: []
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: session
        in: query
        required: true
        schema:
          type: string
        description: Non-secret session ID returned by exchange; matching cookies still required.
      responses:
        '200':
          description: Credentials are returned only via HttpOnly Set-Cookie; invalid/consumed tickets return 401.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewerSessionReceipt'
        default:
          description: Structured error; HTTP 400/401/403/404/409/429/503 as applicable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-viewer: true
      x-implementation: local
      tags:
      - B
  /b/{browserId}/session/logout:
    post:
      operationId: logoutViewerSession
      summary: End the viewer session
      description: 'End only the current viewer session, revoke its refresh family and close streams; clear cookies using the exact browser-specific path. Does not revoke the share URL: the accepted account can reopen its saved browser for a new session. Direct one-time tickets remain consumed. Missing/expired cookies are cleared and return 200. Closing a page alone is not reliable logout. Use isolated viewer origin, no-store/no-referrer, strict CSP, same-origin credentials, exact Origin/CSRF checks and redacted logs. Check current link authorization, permission, revision, runtime and issuer access on every request and stream. Never accept a workspace API key here. Validate the recipient’s active account/membership as well as the owner’s source grant. Removal from the recipient library invalidates that recipient’s sessions only. Local cookies are independently named per viewer session (cb_access_{sessionId}, cb_refresh_{sessionId}) and omit Secure on localhost HTTP. No anonymous account authorization.'
      servers:
      - url: http://localhost:3001
        description: Isolated local viewer
      - url: https://view.cloudbrowser.tv
        description: Planned production viewer
      security:
      - ViewerAccess: []
      - ViewerRefresh: []
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      - name: session
        in: query
        required: true
        schema:
          type: string
        description: Non-secret session ID returned by exchange; matching cookies still required.
      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:
                type: object
      x-viewer: true
      x-implementation: local
      tags:
      - B
components:
  schemas:
    ViewerSessionReceipt:
      type: object
      additionalProperties: false
      required:
      - sessionId
      - autoRenew
      - permission
      - expiresAt
      properties:
        sessionId:
          type: string
        autoRenew:
          type: boolean
        permission:
          type: string
          enum:
          - view
          - control
        expiresAt:
          type: string
          format: date-time
    ExchangeViewerTicket:
      type: object
      additionalProperties: false
      required:
      - ticket
      properties:
        ticket:
          type: string
          description: Single-use opaque secret from the URL fragment. Never log it.
    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
  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.