Clarify Meeting Recordings API

openapi: 3.2.0
info:
  title: Clarify Meeting Recordings API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
tags:
- name: MeetingRecordings
paths:
  /workspaces/{workspace}/meetings/{meetingId}/recording:
    post:
      description: Turns on recording for a meeting so a notetaker bot joins the call. Returns the updated meeting record.
      operationId: enableRecording
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: meetingId
        required: true
        in: path
        description: The unique ID of the meeting.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '201':
          description: The meeting with recording enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
              example:
                data:
                  type: meeting
                  id: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                  attributes:
                    _id: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                    title: Acme Renewal QBR
                    start: '2026-02-01T17:00:00.000Z'
                    end: '2026-02-01T17:30:00.000Z'
                    recording_enabled: true
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Enable meeting recording
      tags:
      - MeetingRecordings
    delete:
      description: Turns off recording for a meeting so no notetaker bot joins the call. Returns the updated meeting record.
      operationId: disableRecording
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: meetingId
        required: true
        in: path
        description: The unique ID of the meeting.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '200':
          description: The meeting with recording disabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
              example:
                data:
                  type: meeting
                  id: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                  attributes:
                    _id: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                    title: Acme Renewal QBR
                    start: '2026-02-01T17:00:00.000Z'
                    end: '2026-02-01T17:30:00.000Z'
                    recording_enabled: false
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Disable meeting recording
      tags:
      - MeetingRecordings
  /workspaces/{workspace}/meetings/{meetingId}/recordings/{id}/artifacts:
    post:
      description: Returns short-lived signed URLs for a recording’s video and transcript files. Either URL is `null` when that artifact is not available.
      operationId: getRecordingArtifacts
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: meetingId
        required: true
        in: path
        description: The unique ID of the meeting.
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the recording.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '201':
          description: The recording’s signed artifact URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingArtifactResponse'
              example:
                data:
                  videoUrl: https://storage.clarify.ai/recordings/acme/2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62/video.mp4?signature=...
                  transcriptionUrl: https://storage.clarify.ai/recordings/acme/2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62/transcript.json?signature=...
      summary: Get recording artifacts
      tags:
      - MeetingRecordings
  /workspaces/{workspace}/meetings/{meetingId}/recordings/transcript:
    post:
      description: Creates a recording on the meeting from an externally captured transcript, so meetings recorded outside Clarify can be summarized and searched, and triggers summary generation. A meeting with a recording already gets a second recording. Pass `recordingId` to overwrite a completed manual-upload recording’s transcript instead. Returns the recording.
      operationId: uploadRecordingTranscript
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: meetingId
        required: true
        in: path
        description: The unique ID of the meeting.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadRecordingTranscriptDto'
            examples:
              upload:
                summary: Upload a two-word transcript segment
                value:
                  transcript:
                  - speaker: Jane Doe
                    speaker_id: 1
                    language: en
                    words:
                    - text: Thanks
                      start_timestamp: 0
                      end_timestamp: 0.4
                      language: en
                      confidence: 0.98
                    - text: everyone
                      start_timestamp: 0.4
                      end_timestamp: 0.9
                      language: en
                      confidence: 0.97
      responses:
        '201':
          description: The created meeting recording.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
              example:
                data:
                  type: meeting_recording
                  id: 2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62
                  attributes:
                    _id: 2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62
                    meeting_id: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                    recording_source: manual_upload
                    status: Done
                    start_at: '2026-02-01T17:00:00.000Z'
                    end_at: '2026-02-01T17:30:00.000Z'
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Upload a recording transcript
      tags:
      - MeetingRecordings
  /workspaces/{workspace}/meetings/{meetingId}/recordings/media:
    post:
      description: Creates a pending recording on the meeting and returns a presigned S3 POST policy for uploading an audio or video file directly to storage. Uploaded media is stored for playback and is not transcribed. Optionally include a transcript in the same request so one recording carries both video and transcript. Submit the file to the returned policy, then confirm the upload. Pass `recordingId` to overwrite a completed manual-upload recording instead of creating a new one.
      operationId: initMediaUpload
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: meetingId
        required: true
        in: path
        description: The unique ID of the meeting.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitRecordingMediaDto'
            examples:
              upload:
                summary: Start an mp4 video upload
                value:
                  contentType: video/mp4
      responses:
        '201':
          description: The pending recording and the presigned upload policy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitRecordingMediaResponse'
              example:
                data:
                  recordingId: 2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62
                  meetingId: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                  key: acme/manual/2026-02-01/2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62/recording-7e71a013-1341-4472-a54d-63d81a56b5dd.mp4
                  upload:
                    url: https://storage.clarify.ai/meeting-recordings
                    fields:
                      key: acme/manual/2026-02-01/2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62/recording-7e71a013-1341-4472-a54d-63d81a56b5dd.mp4
                      Content-Type: video/mp4
                      policy: '...'
                      x-amz-signature: '...'
      summary: Start a recording media upload
      tags:
      - MeetingRecordings
  /workspaces/{workspace}/meetings/{meetingId}/recordings/media/{recordingId}:
    post:
      description: 'Finalizes a media upload after the file has been submitted to the presigned policy: validates the stored object and marks the recording complete. Returns the finalized recording.'
      operationId: confirmMediaUpload
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: meetingId
        required: true
        in: path
        description: The unique ID of the meeting.
        schema:
          type: string
      - name: recordingId
        required: true
        in: path
        description: The unique ID of the recording.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '200':
          description: The finalized meeting recording.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
              example:
                data:
                  type: meeting_recording
                  id: 2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62
                  attributes:
                    _id: 2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62
                    meeting_id: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                    recording_source: manual_upload
                    status: Done
                    start_at: '2026-02-01T17:00:00.000Z'
                    end_at: '2026-02-01T17:30:00.000Z'
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Confirm a recording media upload
      tags:
      - MeetingRecordings
  /workspaces/{workspace}/meetings/{meetingId}/transcript:
    post:
      deprecated: true
      description: Creates a recording for a meeting from an externally captured transcript, so meetings recorded outside Clarify can be summarized and searched. Returns the created recording.
      operationId: uploadTranscript
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: meetingId
        required: true
        in: path
        description: The unique ID of the meeting.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UploadTranscriptDto'
            examples:
              upload:
                summary: Upload a two-word transcript segment
                value:
                  transcript:
                  - speaker: Jane Doe
                    speaker_id: 1
                    language: en
                    words:
                    - text: Thanks
                      start_timestamp: 0
                      end_timestamp: 0.4
                      language: en
                      confidence: 0.98
                    - text: everyone
                      start_timestamp: 0.4
                      end_timestamp: 0.9
                      language: en
                      confidence: 0.97
      responses:
        '201':
          description: The created meeting recording.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordResponse'
              example:
                data:
                  type: meeting_recording
                  id: 2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62
                  attributes:
                    _id: 2f7a9c1e-4b6d-4e8a-9c0f-1d3b5e7a9c62
                    meeting_id: 6c8e0a2b-4d5f-4a7b-9c1d-3e5f7a9b1c2d
                    recording_source: manual_upload
                    status: Done
                    start_at: '2026-02-01T17:00:00.000Z'
                    end_at: '2026-02-01T17:30:00.000Z'
                    _created_at: '2026-01-15T09:30:00.000Z'
                    _updated_at: '2026-02-01T17:45:00.000Z'
      summary: Upload a meeting transcript
      tags:
      - MeetingRecordings
