Demodesk Externally recorded demos API

openapi: 3.0.1
info:
  title: API V1 Externally recorded demos API
  version: v1
servers:
- url: https://{defaultHost}
  variables:
    defaultHost:
      default: demodesk.com
tags:
- name: Externally recorded demos
paths:
  /api/v1/externally_recorded_demos:
    post:
      summary: Create Externally recorded demo
      tags:
      - Externally recorded demos
      security:
      - api-key: []
      parameters: []
      responses:
        '401':
          description: unauthenticated
        '200':
          description: demo created
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                demo:
                  type: object
                  description: Meeting details
                  properties:
                    start_date:
                      type: string
                      format: datetime
                      description: Meeting start time
                    account:
                      type: string
                      description: Meeting name
                    calendar_owner_id:
                      type: string
                      description: User id of the calendar event owner.
                    booker_id:
                      type: string
                      description: User id of the calendar event booker
                  required:
                  - account
                host:
                  type: object
                  description: Identification of the meeting host
                  properties:
                    email:
                      type: string
                      description: Email address of the meeting host
                  required:
                  - email
                guests:
                  type: array
                  description: List of meeting guests/participants
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Name of the guest
                    required:
                    - name
                recording:
                  type: object
                  description: Recording details
                  properties:
                    url:
                      type: string
                      description: URL of the recording file (must be publicly accessible)
                    speaker_count:
                      type: integer
                      description: The number of speakers in the recording
                    content_type:
                      type: string
                      description: The content type of the recording, e.g., "audio/mpeg".
                  required:
                  - url
                  - speaker_count
                  - content_type
              required:
              - demo
              - host
              - guests
              - recording
        required: true
  /api/v1/externally_recorded_demos/create_from_mobile_recording_upload:
    post:
      summary: Create demo from mobile recording upload
      tags:
      - Externally recorded demos
      description: 'Uploads a recording from mobile.

        If `demo_id` is provided, the recording is attached to that existing demo.

        If `demo_id` is omitted, a new demo is created from the provided metadata.

        '
      security:
      - api-key: []
      parameters: []
      responses:
        '401':
          description: unauthenticated
        '200':
          description: demo created
        '400':
          description: invalid payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                required:
                - errors
        '404':
          description: demo not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: ActiveStorage blob signed id of the uploaded video file
                  example: eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBc0EiLCJleHAiOm51bGwsInB1ciI6ImJsb2JfaWQifX0=--abcdef123
                name:
                  type: string
                  description: Original file name used as fallback demo title when demo.account is missing
                  minLength: 1
                  example: weekly-product-review.mp4
                current_index:
                  type: integer
                  description: Non-negative upload index used to stagger transcription jobs by minutes
                  minimum: 0
                  example: 0
                demo_id:
                  type: integer
                  description: Existing Demodesk meeting id to attach recording to instead of creating a new meeting
                  minimum: 1
                  example: 12345
                demo:
                  type: object
                  description: Optional demo metadata used only when demo_id is not provided. created_via is set server-side to mobile_upload.
                  properties:
                    account:
                      type: string
                      description: Meeting title
                      minLength: 1
                      example: Mobile imported meeting
                    start_date:
                      type: string
                      format: datetime
                      description: Meeting start date/time in ISO8601 format
                      example: '2025-01-20T12:00:00Z'
                    duration:
                      type: integer
                      description: Meeting duration in seconds
                      minimum: 1
                      example: 900
                participants:
                  type: array
                  description: List of participant metadata. required only when demo_id is not provided.
                  items:
                    type: object
                    properties:
                      full_name:
                        type: string
                        description: Participant full name
                        nullable: true
                        example: Ada Lovelace
                      email:
                        type: string
                        description: Participant email address
                        nullable: true
                        example: ada@example.com
                location:
                  type: object
                  description: Location/link string. Backend stores location kind as other.
                  properties:
                    value:
                      type: string
                      description: Meeting location/link string
                      nullable: true
                      example: https://meet.google.com/abc-defg-hij
              required:
              - file
              - name
              example:
                file: eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBc0EiLCJleHAiOm51bGwsInB1ciI6ImJsb2JfaWQifX0=--abcdef123
                name: weekly-product-review.mp4
                current_index: 0
                demo_id: 12345
                demo:
                  account: Mobile imported meeting
                  start_date: '2025-01-20T12:00:00Z'
                  duration: 900
                participants:
                - full_name: Ada Lovelace
                  email: ada@example.com
                - full_name: Grace Hopper
                  email: grace@example.com
                location:
                  value: https://meet.google.com/abc-defg-hij
        required: true
  /api/v1/externally_recorded_demos/create_from_recording_upload:
    post:
      summary: Create demo from recording upload
      tags:
      - Externally recorded demos
      description: 'Uploads a recording.

        If `demo_id` is provided, the recording is attached to that existing demo.

        If `demo_id` is omitted, a new manual-upload demo is created.

        '
      security:
      - api-key: []
      parameters: []
      responses:
        '401':
          description: unauthenticated
        '200':
          description: demo created or recording attached
        '404':
          description: demo not found
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                file:
                  type: string
                  description: ActiveStorage blob signed id of the uploaded video file
                  example: eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBc0EiLCJleHAiOm51bGwsInB1ciI6ImJsb2JfaWQifX0=--abcdef123
                name:
                  type: string
                  description: Original file name used as demo title when creating a new meeting
                  minLength: 1
                  example: weekly-product-review.mp4
                current_index:
                  type: integer
                  description: Non-negative upload index used to stagger transcription jobs by minutes
                  minimum: 0
                  example: 0
                demo_id:
                  type: integer
                  description: Existing Demodesk meeting id to attach recording to instead of creating a new meeting
                  minimum: 1
                  example: 12345
              required:
              - file
              - name
              example:
                file: eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBc0EiLCJleHAiOm51bGwsInB1ciI6ImJsb2JfaWQifX0=--abcdef123
                name: weekly-product-review.mp4
                current_index: 0
                demo_id: 12345
        required: true
components:
  securitySchemes:
    api-key:
      type: apiKey
      name: api-key
      in: header