RingCentral Historical Recordings API

openapi: 3.0.3
info:
  title: RingCentral Adaptive Cards Historical Recordings API
  description: RingCentral API specification
  version: 1.0.58-20240529-47eda8bd
  contact:
    name: RingCentral Developers Support
    url: https://developers.ringcentral.com/support
  termsOfService: https://www.ringcentral.com/legal/apilitos.html
  license:
    name: RingCentral API License Agreement
    url: https://www.ringcentral.com/legal/apilitos.html
servers:
- url: https://platform.ringcentral.com
  description: Production API entry point
- url: https://media.ringcentral.com
  description: Production Media entry point
- url: https://platform.devtest.ringcentral.com
  description: Developer sandbox API entry point
- url: https://platform.devtest.ringcentral.com
  description: Developer sandbox Media entry point
security:
- OAuth2: []
tags:
- name: Historical Recordings
  description: Historical webinar recordings management (host and admin interfaces)
paths:
  /webinar/history/v1/company/recordings:
    get:
      tags:
      - Historical Recordings
      summary: List Webinar Recordings (Admin)
      description: 'Returns the list of webinar recordings (Administrator''s interface).

        The user must have "WebinarSettings" permission granted otherwise the API returns HTTP 403.

        '
      operationId: rcwHistoryAdminListRecordings
      parameters:
      - name: nameFragment
        in: query
        description: Filter to return only webinar recordings containing particular substring within their names
        required: false
        explode: true
        schema:
          type: string
        example: All-hands
      - $ref: '#/components/parameters/CreationTimeFrom'
      - $ref: '#/components/parameters/CreationTimeTo'
      - $ref: '#/components/parameters/RecordingStatus'
      - $ref: '#/components/parameters/HostUserId'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingAdminListResource'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      x-throttling-group: Heavy
      x-app-permission: ReadWebinars
  /webinar/history/v1/company/recordings/{recordingId}:
    get:
      tags:
      - Historical Recordings
      summary: Get Webinar Recording (Admin)
      description: 'Returns the webinar recording by ID (Administrator''s interface).


        The user must have "WebinarSettings" permission granted otherwise the API returns HTTP 403.

        '
      operationId: rcwHistoryAdminGetRecording
      parameters:
      - $ref: '#/components/parameters/RecordingId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingAdminExtendedItemModel'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-throttling-group: Heavy
      x-app-permission: ReadWebinars
  /webinar/history/v1/recordings:
    get:
      tags:
      - Historical Recordings
      summary: List Webinar Recordings
      description: 'Returns the list of webinar recordings for a given webinar host user

        '
      operationId: rcwHistoryListRecordings
      parameters:
      - $ref: '#/components/parameters/CreationTimeFrom'
      - $ref: '#/components/parameters/CreationTimeTo'
      - $ref: '#/components/parameters/RecordingStatus'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingListResource'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
      x-throttling-group: Heavy
      x-app-permission: ReadWebinars
  /webinar/history/v1/recordings/{recordingId}:
    get:
      tags:
      - Historical Recordings
      summary: Get Webinar Recording
      description: 'Returns the webinar recording by ID (Webinar host''s interface).

        This API also returns sharing link if sharing is enabled.

        '
      operationId: rcwHistoryGetRecording
      parameters:
      - $ref: '#/components/parameters/RecordingId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingItemExtendedModel'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-throttling-group: Heavy
      x-app-permission: ReadWebinars
  /webinar/history/v1/recordings/{recordingId}/download:
    get:
      tags:
      - Historical Recordings
      summary: Get Webinar Recording Download Resource
      description: 'Returns the webinar recording download link (both Webinar host''s and admin interface).


        If called by a webinar host, the API returns error (403) if recording downloading is prohibited by company settings.

        The admin user who has "WebinarSettings" permission should be able to download recording regardless of current company settings.

        '
      operationId: rcwHistoryGetRecordingDownload
      parameters:
      - $ref: '#/components/parameters/RecordingMediaType'
      - $ref: '#/components/parameters/RecordingId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordingDownloadModel'
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
      x-throttling-group: Heavy
      x-app-permission: ReadWebinars