components:
  schemas:
    InitRecordingMediaDto:
      type: object
      properties:
        recordingId:
          type: string
          format: uuid
          description: A completed manual-upload recording to overwrite. When omitted, a new recording is created on the meeting. Only the artifacts supplied in this request are overwritten; other stored artifacts are left intact.
        contentType:
          type: string
          pattern: ^(audio|video)\/
          description: The MIME type of the media file to upload; must be an `audio/*` or `video/*` type. Uploaded media is stored for playback and is not transcribed.
        transcript:
          type: array
          items:
            type: object
            properties:
              words:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                      description: The transcribed word.
                    start_timestamp:
                      type: number
                      description: The start time of the word, in seconds from the beginning of the recording.
                    end_timestamp:
                      type: number
                      description: The end time of the word, in seconds from the beginning of the recording.
                    language:
                      type: string
                      nullable: true
                      description: The detected language of the word as an ISO code, or `null` if unknown.
                    confidence:
                      type: number
                      nullable: true
                      description: The transcription confidence for the word, from 0 to 1, or `null` if unavailable.
                  required:
                  - text
                  - start_timestamp
                  - end_timestamp
                  - language
                  - confidence
                description: The words spoken in this segment.
              speaker:
                type: string
                nullable: true
                description: The display name of the speaker, or `null` if unattributed.
              speaker_id:
                type: number
                nullable: true
                description: The numeric ID of the speaker, or `null` if unattributed.
              language:
                type: string
                description: The primary language of the segment as an ISO code.
            required:
            - words
            - speaker
            - speaker_id
            - language
          description: An optional transcript to attach to the same recording as the media, so one recording carries both. Applied to the recording when the upload is confirmed, then used to generate the summary.
      required:
      - contentType
    RecordingArtifactResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            videoUrl:
              type: string
              nullable: true
              description: A short-lived signed URL for the recording’s video file, or `null` if no video is available.
            transcriptionUrl:
              type: string
              nullable: true
              description: A short-lived signed URL for the recording’s transcript file, or `null` if no transcript is available.
          required:
          - videoUrl
          - transcriptionUrl
          description: The recording’s signed artifact URLs.
      required:
      - data
    UploadRecordingTranscriptDto:
      type: object
      properties:
        recordingId:
          type: string
          format: uuid
          description: A completed manual-upload recording to overwrite. When omitted, a new recording is created on the meeting. Only the artifacts supplied in this request are overwritten; other stored artifacts are left intact.
        transcript:
          type: array
          items:
            type: object
            properties:
              words:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                      description: The transcribed word.
                    start_timestamp:
                      type: number
                      description: The start time of the word, in seconds from the beginning of the recording.
                    end_timestamp:
                      type: number
                      description: The end time of the word, in seconds from the beginning of the recording.
                    language:
                      type: string
                      nullable: true
                      description: The detected language of the word as an ISO code, or `null` if unknown.
                    confidence:
                      type: number
                      nullable: true
                      description: The transcription confidence for the word, from 0 to 1, or `null` if unavailable.
                  required:
                  - text
                  - start_timestamp
                  - end_timestamp
                  - language
                  - confidence
                description: The words spoken in this segment.
              speaker:
                type: string
                nullable: true
                description: The display name of the speaker, or `null` if unattributed.
              speaker_id:
                type: number
                nullable: true
                description: The numeric ID of the speaker, or `null` if unattributed.
              language:
                type: string
                description: The primary language of the segment as an ISO code.
            required:
            - words
            - speaker
            - speaker_id
            - language
          description: The meeting transcript, as an ordered list of speaker segments.
      required:
      - transcript
    RecordResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
              - record
              description: The resource type; matches the `object` path parameter.
            id:
              type: string
              description: The unique ID of the resource.
            attributes:
              type: object
              properties: {}
              description: Field values keyed by field name; available fields depend on the object’s schema.
            relationships:
              type: object
              properties: {}
              description: Related resources keyed by relationship name, present when requested via `include`.
            meta:
              type: object
              properties:
                effective_access_level:
                  type: string
                  enum:
                  - owner
                  - edit
                  - view
                  - none
                  description: The requesting user's effective access to this record (`owner`, `edit`, `view`, or `none`).
              description: Per-request metadata about the resource.
          required:
          - type
          - id
          - attributes
          description: The resource.
      required:
      - data
    InitRecordingMediaResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            recordingId:
              type: string
              description: The ID of the created recording, used to confirm the upload.
            meetingId:
              type: string
              description: The ID of the meeting the recording is attached to.
            key:
              type: string
              description: The storage key the media is uploaded to.
            upload:
              type: object
              properties:
                url:
                  type: string
                  description: The URL to submit the multipart form POST to.
                fields:
                  type: object
                  additionalProperties:
                    type: string
                  description: Form fields to include in the multipart POST alongside the file, exactly as returned.
              required:
              - url
              - fields
              description: The presigned S3 POST policy to submit the media file to.
          required:
          - recordingId
          - meetingId
          - key
          - upload
      required:
      - data
    UploadTranscriptDto:
      type: object
      properties:
        transcript:
          type: array
          items:
            type: object
            properties:
              words:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                      description: The transcribed word.
                    start_timestamp:
                      type: number
                      description: The start time of the word, in seconds from the beginning of the recording.
                    end_timestamp:
                      type: number
                      description: The end time of the word, in seconds from the beginning of the recording.
                    language:
                      type: string
                      nullable: true
                      description: The detected language of the word as an ISO code, or `null` if unknown.
                    confidence:
                      type: number
                      nullable: true
                      description: The transcription confidence for the word, from 0 to 1, or `null` if unavailable.
                  required:
                  - text
                  - start_timestamp
                  - end_timestamp
                  - language
                  - confidence
                description: The words spoken in this segment.
              speaker:
                type: string
                nullable: true
                description: The display name of the speaker, or `null` if unattributed.
              speaker_id:
                type: number
                nullable: true
                description: The numeric ID of the speaker, or `null` if unattributed.
              language:
                type: string
                description: The primary language of the segment as an ISO code.
            required:
            - words
            - speaker
            - speaker_id
            - language
          description: The meeting transcript, as an ordered list of speaker segments.
      required:
      - transcript
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Send your key in the Authorization header as: `api-key <your-api-key>`.'
    bearer:
      type: http
      scheme: bearer
      description: 'User access token authentication for endpoints that act across workspaces. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'