dialogbrain-com Workspace Analytics API

openapi: 3.2.0
info:
  title: DialogBrain v2 API Gateway Workspace Analytics API
  description: Clean refactored API gateway with minimal vertical slice
  version: 0.1.0
tags:
- name: workspace-analytics
paths:
  /api/workspace/analytics/query:
    post:
      tags:
      - workspace-analytics
      summary: Ephemeral Query
      description: 'Run an ad-hoc NL question with 2-attempt generate→run retry loop.


        Does not persist. Returns SQL, chart metadata, and result rows (truncated if >200).'
      operationId: ephemeral_query_api_workspace_analytics_query_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/src__api__workspace_analytics__QueryRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/team:
    get:
      tags:
      - workspace-analytics
      summary: Team Report
      description: 'How each person on the team worked in [since, until) (services/team_report).

        Owner and admins only: what each colleague did is a manager''s view.'
      operationId: team_report_api_workspace_analytics_team_get
      parameters:
      - name: since
        in: query
        required: true
        schema:
          type: string
          format: date-time
          title: Since
      - name: until
        in: query
        required: true
        schema:
          type: string
          format: date-time
          title: Until
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/cards:
    get:
      tags:
      - workspace-analytics
      summary: List Cards
      description: 'List all pinned dashboard cards for this workspace. The team card is

        put there for an owner or admin the first time, and shown only to them.'
      operationId: list_cards_api_workspace_analytics_cards_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
    post:
      tags:
      - workspace-analytics
      summary: Create Card
      description: 'Create a new pinned dashboard card.


        SQL is guard-validated (shape + allowlist). Card is appended to the bottom

        of the grid (y = max(y+h) of existing cards).'
      operationId: create_card_api_workspace_analytics_cards_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/cards/{card_id}:
    patch:
      tags:
      - workspace-analytics
      summary: Patch Card
      description: 'Update a pinned card''s title, chart, and/or SQL.


        SQL (if provided) is guard-validated. updated_at is set automatically.'
      operationId: patch_card_api_workspace_analytics_cards__card_id__patch
      parameters:
      - name: card_id
        in: path
        required: true
        schema:
          type: integer
          title: Card Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - workspace-analytics
      summary: Delete Card
      description: 'Delete a pinned card. The team card is only taken off the dashboard

        (kept as ''team_removed''), so it is not put back the next time.'
      operationId: delete_card_api_workspace_analytics_cards__card_id__delete
      parameters:
      - name: card_id
        in: path
        required: true
        schema:
          type: integer
          title: Card Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/cards/{card_id}/run:
    post:
      tags:
      - workspace-analytics
      summary: Run Card
      description: 'Run a pinned card''s SQL and return result rows.


        Single-shot execution (no regeneration). Raises 422 on run failure.'
      operationId: run_card_api_workspace_analytics_cards__card_id__run_post
      parameters:
      - name: card_id
        in: path
        required: true
        schema:
          type: integer
          title: Card Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/cards/{card_id}/regenerate:
    post:
      tags:
      - workspace-analytics
      summary: Regenerate Card
      description: 'Regenerate a card''s SQL from its question with 2-attempt generate→run loop.


        Persists updated SQL and chart ONLY after a successful run. Failed regenerations

        leave the card untouched (never bricked).'
      operationId: regenerate_card_api_workspace_analytics_cards__card_id__regenerate_post
      parameters:
      - name: card_id
        in: path
        required: true
        schema:
          type: integer
          title: Card Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/cards/layout:
    put:
      tags:
      - workspace-analytics
      summary: Save Layout
      description: 'Bulk update layout for multiple cards.


        Each card is scoped to the current workspace. Cross-tenant items silently no-op.'
      operationId: save_layout_api_workspace_analytics_cards_layout_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LayoutSave'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/cards/{card_id}/schedules:
    post:
      tags:
      - workspace-analytics
      summary: Create Schedule
      description: 'Create a new schedule for a card to run on a recurrence.


        Validates card and thread are in the workspace, computes next_run_at,

        and inserts the schedule.'
      operationId: create_schedule_api_workspace_analytics_cards__card_id__schedules_post
      parameters:
      - name: card_id
        in: path
        required: true
        schema:
          type: integer
          title: Card Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScheduleCreate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - workspace-analytics
      summary: List Card Schedules
      description: List all schedules for a card.
      operationId: list_card_schedules_api_workspace_analytics_cards__card_id__schedules_get
      parameters:
      - name: card_id
        in: path
        required: true
        schema:
          type: integer
          title: Card Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/schedules:
    get:
      tags:
      - workspace-analytics
      summary: List Workspace Schedules
      description: List all schedules in the workspace.
      operationId: list_workspace_schedules_api_workspace_analytics_schedules_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/workspace/analytics/schedules/{schedule_id}:
    patch:
      tags:
      - workspace-analytics
      summary: Patch Schedule
      description: 'Update a schedule''s properties.


        Recomputes next_run_at if schedule fields change. Sets updated_at=now().

        If resuming (status=''active'' from paused), clears consecutive_failures.'
      operationId: patch_schedule_api_workspace_analytics_schedules__schedule_id__patch
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: integer
          title: Schedule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SchedulePatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - workspace-analytics
      summary: Delete Schedule
      description: Delete a schedule.
      operationId: delete_schedule_api_workspace_analytics_schedules__schedule_id__delete
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: integer
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/workspace/analytics/schedules/{schedule_id}/test:
    post:
      tags:
      - workspace-analytics
      summary: Test Schedule
      description: 'Test-run a schedule: load card+thread, run SQL, format, and send.


        Returns a preview of what would be sent. Does NOT modify next_run_at.'
      operationId: test_schedule_api_workspace_analytics_schedules__schedule_id__test_post
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: integer
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    src__api__workspace_analytics__QueryRequest:
      properties:
        question:
          type: string
          title: Question
      type: object
      required:
      - question
      title: QueryRequest
    LayoutSave:
      properties:
        items:
          items:
            $ref: '#/components/schemas/LayoutItem'
          type: array
          title: Items
      type: object
      required:
      - items
      title: LayoutSave
    SchedulePatch:
      properties:
        frequency:
          anyOf:
          - type: string
            enum:
            - daily
            - weekly
            - monthly
          - type: 'null'
          title: Frequency
        day_of_week:
          anyOf:
          - type: integer
          - type: 'null'
          title: Day Of Week
        day_of_month:
          anyOf:
          - type: integer
          - type: 'null'
          title: Day Of Month
        time_of_day:
          anyOf:
          - type: string
          - type: 'null'
          title: Time Of Day
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
        status:
          anyOf:
          - type: string
            enum:
            - active
            - paused
          - type: 'null'
          title: Status
      type: object
      title: SchedulePatch
    ScheduleCreate:
      properties:
        thread_id:
          type: integer
          title: Thread Id
        frequency:
          type: string
          enum:
          - daily
          - weekly
          - monthly
          title: Frequency
        day_of_week:
          anyOf:
          - type: integer
          - type: 'null'
          title: Day Of Week
        day_of_month:
          anyOf:
          - type: integer
          - type: 'null'
          title: Day Of Month
        time_of_day:
          type: string
          title: Time Of Day
        timezone:
          type: string
          title: Timezone
      type: object
      required:
      - thread_id
      - frequency
      - time_of_day
      - timezone
      title: ScheduleCreate
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CardPatch:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        chart:
          anyOf:
          - $ref: '#/components/schemas/ChartSpec'
          - type: 'null'
        sql:
          anyOf:
          - type: string
          - type: 'null'
          title: Sql
      type: object
      title: CardPatch
    LayoutItem:
      properties:
        id:
          type: integer
          title: Id
        x:
          type: integer
          title: X
        y:
          type: integer
          title: Y
        w:
          type: integer
          title: W
        h:
          type: integer
          title: H
      type: object
      required:
      - id
      - x
      - y
      - w
      - h
      title: LayoutItem
    CardCreate:
      properties:
        title:
          type: string
          title: Title
        question:
          type: string
          title: Question
        sql:
          type: string
          title: Sql
        chart:
          $ref: '#/components/schemas/ChartSpec'
        source:
          type: string
          enum:
          - workspace
          - database
          title: Source
          default: workspace
      type: object
      required:
      - title
      - question
      - sql
      - chart
      title: CardCreate
    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
    ChartSpec:
      properties:
        type:
          type: string
          enum:
          - number
          - table
          - bar
          - hbar
          - line
          - area
          - pie
          title: Type
        x:
          anyOf:
          - type: string
          - type: 'null'
          title: X
        y:
          anyOf:
          - type: string
          - type: 'null'
          title: Y
      type: object
      required:
      - type
      title: ChartSpec
      description: 'Chart configuration: type + optional x/y column names.'