dialogbrain-com Listen API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Listen API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: listen
paths:
  /api/listen/join/{token}:
    post:
      tags:
      - listen
      summary: Join As Viewer
      description: 'Self-service join: a logged-in user follows a listener share link and

        becomes a read-only ''viewer'' member of the link''s workspace.


        Idempotent + race-safe (two phone tabs can hit this at once): a single

        upsert adds a viewer if absent, refreshes the channel binding if already a

        viewer, and NEVER downgrades an existing owner/admin/member. For users who

        are (or become) viewers, the workspace is set as their default so reopening

        the app later lands them here.


        Args:

        token: the voice_share_token from the link.

        user: authed user (just signed in, possibly brand-new via OAuth).

        db: shared DB session.


        Returns:

        JoinResponse with workspace_id, channel_account_id, optional live

        thread_id, and the caller''s resulting role.


        Raises:

        HTTPException: 404 if the token is invalid/expired/revoked (or a

        one-time link consumed by someone else); 410 if a one-time link is

        claimed by another user in the race window.'
      operationId: join_as_viewer_api_listen_join__token__post
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JoinResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/listen/share:
    post:
      tags:
      - listen
      summary: Create Share
      description: 'Create a new public listener share link for a Meet channel.


        Links are persistent and additive — this does NOT revoke prior links.

        Returns the new token and the public listener URL.


        Args:

        body: Request with channel_account_id and optional target_lang.

        user: Authed user from JWT token.

        db: Shared database session.


        Returns:

        CreateShareResponse with token and listen_url.


        Raises:

        HTTPException: 403 if no workspace found for user.'
      operationId: create_share_api_listen_share_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShareBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateShareResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/listen/shares:
    get:
      tags:
      - listen
      summary: List Shares
      description: 'List ALL the workspace''s listener share links (for settings), each with

        a computed status (''active'' | ''used'' | ''expired'' | ''revoked'') so the UI

        can show dead links instead of silently hiding them.


        Viewers can''t manage links. Each item carries the public listen_url so the

        UI can show + copy it without rebuilding the URL.'
      operationId: list_shares_api_listen_shares_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSharesResponse'
  /api/listen/share/{token}:
    delete:
      tags:
      - listen
      summary: Revoke Share
      description: 'Revoke an existing listener share link.


        Args:

        token: The share token to revoke.

        user: Authed user from JWT token.

        db: Shared database session.


        Returns:

        RevokeShareResponse with revoked=True if successful.


        Raises:

        HTTPException: 403 if no workspace found for user; 404 if token not found.'
      operationId: revoke_share_api_listen_share__token__delete
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeShareResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CreateShareResponse:
      properties:
        token:
          type: string
          title: Token
        listen_url:
          type: string
          title: Listen Url
      type: object
      required:
      - token
      - listen_url
      title: CreateShareResponse
      description: Response body for creating a listener share link.
    RevokeShareResponse:
      properties:
        revoked:
          type: boolean
          title: Revoked
      type: object
      required:
      - revoked
      title: RevokeShareResponse
      description: Response body for revoking a listener share link.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ListSharesResponse:
      properties:
        links:
          items:
            $ref: '#/components/schemas/ShareLinkItem'
          type: array
          title: Links
      type: object
      required:
      - links
      title: ListSharesResponse
      description: All listener share links for the workspace (incl. used/expired/revoked).
    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
    JoinResponse:
      properties:
        workspace_id:
          type: integer
          title: Workspace Id
        channel_account_id:
          type: integer
          title: Channel Account Id
        thread_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Thread Id
        role:
          type: string
          title: Role
      type: object
      required:
      - workspace_id
      - channel_account_id
      - role
      title: JoinResponse
      description: Response body for joining a workspace as a read-only viewer.
    CreateShareBody:
      properties:
        channel_account_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Channel Account Id
        target_lang:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Lang
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        one_time:
          type: boolean
          title: One Time
          default: false
      type: object
      title: CreateShareBody
      description: 'Request body for creating a listener share link.


        channel_account_id is optional — when omitted (the workspace-level "Share

        viewer link" UI), the workspace''s persistent Google Meet channel_account is

        resolved/created automatically, so a link can be minted with no live meeting.'
    ShareLinkItem:
      properties:
        token:
          type: string
          title: Token
        listen_url:
          type: string
          title: Listen Url
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        target_lang:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Lang
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        one_time:
          type: boolean
          title: One Time
          default: false
        used_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Used At
        status:
          type: string
          title: Status
          default: active
      type: object
      required:
      - token
      - listen_url
      title: ShareLinkItem
      description: One listener share link, for the settings list.