> ## Documentation Index
> Fetch the complete documentation index at: https://help.harmonica.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# List owned meetings

> Lists only personal calendar meetings owned by the API-key user. Project
membership never expands this catalogue. Results include compact transcript
currentness, processing provenance, safe restriction scopes, and Project
attachment counts without transcript text. Provider speaker labels remain
unverified source labels and do not establish identity across recordings.




## OpenAPI

````yaml /api-reference/openapi.yaml get /meetings
openapi: 3.1.0
info:
  title: Harmonica API
  version: 1.0.0
  description: >
    REST API for the Harmonica structured deliberation platform.

    Provides access to sessions and their data, including creating, updating,
    and querying sessions, plus response submission for active sessions.
  contact:
    name: Harmonica
    url: https://harmonica.chat
servers:
  - url: https://app.harmonica.chat/api/v1
    description: Production
  - url: http://localhost:3000/api/v1
    description: Local development
security:
  - apiKey: []
paths:
  /meetings:
    get:
      tags:
        - Meetings
      summary: List owned meetings
      description: >
        Lists only personal calendar meetings owned by the API-key user. Project

        membership never expands this catalogue. Results include compact
        transcript

        currentness, processing provenance, safe restriction scopes, and Project

        attachment counts without transcript text. Provider speaker labels
        remain

        unverified source labels and do not establish identity across
        recordings.
      operationId: listMeetings
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum:
              - scheduled
              - joining
              - in_call
              - recording
              - transcribing
              - ready
              - failed
              - cancelled
        - name: provider
          in: query
          schema:
            type: string
            enum:
              - google_meet
              - zoom
              - microsoft_teams
        - name: attachment
          in: query
          description: Filter by whether the meeting is attached to at least one Project.
          schema:
            type: string
            enum:
              - attached
              - unattached
        - name: from
          in: query
          description: Include meetings starting at or after this timestamp.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: Include meetings starting before this timestamp.
          schema:
            type: string
            format: date-time
        - name: updated_since
          in: query
          description: Include meetings updated at or after this timestamp.
          schema:
            type: string
            format: date-time
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: >-
            Legacy offset pagination. Cannot be combined with a non-first-page
            cursor.
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: cursor
          in: query
          description: Opaque stable cursor returned by the previous meeting page.
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: Owner-scoped meeting page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeetingListResponse'
        '400':
          description: Invalid filter, date range, or cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    MeetingListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MeetingListItem'
        pagination:
          type: object
          properties:
            total:
              type: integer
              minimum: 0
            limit:
              type: integer
              minimum: 1
              maximum: 100
            offset:
              type: integer
              minimum: 0
            next_cursor:
              type: string
              nullable: true
          required:
            - total
            - limit
            - offset
            - next_cursor
      required:
        - data
        - pagination
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - not_found
                - validation_error
                - rate_limited
                - payment_required
                - transcript_revision_changed
                - internal_error
                - unprocessable
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
    MeetingListItem:
      allOf:
        - $ref: '#/components/schemas/Meeting'
        - type: object
          properties:
            transcript_status:
              type: string
              enum:
                - processing
                - ready
                - failed
              nullable: true
            transcript_language:
              type: string
              nullable: true
            has_transcript:
              type: boolean
            empty_transcript:
              type: boolean
            utterance_count:
              type: integer
              minimum: 0
            speaker_count:
              type: integer
              minimum: 0
            actual_duration_ms:
              type: integer
              minimum: 0
              nullable: true
            effective_restriction_scopes:
              type: array
              items:
                type: string
                enum:
                  - synthesis
                  - project_attachment
                  - external_export
                  - sharing
                  - all_downstream_processing
            project_attachment_count:
              type: integer
              minimum: 0
            transcript:
              allOf:
                - $ref: '#/components/schemas/MeetingTranscriptMetadata'
              nullable: true
          required:
            - transcript_status
            - transcript_language
            - has_transcript
            - empty_transcript
            - utterance_count
            - speaker_count
            - actual_duration_ms
            - effective_restriction_scopes
            - project_attachment_count
            - transcript
    Meeting:
      type: object
      description: >-
        Calendar meeting metadata. Direct Project-derived reads redact
        meeting_url and raw error_message to null.
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        meeting_url:
          type: string
          format: uri
          nullable: true
        meeting_provider:
          type: string
          enum:
            - google_meet
            - zoom
            - microsoft_teams
        starts_at:
          type: string
          format: date-time
        ends_at:
          type: string
          format: date-time
          nullable: true
        timezone:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - scheduled
            - joining
            - in_call
            - recording
            - transcribing
            - ready
            - failed
            - cancelled
        error_code:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
          description: >-
            Raw meeting failure detail for the owner; null for Project-derived
            readers.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - title
        - meeting_url
        - meeting_provider
        - starts_at
        - ends_at
        - timezone
        - status
        - error_code
        - error_message
        - created_at
        - updated_at
    MeetingTranscriptMetadata:
      type: object
      properties:
        id:
          type: string
          format: uuid
        meeting_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - processing
            - ready
            - failed
        availability:
          type: string
          enum:
            - pending
            - ready
            - retryable_failure
            - terminal_failure
            - restricted
        language:
          type: string
          nullable: true
        revision:
          type: integer
          minimum: 1
          nullable: true
          description: Advances only when canonical transcript content changes.
        content_hash:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
          nullable: true
        restriction_revision:
          type: string
          pattern: ^\d+$
          description: >-
            Latest restriction event sequence, or "0". Cache checks compare this
            with content_hash.
        completed_at:
          type: string
          format: date-time
          nullable: true
        source:
          $ref: '#/components/schemas/TranscriptSourceProvenance'
        processing:
          $ref: '#/components/schemas/TranscriptProcessingProvenance'
      required:
        - id
        - meeting_id
        - status
        - availability
        - language
        - revision
        - content_hash
        - restriction_revision
        - completed_at
        - source
        - processing
    TranscriptSourceProvenance:
      type: object
      properties:
        kind:
          type: string
          enum:
            - harmonica_capture
            - provider_import
            - manual_import
        provider:
          type: string
          description: >-
            Source provider name. Provider names are extensible rather than a
            closed enum.
      required:
        - kind
        - provider
    TranscriptProcessingProvenance:
      type: object
      properties:
        provider:
          type: string
        model:
          type: string
        normalization_version:
          type: string
        attempt_status:
          type: string
          enum:
            - pending
            - processing
            - succeeded
            - failed
        failure_stage:
          type: string
          enum:
            - capture
            - transcription
            - normalization
            - persistence
            - unknown
          nullable: true
        failure_disposition:
          type: string
          enum:
            - retryable
            - terminal
          nullable: true
        error_code:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
          description: >-
            Raw detail for the owner; Project-derived readers receive only a
            safe generic message.
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
      required:
        - provider
        - model
        - normalization_version
        - attempt_status
        - failure_stage
        - failure_disposition
        - error_code
        - error_message
        - started_at
        - completed_at
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid or missing API key
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        API key authentication. Pass your key as a Bearer token.
        Keys use the format `hm_live_<32 hex chars>`.
        Generate keys from your Harmonica dashboard settings.

````