components:
  schemas:
    WebinarHostModel:
      type: object
      required:
      - host
      properties:
        host:
          $ref: '#/components/schemas/HostModel'
    RecordingItemModel:
      allOf:
      - $ref: '#/components/schemas/RecordingModel'
      - type: object
        properties:
          session:
            $ref: '#/components/schemas/SessionRefModel'
    RecordingExtendedModel:
      allOf:
      - $ref: '#/components/schemas/RcwResourceBaseModel'
      - $ref: '#/components/schemas/RecordingBaseModel'
      - $ref: '#/components/schemas/RecordingSharingModel'
    WebinarTitleModel:
      type: object
      required:
      - title
      properties:
        title:
          type: string
          description: Webinar title
          maxLength: 512
          minLength: 1
          example: All-Hands Webinar
        description:
          type: string
          description: User-friendly description of the Webinar
          maxLength: 4096
          minLength: 0
          example: Quarterly All-hands event to present recent news about our company to employees
          default: ''
    RecordingSharedStatusModel:
      type: boolean
      description: 'Indicates if Host or Admin has shared a recording.

        Can be set to true only then recording status is ''Available''.

        '
      example: true
    ApiErrorWithParameter:
      description: 'The error model with additional attributes which can be used for HTTP 400/409

        This is a deprecated model: "ApiError" model can be used instead with arbitrary additional parameters

        '
      allOf:
      - $ref: '#/components/schemas/ApiError'
      - type: object
        properties:
          parameterName:
            type: string
            description: The name of the API parameter/attribute which caused the error
          parameterValue:
            type: string
            description: The value of the API parameter/attribute which caused the error
    RecordingListResource:
      type: object
      required:
      - records
      - paging
      properties:
        records:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/RecordingItemModel'
        paging:
          $ref: '#/components/schemas/RcwPagingModel'
    ApiError:
      type: object
      description: Generalized API error structure suitable for any error type
      required:
      - errorCode
      - message
      properties:
        errorCode:
          type: string
          description: Logical error code (typically, 3 letters followed with number, dash separated)
          example: XXX-123
        message:
          type: string
          description: User-friendly error message
          example: Something went wrong
      additionalProperties: true
    RecordingDownloadModel:
      type: object
      required:
      - downloadUri
      - downloadContentType
      - downloadSize
      properties:
        downloadUri:
          type: string
          format: uri
          description: Download URI (available only for webinar host or admin)
        downloadContentType:
          type: string
          description: MIME type of the file to download.
          enum:
          - video/mp4
          - audio/m4a
          default: video/mp4
        downloadSize:
          type: integer
          format: int64
          description: Download file size in bytes
          example: 20821092300
    RecordingMediaType:
      type: string
      description: Recording file media type. 'Video' implies multiplexed audio and video. 'Audio' refers to audio only.
      enum:
      - Video
      - Audio
      example: Video
      default: Video
    HostModel:
      allOf:
      - $ref: '#/components/schemas/RcwBaseContactModel'
      - $ref: '#/components/schemas/RcwLinkedUserModel'
    ApiErrorResponseModel:
      type: object
      description: Standard error response model which is returned in case of any unsuccessful operation
      required:
      - errors
      properties:
        errors:
          type: array
          description: The array of errors (there will be just one in the most of the cases)
          minItems: 1
          items:
            $ref: '#/components/schemas/ApiError'
    RecordingSharingModel:
      type: object
      required:
      - recordingSharedUri
      properties:
        recordingSharedUri:
          type: string
          format: uri
          readOnly: true
          description: Shared URI of the recording. If a password was required to join a webinar, the URI should contain the password encoded
          example: https://v.ringcentral.com/w/a/recording/de7yd8ew7yfsdfjh899843rgj?pw=a1b2c3d4
    RcwDomainUserModel:
      allOf:
      - $ref: '#/components/schemas/RcwUserModel'
      - type: object
        required:
        - domain
        properties:
          domain:
            type: string
            description: Identity domain
            enum:
            - pbx
            - ilm
            default: pbx
    RcwResourceBaseModel:
      allOf:
      - $ref: '#/components/schemas/RcwImmutableResourceIdModel'
      - type: object
        required:
        - creationTime
        - lastModifiedTime
        properties:
          creationTime:
            type: string
            description: Object creation time
            format: date-time
            readOnly: true
          lastModifiedTime:
            type: string
            description: Object last modification time
            format: date-time
            readOnly: true
    RcwUserModel:
      type: object
      required:
      - userId
      - accountId
      properties:
        userId:
          type: string
          maxLength: 256
          description: User ID
        accountId:
          type: string
          maxLength: 256
          description: Account ID
    RcwPagingForwardModel:
      type: object
      required:
      - pageToken
      - perPage
      properties:
        perPage:
          type: integer
          format: int32
          minimum: 1
          maximum: 1000
          description: Number of items per page
          example: 100
        pageToken:
          type: string
          description: Current page token
        nextPageToken:
          type: string
          description: Next page token (absent for the last page of the result set)
        previousPageToken:
          type: string
          description: 'Previous page token (absent for the first page of the result set)

            May be omitted if the result set does not support backward navigation.

            '
    RecordingBaseModel:
      type: object
      required:
      - status
      properties:
        status:
          $ref: '#/components/schemas/RecordingStatusModel'
        failureReason:
          $ref: '#/components/schemas/ApiError'
        duration:
          type: integer
          format: int32
          readOnly: true
          minimum: 1
          description: Recording duration in seconds
          example: 3600
        shared:
          $ref: '#/components/schemas/RecordingSharedStatusModel'
        sharedUriExpirationTime:
          $ref: '#/components/schemas/RecordingSharedLinkExpiryModel'
    RcwImmutableResourceIdModel:
      type: object
      properties:
        id:
          type: string
          description: Internal object ID
          minLength: 1
          maxLength: 20
          example: '78654321'
          readOnly: true
    RcwResourceIdModel:
      type: object
      properties:
        id:
          type: string
          description: Internal object ID
          minLength: 1
          maxLength: 20
          example: '78654321'
    WebinarRefModel:
      allOf:
      - $ref: '#/components/schemas/RcwResourceIdModel'
      - $ref: '#/components/schemas/WebinarTitleModel'
      - $ref: '#/components/schemas/WebinarHostModel'
    RecordingStatusModel:
      type: string
      description: Recording status
      enum:
      - Processing
      - Available
      - Failed
      - Purged
      example: Available
    ParameterizedErrorResponseModel:
      type: object
      description: Standard error response which may include parameterized errors
      required:
      - errors
      properties:
        errors:
          type: array
          description: The array of errors (there will be just one in the most of the cases)
          minItems: 1
          items:
            $ref: '#/components/schemas/ApiErrorWithParameter'
    SessionRefAdminModel:
      allOf:
      - $ref: '#/components/schemas/RcwResourceIdModel'
      - $ref: '#/components/schemas/SessionMinimalModel'
      - type: object
        properties:
          webinar:
            $ref: '#/components/schemas/WebinarRefModel'
    SessionRefModel:
      allOf:
      - $ref: '#/components/schemas/RcwResourceIdModel'
      - $ref: '#/components/schemas/SessionMinimalModel'
      - type: object
        properties:
          webinar:
            $ref: '#/components/schemas/WebinarRefModel'
    RecordingSharedLinkExpiryModel:
      type: string
      nullable: true
      format: date-time
      description: Time after which recording shared link cannot be accessed by recipients.
      example: '2023-10-01T10:05:00.000Z'
    RecordingAdminModel:
      allOf:
      - $ref: '#/components/schemas/RecordingItemModel'
      - type: object
        properties:
          session:
            $ref: '#/components/schemas/SessionRefAdminModel'
    RcwBaseContactModel:
      type: object
      properties:
        firstName:
          type: string
          description: First (given) name
          maxLength: 64
          example: John
          x-sensitive-data: masked
        lastName:
          type: string
          description: Last (family) name
          maxLength: 64
          example: Doe
          x-sensitive-data: masked
    RecordingItemExtendedModel:
      allOf:
      - $ref: '#/components/schemas/RecordingExtendedModel'
      - type: object
        properties:
          session:
            $ref: '#/components/schemas/SessionRefModel'
    RcwLinkedUserModel:
      type: object
      description: The internal IDs of RC-authenticated users.
      properties:
        linkedUser:
          $ref: '#/components/schemas/RcwDomainUserModel'
    RcwPagingModel:
      allOf:
      - $ref: '#/components/schemas/RcwPagingForwardModel'
      - type: object
        properties:
          previousPageToken:
            type: string
            description: Previous page token (absent for the first page of the result set)
    RecordingAdminListResource:
      type: object
      required:
      - records
      - paging
      properties:
        records:
          type: array
          minItems: 0
          items:
            $ref: '#/components/schemas/RecordingAdminModel'
        paging:
          $ref: '#/components/schemas/RcwPagingModel'
    RecordingModel:
      allOf:
      - $ref: '#/components/schemas/RcwResourceBaseModel'
      - $ref: '#/components/schemas/RecordingBaseModel'
    SessionMinimalModel:
      type: object
      properties:
        startTime:
          type: string
          description: 'Session start time. If a session hasn''t been started this fields should be set to "scheduledStartTime"

            '
          format: date-time
        endTime:
          type: string
          description: 'Session end time. If a session hasn''t been finished this fields should be set to ("startTime"+"scheduledDuration")

            '
          format: date-time
        duration:
          type: integer
          format: int32
          description: Session duration in seconds rounded up (returned if 'startTime' and 'endTime' are not empty)
          example: 3600
        title:
          type: string
          description: Session title. If blank - derived from webinar title.
          maxLength: 512
          example: Live Broadcasting US
        description:
          type: string
          maxLength: 4096
          description: User-friendly description of the Session. If blank - derived from webinar title.
          example: Live session for US-based participants
    RecordingAdminExtendedItemModel:
      allOf:
      - $ref: '#/components/schemas/RecordingItemExtendedModel'
      - type: object
        properties:
          session:
            $ref: '#/components/schemas/SessionRefAdminModel'
  parameters:
    CreationTimeFrom:
      name: creationTimeFrom
      in: query
      description: The beginning of the time window by 'creationTime' .
      required: true
      explode: false
      schema:
        type: string
        format: date-time
    HostUserId:
      name: hostUserId
      in: query
      description: Identifier of the user who hosts a webinar (if omitted, webinars hosted by all company users will be returned)
      required: false
      explode: false
      schema:
        type: array
        maxItems: 10
        minItems: 0
        items:
          type: string
          minLength: 1
          maxLength: 20
      example:
      - '77777777'
    PerPage:
      name: perPage
      in: query
      description: 'The number of items per page. If provided value in the request

        is greater than a maximum, the maximum value is applied

        '
      required: false
      explode: false
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 1000
        default: 100
      example: 100
    PageToken:
      name: pageToken
      in: query
      description: 'The token indicating the particular page of the result set to be retrieved.

        If omitted the first page will be returned.

        '
      required: false
      explode: false
      schema:
        type: string
    RecordingId:
      name: recordingId
      in: path
      description: Identifier of the Webinar recording.
      required: true
      style: simple
      explode: false
      schema:
        type: string
      example: '7637637682'
    RecordingMediaType:
      schema:
        $ref: '#/components/schemas/RecordingMediaType'
      in: query
      name: recordingMediaType
      description: 'Download file media type.

        - Type ''Video'' refers to a multiplexed audio and video file.

        - Type ''Audio'' refers to an audio only file.

        - Unless specified by this query parameter, a video file is returned by default when a recording is downloaded.

        '
      required: false
    RecordingStatus:
      name: status
      in: query
      description: The status of the recording.
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: '#/components/schemas/RecordingStatusModel'
    CreationTimeTo:
      name: creationTimeTo
      in: query
      description: The end of the time window by 'creationTime' .
      required: true
      explode: false
      schema:
        type: string
        format: date-time
  responses:
    NotFound:
      description: 'General response with **HTTP 404 "Not found"** status.<br>

        Reasons: the entity with given ID (typically specified in a path parameter), is not found or inaccessible

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponseModel'
    Forbidden:
      description: 'General response with **HTTP 403 "Forbidden"** status.<br>

        Reasons: the requested operation is forbidden because of certain resource state, lack of permissions, feature unavailability, etc.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponseModel'
    InternalError:
      description: 'General response with **HTTP 500 "Internal Server Error"** status.<br>

        Reasons: general server-side error.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponseModel'
    InvalidRequest:
      description: 'General response with **HTTP 400 "Bad request"** status.<br>

        Reasons: unparsable request, path, query or body parameters are invalid.

        The error description may contain reference to particular parameter(s) which haven''t passed the validation.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ParameterizedErrorResponseModel'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.ringcentral.com/restapi/oauth/authorize
          tokenUrl: https://platform.ringcentral.com/restapi/oauth/token
          refreshUrl: https://platform.ringcentral.com/restapi/oauth/token
          scopes: {}
