dialogbrain-com Sync Admin API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Sync Admin API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: sync-admin
paths:
  /api/threads/{thread_id}/sync-status:
    get:
      tags:
      - sync-admin
      summary: Get Thread Sync Status
      description: 'Get detailed sync status for a specific thread.


        Returns watermarks, progress, and health metrics.'
      operationId: get_thread_sync_status_api_threads__thread_id__sync_status_get
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: integer
          title: Thread Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThreadSyncStatus'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/threads/{thread_id}/backfill-history:
    post:
      tags:
      - sync-admin
      summary: Trigger Backfill History
      description: 'Trigger LWM backfill for thread (load older historical messages).


        This is an on-demand operation triggered when:

        - User scrolls to top of thread

        - User searches within thread history

        - User explicitly requests "Load full history"


        The backfill runs in background and updates lwm_progress_id.'
      operationId: trigger_backfill_history_api_threads__thread_id__backfill_history_post
      parameters:
      - name: thread_id
        in: path
        required: true
        schema:
          type: integer
          title: Thread Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackfillHistoryRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackfillHistoryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/sync/admin/phonebook-discovery:
    get:
      tags:
      - sync-admin
      summary: Get Phonebook Discovery Status
      description: Get phone book discovery status for all Telegram accounts.
      operationId: get_phonebook_discovery_status_api_sync_admin_phonebook_discovery_get
      parameters:
      - name: user_id
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          description: Filter by user ID
          title: User Id
        description: Filter by user ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/sync/workers/phonebook-discovery/status:
    get:
      tags:
      - sync-admin
      summary: Get Phonebook Discovery Worker Status
      description: Get phonebook discovery worker status from channel-sync-service.
      operationId: get_phonebook_discovery_worker_status_api_sync_workers_phonebook_discovery_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/sync/admin/phonebook-discovery/{account_id}/restart:
    post:
      tags:
      - sync-admin
      summary: Restart Phonebook Discovery
      description: Restart phone book discovery for a Telegram account.
      operationId: restart_phonebook_discovery_api_sync_admin_phonebook_discovery__account_id__restart_post
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: integer
          title: Account Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ThreadSyncStatus:
      properties:
        thread_id:
          type: integer
          title: Thread Id
        title:
          type: string
          title: Title
        channel:
          type: string
          title: Channel
        kind:
          type: string
          title: Kind
        state:
          type: string
          title: State
        hwm_msg_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Hwm Msg Id
        hwm_ts:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Hwm Ts
        hwm_established_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Hwm Established At
        lwm_msg_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Lwm Msg Id
        lwm_ts:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Lwm Ts
        lwm_progress_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Lwm Progress Id
        has_full_history:
          type: boolean
          title: Has Full History
        messages_synced:
          type: integer
          title: Messages Synced
        message_cap:
          anyOf:
          - type: integer
          - type: 'null'
          title: Message Cap
        last_sync_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Sync At
        lag_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Lag Seconds
        error_count:
          type: integer
          title: Error Count
        last_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Error
        health_status:
          type: string
          title: Health Status
      type: object
      required:
      - thread_id
      - title
      - channel
      - kind
      - state
      - hwm_msg_id
      - hwm_ts
      - hwm_established_at
      - lwm_msg_id
      - lwm_ts
      - lwm_progress_id
      - has_full_history
      - messages_synced
      - message_cap
      - last_sync_at
      - lag_seconds
      - error_count
      - last_error
      - health_status
      title: ThreadSyncStatus
      description: Sync status for a single thread.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BackfillHistoryResponse:
      properties:
        status:
          type: string
          title: Status
        thread_id:
          type: integer
          title: Thread Id
        task_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Id
        message:
          type: string
          title: Message
        estimated_messages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Estimated Messages
      type: object
      required:
      - status
      - thread_id
      - task_id
      - message
      - estimated_messages
      title: BackfillHistoryResponse
      description: Response from backfill request.
    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
    BackfillHistoryRequest:
      properties:
        max_messages:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Messages
          default: 500
        priority:
          type: string
          title: Priority
          default: normal
      type: object
      title: BackfillHistoryRequest
      description: Request to backfill historical messages.