Cloudbrowser Library API

openapi: 3.2.0
info:
  title: Cloudbrowser REST Library 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: Library
paths:
  /library/browsers:
    get:
      operationId: listBrowserLibrary
      summary: List my owned and shared browsers
      description: Signed-in account only. Owned and shared entries appear in one grid. A shared entry does not transfer ownership, create a browser, consume the recipient’s browser concurrency, or grant lifecycle/reshare/CDP rights. Every preview subscription rechecks current authorization. Unavailable entries may remain visible without streaming private contents. Compute remains on the owning workspace. Local implementation returns all matching entries with nextCursor=null; pagination is pending.
      x-cli: cloudbrowser library list --source all --output json
      x-account: true
      security:
      - AccountSession: []
      - AccountAccess: []
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/BrowserLibraryEntry'
                  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:
      - Library
  /library/shares/accept:
    post:
      operationId: acceptSharedBrowser
      summary: Accept a shared browser into my account
      description: Requires signed-in account and a valid invitation. Reusable share links can be accepted by multiple accounts. Direct one-time invitations atomically bind to the first accepting account; subsequent redemption receives 409, including by the same account; use the saved library entry instead. Validate link expiration, revocation, revision and owner authority before accepting. Save an account-to-browser access reference, not ownership or a raw bearer token. Deduplicate by account/browser and retain a specific authorized source grant; never silently widen rights. Existing owner entries remain owned. Accepted members can later request fresh viewer tickets without replaying the original invite. Entry ticket expiration does not expire accepted membership; parent-link expiration/revocation does. Return the canonical /browsers/{id} URL. A paused browser can be added but must not be resumed automatically.
      x-cli: cloudbrowser library add --url "$LIVE_VIEW_URL"
      x-account: true
      security:
      - AccountSession: []
      - AccountAccess: []
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptSharedBrowser'
      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
                required:
                - browserId
                properties:
                  browserId:
                    type: string
      x-implementation: local
      tags:
      - Library
  /library/browsers/{browserId}:
    delete:
      operationId: removeSharedBrowser
      summary: Remove a shared browser from my library
      description: Remove only this recipient’s saved access relationship and end that recipient’s viewer sessions. Do not delete/pause the owner’s browser, revoke the public share link or affect other recipients. Reject owned entries; owner deletion uses the lifecycle API. Re-adding requires a valid reusable invite or new invite if one-time access was removed.
      x-cli: cloudbrowser library remove br_shared --yes
      x-account: true
      security:
      - AccountSession: []
      - AccountAccess: []
      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: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  removed:
                    const: true
      x-implementation: local
      tags:
      - Library
  /library/browsers/{browserId}/viewer-ticket:
    post:
      operationId: createLibraryViewerTicket
      summary: Open an owned or saved shared browser
      description: Account authorization required. Check ownership or saved membership AND its current parent grant permission, revision, expiration and issuer access; a saved list entry is not authority by itself. Browser must be running to stream; paused view shows an explicitly labeled authorized last frame without implicitly resuming. Mint a short-lived one-use runtime-bound ticket for the isolated viewer origin. The account shell passes only this ticket through a strict origin-checked handshake to the viewer, never its account cookie or workspace API key. Shared control grants no lifecycle, deletion, fork, reshare or CDP rights. Grid and fullscreen use this same authorization path; switching presentation alone does not duplicate runtime sessions.
      x-cli: cloudbrowser library view br_shared
      x-account: true
      security:
      - AccountSession: []
      - AccountAccess: []
      parameters:
      - name: browserId
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewerTicket'
        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:
      - Library
components:
  schemas:
    ViewerTicket:
      type: object
      additionalProperties: false
      properties:
        ticket:
          type: string
          description: One-time secret minted after account/library authorization, bound to recipient account, browser, grant revision, permission and runtime. Return only on ticket issuance.
        ticketExpiresAt:
          type: string
          format: date-time
        url:
          type: string
          description: Isolated viewer URL carrying a single-use ticket in its fragment. The viewer clears the fragment before exchange.
      required:
      - ticket
      - ticketExpiresAt
      - url
    AcceptSharedBrowser:
      type: object
      additionalProperties: false
      properties:
        linkId:
          type: string
        shareToken:
          type: string
        ticket:
          type: string
      required:
      - linkId
      oneOf:
      - required:
        - shareToken
        not:
          required:
          - ticket
      - required:
        - ticket
        not:
          required:
          - shareToken
      description: Account authorization plus one invitation credential. Token read from URL fragment and removed immediately. Store a server-side pending authorization handle bound to the login transaction when redirecting to sign-in; never put the bearer secret in OAuth state, returnTo, query strings, analytics or localStorage.
    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
    BrowserLibraryEntry:
      type: object
      properties:
        id:
          type: string
          example: br_123
        name:
          type: string
        status:
          type: string
          enum:
          - starting
          - running
          - pausing
          - paused
          - resuming
          - failed
          - deleting
          - unavailable
        parentId:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        error:
          type:
          - string
          - 'null'
        runtimeGeneration:
          type: integer
        owner:
          type: boolean
        permission:
          type: string
          enum:
          - view
          - control
        ownerName:
          type: string
        shared:
          type: boolean
          description: Owned browser has at least one currently active sharing grant.
        ownerAvatarUrl:
          type:
          - string
          - 'null'
          format: uri
        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.
      required:
      - id
      - name
      - status
      - owner
      - permission
      - runtimeGeneration
  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.