openapi: 3.0.0 info: title: Live Recordings Service description: >- This API contains all the functions that can be used for controlling the recorder (e.g. starting a recording) version: 2019.Winter.1 servers: - url: 'http://{host}/fw/Apps/Recorder/WebAPI/LiveRecordings' description: UCX Suite server variables: host: default: localhost description: The UCX Suite server hostname or IP address security: - UserSecurity: [] paths: /: get: summary: Get current active recordings, filtered by device name, directory number, username and/or numeric user ID tags: - Recording parameters: - name: deviceName description: The device of which you want to see active recordings. example: SEP123456789ABC in: query required: false schema: type: string - name: directoryNumber description: The directory number of which you want to see active recordings. example: 123456 in: query required: false schema: type: string - name: username description: The username of the user of which you want to see active recordings. example: user1 in: query required: false schema: type: string - name: numericUserId description: The numeric user ID of the user of which you want to see active recordings. example: 00998877 in: query required: false schema: type: string responses: '200': description: The list of recordings is returned content: application/json: schema: type: array items: $ref: '#/components/schemas/Recording' '400': description: No device name nor directory number were given '401': description: No authentication provided or wrong user credentials '403': description: Authenticated user is unauthorized '500': description: An error occurred while processing the request post: summary: Start recording a connected call tags: - Recording requestBody: description: >- \* If the request doesn't contain a body, start recording a connected call (media forking) on the line associated to the authenticated user. \* If the request contains a body, start recording a connected call on the line defined by given properties. The authenticated user must have 'Complete Management' Call Recording authorization level in order to start recording other users' devices. content: application/json: schema: type: object properties: deviceName: description: >- The device you want to record (there must be a connected call on it). If directoryNumber is specified too, the call on the device will be recorded only if it belongs to the given line type: string default: null example: SEP123456789ABC directoryNumber: description: >- The line you want to record (there must be a connected call on it). If deviceName is specified too, the call on the line will be recorded only if it belongs to the given device type: string default: null example: '101' mode: description: | The recording mode you want to use. * `0`: Cisco Media Forking * `1`: Dial-In type: integer enum: - 0 - 1 default: 0 responses: '201': description: The call is being recorded content: application/json: schema: properties: id: type: string format: uuid description: The identifier of the recording you just started example: 6b98303a-b295-473a-adae-19b78aca468d '400': description: The request contains some errors content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: The request body contains neither the device name nor the directory number * `1`: The line identified by given device name and/or directory number does not exist or isn't monitorable through TAPI * `2`: Invalid recording mode * `3`: Requesting user without extension number * `4`: Device configured for Automatic call recording enum: - 0 - 1 - 2 - 3 - 4 deviceName: type: string description: >- The name of the device that cannot be monitored through TAPI. Present only if reason=1 example: SEP123456789ABC '401': description: No authentication provided or wrong user credentials '403': description: >- The call cannot be recorded due to user authorization issues or to the restrictions set on the Imagicle Call Recording Service content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Authenticated user is unauthorized * `1`: The user associated to the call is not authorized to record * `2`: The call direction doesn't match the filter set on the Imagicle Call Recording service * `3`: The call traffic type doesn't match the filter set on the Imagicle Call Recording service * `4`: Remote party is in the blacklist set on the Imagicle Call Recording service enum: - 0 - 1 - 2 - 3 - 4 username: type: string description: >- The username associated to the call is not authorized to record. Present only if reason=1. '409': description: >- The call cannot be recorded due to the current status of the Imagicle Call Recording service content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: The call connected on given device is on a line with no IAS user associated to it * `1`: There is no connected call on given device enum: - 0 - 1 extension: type: string description: >- Directory number of the line having a connected call but no user associated (may be null if no such line has been found) '429': description: The request has already been received content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Another recording request has already been received for this call (the recording has not started yet) * `1`: The call is already being recorded enum: - 0 - 1 '500': description: An error occurred while processing the request '501': description: >- The call cannot be recorded due to a misconfiguration of the Imagicle Call Recording service content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Invalid Imagicle Call Recording license * `1`: No recording pilot has been configured on the Imagicle Call Recording service * `2`: Configured recording pilot doesn't route calls to the Imagicle Call Recording service (if mode is DialIn), or something is not correctly configured on CUCM side (if mode is MediaForking) enum: - 0 - 1 - 2 '503': description: >- The call cannot be recorded because all licensed channels are being used delete: summary: >- Stop a recording on the line identified by the device name and/or the directory number tags: - Recording parameters: - name: deviceName description: >- The device you want to record (there must be a connected call on it). If directoryNumber is specified too, the call on the device will be recorded only if it belongs to the given line example: SEP123456789ABC in: query schema: type: string - name: directoryNumber description: >- The line you want to record (there must be a connected call on it). If deviceName is specified too, the call on the line will be recorded only if it belongs to the given device example: '101' in: query schema: type: string responses: '204': description: The recording has been stopped '400': description: The request contains some errors content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Neither device name nor directory number have been specified * `1`: The line identified by given device name and/or directory number does not exist or isn't monitorable through TAPI * `2`: Device configured for Automatic call recording enum: - 0 - 1 - 2 deviceName: type: string description: >- The name of the device that cannot be monitored through TAPI. Present only if reason=1 example: SEP123456789ABC '401': description: No authentication provided or wrong user credentials '403': description: Authenticated user is unauthorized '409': description: > Either one of these errors occurred: * There is not a call being recorded on the given device name and/or directory number * There is a call being recorded, but it is a manually started dial-in and the stop has been invoked providing the device name '500': description: An error occurred while processing the request /OnBehalfOf: post: summary: If Live Keep is enabled, keep an ongoing recording on behalf of a specific user tags: - Recording requestBody: description: >- If Live Keep is enabled, keep an ongoing recording on behalf of a specific user content: application/json: schema: type: object properties: userName: description: >- The username of the owner of the recording type: string default: null example: mario.rossi mode: description: | The recording mode you want to use. * `0`: Cisco Media Forking * `1`: Dial-In * `2`: Live Keep type: integer enum: - 0 - 1 - 2 default: 0 responses: '201': description: The call is being recorded content: application/json: schema: properties: id: type: string format: uuid description: The identifier of the recording you just started example: 6b98303a-b295-473a-adae-19b78aca468d '400': description: The request contains some errors content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `2`: Invalid recording mode * `3`: Invalid user in request body enum: - 0 - 1 - 2 - 3 - 4 deviceName: type: string description: >- The name of the device that cannot be monitored through TAPI. Present only if reason=1 example: SEP123456789ABC '401': description: No authentication provided or wrong user credentials '403': description: >- The call cannot be recorded due to user authorization issues or to the restrictions set on the Imagicle Call Recording Service content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Authenticated user is unauthorized * `4`: Remote party is in the blacklist set on the Imagicle Call Recording service enum: - 0 - 1 - 2 - 3 - 4 username: type: string description: >- The username associated to the call is not authorized to record. Present only if reason=1. '409': description: >- The call cannot be recorded due to the current status of the Imagicle Call Recording service content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `2`: Cannot restart a stopped recording * `3`: There is no ongoing recording to keep enum: - 0 - 1 - 2 - 3 '429': description: The request has already been received content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Another recording request has already been received for this call (the recording has not started yet) * `1`: The call is already being recorded enum: - 0 - 1 '500': description: An error occurred while processing the request '501': description: >- The call cannot be recorded due to a misconfiguration of the Imagicle Call Recording service content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Invalid Imagicle Call Recording license * `1`: No recording pilot has been configured on the Imagicle Call Recording service * `2`: Configured recording pilot doesn't route calls to the Imagicle Call Recording service (if mode is DialIn), or something is not correctly configured on CUCM side (if mode is MediaForking) enum: - 0 - 1 - 2 '503': description: >- The call cannot be recorded because all licensed channels are being used /Mine: get: summary: Get current active recordings for authenticated user tags: - Recording parameters: [] responses: '200': description: The list of recordings is returned content: application/json: schema: type: array items: $ref: '#/components/schemas/Recording' '401': description: No authentication provided or wrong user credentials '500': description: An error occurred while processing the request delete: summary: Stop recording on the line associated to authenticated user tags: - Recording parameters: [] responses: '204': description: The recording has been stopped '400': description: The request contains some errors content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `1`: Authenticated user is associated to a line that isn't monitorable through TAPI * `2`: Device configured for Automatic call recording number enum: - 1 - 2 '401': description: No authentication provided or wrong user credentials '409': description: There is no such active recording for authenticated user '500': description: An error occurred while processing the request '/{id}': delete: summary: >- Stop recording the call identified by the id returned when the recording was started tags: - Recording parameters: - name: id description: The id of the recording you want to stop example: 6b98303a-b295-473a-adae-19b78aca468d in: path required: true schema: type: string format: uuid responses: '204': description: The recording has been stopped '400': description: The request contains some errors content: application/json: schema: properties: reason: type: integer description: > The reason why the request has been rejected * `0`: Given id is not a valid GUID * `1`: Id identifies a recording on a line that isn't monitorable through TAPI * `2`: Device configured for Automatic call recording enum: - 0 - 1 - 2 '401': description: No authentication provided or wrong user credentials '403': description: Authenticated user is unauthorized '409': description: There is no such recording with given id '500': description: An error occurred while processing the request '/{id}/Pause': put: summary: Pause the recording of a connected call tags: - Recording parameters: - name: id description: The id of the recording you want to pause example: 6b98303a-b295-473a-adae-19b78aca468d in: path required: true schema: type: string format: uuid responses: '204': description: The recording has been paused '400': description: Given id is not a valid GUID '401': description: No authentication provided or wrong user credentials '403': description: Authenticated user is unauthorized '409': description: There is no such recording with given id '429': description: The call recording is already paused '500': description: An error occurred while processing the request '/{id}/Resume': put: summary: Resume a paused recording tags: - Recording parameters: - name: id description: The id of the paused recording you want to resume example: 6b98303a-b295-473a-adae-19b78aca468d in: path required: true schema: type: string format: uuid responses: '204': description: The recording has been resumed '400': description: Given id is not a valid GUID '401': description: No authentication provided or wrong user credentials '403': description: Authenticated user is unauthorized '409': description: There is no such recording with given id '429': description: The call recording is not paused '500': description: An error occurred while processing the request '/Pause': put: summary: Pause the recording of a connected call on given directory number tags: - Recording parameters: - name: directoryNumber description: The directory number of the line whose recording you want to pause example: 754 in: query required: true schema: type: string responses: '204': description: The recordings have been paused '400': description: Given directory number is null '401': description: No authentication provided or wrong user credentials '403': description: Authenticated user is unauthorized '409': description: There is no such recording with given directory number '429': description: The call recording is already paused '500': description: An error occurred while processing the request '/Resume': put: summary: Resume a paused recording on given directory number tags: - Recording parameters: - name: directoryNumber description: The directory number of the line whose recording you want to resume example: 754 in: query required: true schema: type: string responses: '204': description: The recordings have been resumed '400': description: Given directory number is null '401': description: No authentication provided or wrong user credentials '403': description: Authenticated user is unauthorized '409': description: There is no such recording with given directory number '429': description: The call recording is not paused '500': description: An error occurred while processing the request components: securitySchemes: UserSecurity: type: http scheme: basic schemas: Recording: type: object properties: id: type: string format: uuid description: The identifier of the recording example: 6b98303a-b295-473a-adae-19b78aca468d duration: type: string format: ISO 8601 duration description: Current duration example: PT1M13S startedAt: type: string format: ISO 8601 date description: Starting recording time example: "2018-07-02T15:07:00.0000000" localParty: $ref: '#/components/schemas/LocalParty' remoteParty: $ref: '#/components/schemas/RemoteParty' isPaused: type: boolean description: True if the recording is paused. False otherwise LocalParty: type: object description: Details about the local party, i.e. the recording owner properties: username: type: string description: IAS Username example: user1 RemoteParty: type: object description: Details about the remote party properties: firstName: type: string description: Contact first name example: John lastName: type: string description: Contact last name example: Doe phoneNumber: type: string description: Remote party phone number example: '+1555123456'