dialogbrain-com Browser Identities API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Browser Identities API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: browser-identities
paths:
  /api/workspaces/{workspace_id}/browser/identities:
    post:
      tags:
      - browser-identities
      summary: Create Pending
      operationId: create_pending_api_workspaces__workspace_id__browser_identities_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePendingRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - browser-identities
      summary: List Identities
      operationId: list_identities_api_workspaces__workspace_id__browser_identities_get
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspaces/{workspace_id}/browser/identities/{identity_id}/open:
    post:
      tags:
      - browser-identities
      summary: Open Identity
      description: 'Start a VNC session for an active identity without revoking it.

        Returns vnc_ws_url so the frontend can embed the viewer.


        Optional JSON body with ''url'' field to navigate to a specific page on the

        identity''s origin instead of the origin itself. The url must be on the same

        domain as the identity''s origin (https or http).'
      operationId: open_identity_api_workspaces__workspace_id__browser_identities__identity_id__open_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/OpenIdentityRequest'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspaces/{workspace_id}/browser/identities/{identity_id}/abort:
    post:
      tags:
      - browser-identities
      summary: Abort Identity
      description: 'Cancel the headed claim/Open session for this identity WITHOUT

        capturing cookies — called when the user closes/cancels the claim modal.

        Frees the single-display slot so the next Open doesn''t 409, AND undoes the

        DB side of the claim: an in-flight re-login is released (the identity keeps

        the session it already had), a first claim that never completed is deleted

        instead of being left as a "Claiming…" stub. Idempotent.'
      operationId: abort_identity_api_workspaces__workspace_id__browser_identities__identity_id__abort_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspaces/{workspace_id}/browser/identities/{identity_id}/consent_accepted:
    post:
      tags:
      - browser-identities
      summary: Consent Accepted
      description: 'Stamp consent and start the claim window. Optional body `{url}`: the

        first page, on the identity''s own site (a hand-off link to a signup page).'
      operationId: consent_accepted_api_workspaces__workspace_id__browser_identities__identity_id__consent_accepted_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/OpenIdentityRequest'
              - type: 'null'
              title: Body
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspaces/{workspace_id}/browser/identities/{identity_id}/complete:
    post:
      tags:
      - browser-identities
      summary: Complete
      operationId: complete_api_workspaces__workspace_id__browser_identities__identity_id__complete_post
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__api__workspace_browser_identities__CompleteRequest'
              default:
                login_url_patterns: []
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspaces/{workspace_id}/browser/identities/{identity_id}:
    patch:
      tags:
      - browser-identities
      summary: Patch Identity
      operationId: patch_identity_api_workspaces__workspace_id__browser_identities__identity_id__patch
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IsSharedPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - browser-identities
      summary: Delete Identity
      operationId: delete_identity_api_workspaces__workspace_id__browser_identities__identity_id__delete
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspaces/{workspace_id}/browser/identities/{identity_id}/credentials:
    put:
      tags:
      - browser-identities
      summary: Set Credentials
      operationId: set_credentials_api_workspaces__workspace_id__browser_identities__identity_id__credentials_put
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - browser-identities
      summary: Delete Credentials
      operationId: delete_credentials_api_workspaces__workspace_id__browser_identities__identity_id__credentials_delete
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspaces/{workspace_id}/browser/identities/{identity_id}/egress:
    patch:
      tags:
      - browser-identities
      summary: Set Identity Egress
      description: 'Override this identity''s egress. egress_mode=null restores

        ''inherit the workspace default'' — it does NOT mean direct. ADMIN, not

        OWNER: this can only pick among egresses the workspace already approved

        (workspace default, or a VPN profile scoped to this workspace) — it

        can never create a new egress route, unlike the workspace default PUT.'
      operationId: set_identity_egress_api_workspaces__workspace_id__browser_identities__identity_id__egress_patch
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: integer
          title: Workspace Id
      - name: identity_id
        in: path
        required: true
        schema:
          type: integer
          title: Identity Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityEgressPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    OpenIdentityRequest:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
      type: object
      title: OpenIdentityRequest
      description: "Request body for opening an identity with optional start URL.\n\nurl: Optional URL to navigate to on the identity's origin. Must be on the\n    same domain as the identity's origin (https or http). If not provided,\n    the identity's origin is used."
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    src__api__workspace_browser_identities__CompleteRequest:
      properties:
        storage_state_json:
          anyOf:
          - type: string
            contentMediaType: application/octet-stream
          - type: 'null'
          title: Storage State Json
        login_url_patterns:
          items:
            type: string
          type: array
          title: Login Url Patterns
      type: object
      title: CompleteRequest
      description: "Cookies for the completion endpoint.\n\nTwo call shapes are valid:\n- Body with storage_state_json set: caller (typically a test harness\n  or future internal pusher) already has the cookies. Used as-is.\n- Empty body / storage_state_json=None: the gateway pulls\n  storage_state from browser-mcp via /claim/complete server-side.\n  This is the user-facing path — the frontend Close button POSTs\n  with no body and the gateway handles the round-trip."
    IsSharedPatch:
      properties:
        is_shared:
          type: boolean
          title: Is Shared
      type: object
      required:
      - is_shared
      title: IsSharedPatch
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    IdentityEgressPatch:
      properties:
        egress_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Egress Mode
        egress_vpn_profile_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Egress Vpn Profile Id
      type: object
      title: IdentityEgressPatch
      description: 'egress_mode=None restores ''inherit the workspace default'' — it is NOT

        ''direct''. Must be stored as SQL NULL (see egress_service.py).'
    CreatePendingRequest:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
        origin:
          type: string
          title: Origin
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        force:
          type: boolean
          title: Force
          default: false
      type: object
      required:
      - name
      - origin
      title: CreatePendingRequest