x-tagGroups:
- name: Voice
  popular: true
  tags:
  - Business Hours
  - Call Blocking
  - Call Control
  - Call Forwarding
  - Call Handling Rules
  - Interaction Rules
  - State-based Rules
  - Call Flip
  - Call Log
  - Call History
  - Call Log Export
  - Call Monitoring Groups
  - Call Queues
  - Call Recordings
  - Call Recording Settings
  - Device SIP Registration
  - Greetings
  - IVR
  - RingOut
  - Verification Calls
- name: SMS and Fax
  popular: true
  tags:
  - Fax
  - Message Exports
  - Message Store
  - Pager Messages
  - SMS
  - High Volume SMS
  - SMS Log Export
  - SMS Templates
  - Voicemail Broadcasting
- name: Social Messaging
  popular: true
  tags:
  - Identities
  - Contents
- name: Team Messaging
  popular: true
  tags:
  - Adaptive Cards
  - Bots
  - Calendar Events
  - Chats
  - Conversations
  - Compliance Exports
  - Contacts
  - Incoming Webhooks
  - Notes
  - Posts
  - Profile
  - Tasks
  - Teams
- name: Video
  popular: true
  tags:
  - Bridge Management
  - Delegation Management
  - Meetings History
  - Meeting Recordings
  - RCM Meetings (Legacy)
  - RCM Webinars (Legacy)
