Wispr AI Notetaker Chats API

openapi: 3.0.3
info:
  title: Wispr Backend Analytics Notetaker Chats API
  description: Wispr Backend API
  version: 0.5.2
tags:
- name: Notetaker Chats
paths:
  /api/v1/notetaker-chats/upload:
    post:
      tags:
      - Notetaker Chats
      summary: Upload Notetaker Chats
      description: "Upload chat mutations when Cloud Sync is enabled.\n\nReferenced meetings are validated up front, so a missing or unowned meeting\nrejects the entire batch before any write. Each chat then commits\nindependently; a mid-batch conflict can leave earlier chats persisted.\nClients should retry the whole batch because revisions are idempotent.\n\nArgs:\n    body: Batch of chat mutations to upload.\n    user: Authenticated owner of the chats and referenced meetings.\n    db:   Main database executor used for meeting validation.\n\nReturns:\n    Acknowledgements for every successfully applied chat mutation.\n\nRaises:\n    HTTPException:\n        403: Cloud Sync is disabled.\n        404: A referenced meeting is missing or not owned by the caller.\n        409: A chat mutation conflicts with canonical state."
      operationId: upload_notetaker_chats
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadNotetakerChatsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadNotetakerChatsResponse'
        '403':
          description: Cloud Sync is disabled
        '404':
          description: Meeting missing or not owned; batch rejected before any chat write
        '409':
          description: Identifier conflict; earlier chats may be persisted, so retry the whole batch
        '429':
          description: Too Many Requests
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - ApiKeyHeaderPatched: []
  /api/v1/notetaker-chats:
    get:
      tags:
      - Notetaker Chats
      summary: List Notetaker Chats
      description: 'List hub or meeting-scoped sessions, newest activity first.


        Omit ``cursor`` for the most recent page; pass ``next_cursor`` to continue

        into older sessions.'
      operationId: list_notetaker_chats
      security:
      - ApiKeyHeaderPatched: []
      parameters:
      - name: scope
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/NotetakerChatScope'
          default: hub
      - name: meeting_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Meeting Id
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotetakerChatsResponse'
        '403':
          description: Cloud Sync is disabled
        '429':
          description: Too Many Requests
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/notetaker-chats/{chat_id}/messages:
    get:
      tags:
      - Notetaker Chats
      summary: List Notetaker Chat Messages
      description: 'Load messages for one session, newest page first.


        Response pages are chronological within the page. Pass ``next_cursor`` to

        fetch older messages as the user scrolls up.'
      operationId: list_notetaker_chat_messages
      security:
      - ApiKeyHeaderPatched: []
      parameters:
      - name: chat_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Chat Id
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 100
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotetakerChatMessagesResponse'
        '403':
          description: Cloud Sync is disabled
        '404':
          description: Chat not found
        '429':
          description: Too Many Requests
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/notetaker-chats/{chat_id}:
    delete:
      tags:
      - Notetaker Chats
      summary: Delete Notetaker Chat
      description: Delete a chat even after Cloud Sync has been disabled.
      operationId: delete_notetaker_chat
      security:
      - ApiKeyHeaderPatched: []
      parameters:
      - name: chat_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Chat Id
      responses:
        '204':
          description: Successful Response
        '429':
          description: Too Many Requests
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    JsonValue: {}
    NotetakerChatKind:
      type: string
      enum:
      - L2
      - meeting_chat
      title: NotetakerChatKind
      description: Product surface that owns a persisted Notetaker chat session.
    ListNotetakerChatsResponse:
      properties:
        chats:
          items:
            $ref: '#/components/schemas/NotetakerChatRecord'
          type: array
          title: Chats
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - chats
      title: ListNotetakerChatsResponse
      description: 'Keyset-paginated Notetaker chat sessions (newest first).


        ``next_cursor`` anchors the oldest row of this page and loads still-older

        chats on the next request. ``null`` means there is no older page.'
    NotetakerChatMessageRole:
      type: string
      enum:
      - user
      - assistant
      title: NotetakerChatMessageRole
      description: Participant role for a persisted Notetaker chat message.
    NotetakerChatUpload:
      properties:
        chat_id:
          type: string
          format: uuid
          title: Chat Id
        kind:
          $ref: '#/components/schemas/NotetakerChatKind'
        meeting_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Meeting Id
        title:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Title
        deleted:
          type: boolean
          title: Deleted
          default: false
        messages:
          items:
            $ref: '#/components/schemas/NotetakerChatMessageUpload'
          type: array
          title: Messages
      type: object
      required:
      - chat_id
      - kind
      title: NotetakerChatUpload
      description: One atomic chat mutation and its bounded message batch.
    UploadNotetakerChatsResponse:
      properties:
        chats:
          items:
            $ref: '#/components/schemas/NotetakerChatUploadAck'
          type: array
          title: Chats
      type: object
      required:
      - chats
      title: UploadNotetakerChatsResponse
      description: Per-chat acknowledgements for an upload batch.
    ListNotetakerChatMessagesResponse:
      properties:
        messages:
          items:
            $ref: '#/components/schemas/NotetakerChatMessageRecord'
          type: array
          title: Messages
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - messages
      title: ListNotetakerChatMessagesResponse
      description: 'Keyset-paginated messages for one session.


        Each page is chronological (oldest→newest within the page) so the client

        can append the first page at the bottom and prepend later pages when

        scrolling up. ``next_cursor`` is the oldest sequence index on this page.'
    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
    NotetakerChatMessageUpload:
      properties:
        message_id:
          type: string
          format: uuid
          title: Message Id
        turn_id:
          type: string
          format: uuid
          title: Turn Id
        role:
          $ref: '#/components/schemas/NotetakerChatMessageRole'
        status:
          $ref: '#/components/schemas/NotetakerChatMessageStatus'
        content:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          type: object
          title: Content
        metadata:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/JsonValue'
            type: object
          - type: 'null'
          title: Metadata
        feedback:
          anyOf:
          - $ref: '#/components/schemas/NotetakerChatFeedback'
          - type: 'null'
      type: object
      required:
      - message_id
      - turn_id
      - role
      - status
      - content
      title: NotetakerChatMessageUpload
      description: One client message mutation.
    NotetakerChatMessageStatus:
      type: string
      enum:
      - pending
      - succeeded
      - request_timeout
      - request_error
      - tool_error
      - cancelled
      - superseded
      - no_text
      - not_editable
      - interrupted
      title: NotetakerChatMessageStatus
      description: Notetaker-specific terminal and in-flight message outcomes.
    UploadNotetakerChatsRequest:
      properties:
        chats:
          items:
            $ref: '#/components/schemas/NotetakerChatUpload'
          type: array
          maxItems: 20
          minItems: 1
          title: Chats
      type: object
      required:
      - chats
      title: UploadNotetakerChatsRequest
      description: 'Bounded upload batch with an independent commit per chat.


        Meeting ownership is validated for the whole batch before any write. A

        mid-batch conflict can leave earlier chats persisted; retry the whole

        batch (revisions are idempotent).'
    NotetakerChatUploadAck:
      properties:
        chat_id:
          type: string
          format: uuid
          title: Chat Id
        messages:
          items:
            $ref: '#/components/schemas/NotetakerChatMessageAck'
          type: array
          title: Messages
      type: object
      required:
      - chat_id
      - messages
      title: NotetakerChatUploadAck
      description: Canonical state acknowledged for one uploaded chat.
    NotetakerChatMessageRecord:
      properties:
        message_id:
          type: string
          format: uuid
          title: Message Id
        chat_id:
          type: string
          format: uuid
          title: Chat Id
        turn_id:
          type: string
          format: uuid
          title: Turn Id
        sequence_index:
          type: integer
          title: Sequence Index
        role:
          $ref: '#/components/schemas/NotetakerChatMessageRole'
        status:
          $ref: '#/components/schemas/NotetakerChatMessageStatus'
        content:
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          type: object
          title: Content
        metadata:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/JsonValue'
            type: object
          - type: 'null'
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - message_id
      - chat_id
      - turn_id
      - sequence_index
      - role
      - status
      - content
      - metadata
      - created_at
      title: NotetakerChatMessageRecord
      description: One canonical server-ordered chat message.
    NotetakerChatMessageAck:
      properties:
        message_id:
          type: string
          format: uuid
          title: Message Id
        sequence_index:
          type: integer
          title: Sequence Index
      type: object
      required:
      - message_id
      - sequence_index
      title: NotetakerChatMessageAck
      description: Canonical sequence index acknowledged for a message.
    NotetakerChatFeedback:
      properties:
        rating:
          type: string
          enum:
          - up
          - down
          title: Rating
        text:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Text
      type: object
      required:
      - rating
      title: NotetakerChatFeedback
      description: Optional assistant-message rating and explanation.
    NotetakerChatRecord:
      properties:
        chat_id:
          type: string
          format: uuid
          title: Chat Id
          description: Client-generated chat session id; stable across upload and list.
        kind:
          $ref: '#/components/schemas/NotetakerChatKind'
        meeting_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Meeting Id
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        last_message_sequence_index:
          type: integer
          title: Last Message Sequence Index
          description: Highest server-assigned message sequence index in this chat (0 if empty).
        created_at:
          type: string
          format: date-time
          title: Created At
        modified_at:
          type: string
          format: date-time
          title: Modified At
      type: object
      required:
      - chat_id
      - kind
      - meeting_id
      - title
      - last_message_sequence_index
      - created_at
      - modified_at
      title: NotetakerChatRecord
      description: One active Notetaker chat session.
    NotetakerChatScope:
      type: string
      enum:
      - hub
      - meeting
      title: NotetakerChatScope
      description: History filtering mode for listing Notetaker chat sessions.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    ApiKeyHeaderPatched:
      type: apiKey
      in: header
      name: Authorization
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key