- name: Webinar
  popular: true
  tags:
  - Webinars and Sessions
  - Invitees
  - Historical Webinars
  - Historical Recordings
  - Registration Management
  - Registrants
  - Webinar Analytics
  - Webinar Subscriptions
- name: Analytics
  popular: true
  tags:
  - Business Analytics
- name: Artificial Intelligence
  popular: true
  tags:
  - Insights
  - Audio
  - Text
  - Status
- name: Authentication
  tags:
  - OAuth 2.0 / OpenID Connect
  - Interoperability
- name: Account
  tags:
  - Company
  - Custom Fields
  - Features
  - Licenses
  - Tax Locations
  - Cost Centers
  - Multi-Site
  - Phone Numbers
  - Presence
  - Regional Settings
  - User Permissions
  - User Settings
  - Audit Trail
  - Calling Rates
  - Appearance Customization
  - Account Integrations
- name: Provisioning
  tags:
  - Automatic Location Updates
  - Devices
  - Extensions
  - Paging Only Groups
  - Park Locations
  - Phone Lines
  - SCIM
  - Shared Lines
  - Group Call Pickup
  - Delegated Lines Groups
  - Directed Call Pickup
  - IVR Apps
  - Video Configuration
  - Number Porting
  - SMB
  - Account Federation
  - Integrations
  - Enterprise Portal API
  - Push to Talk Provisioning
  - BYOC
- name: Address Book
  tags:
  - External Contacts
  - Internal Contacts
  - Hybrid Directory Contacts
  - Overlay Contacts
  - External Shared Directory
- name: Roles and Permissions
  tags:
  - Permissions
  - Role Management
  - Site Administration
  - User Groups
- name: Events & Notifications
  tags:
  - Subscriptions
- name: User Integrations
  tags:
  - Token Management
  - Calendar Management
  - Calendar Event Management
  - Calendar Presence Link
  - Cloud Personal Contacts
  - Cloud Shared Contacts
  - Cloud Directory
  - Deprecated Calendar API
- name: Rooms
  tags:
  - Rooms Client API
  - Rooms Management API
- name: App Management
  tags:
  - App Gallery
  - App Rating Review
  - Bot Provisioning
- name: Workflow Builder
  tags:
  - Flows
  - Flow Editor
  - Flow Log
  - Flow Templates
- name: Utilities
  tags:
  - API Info
  - Application Settings
  - Async Tasks
  - User Notifications
  - Client Versions
  - End-to-End Encryption