search
Get supportBlogGet a demo

Snapshots and recordings

How to retrieve snapshots and records via REST API

The Media API allows you to manage and retrieve media generated during conversations, such as snapshots, screen captures, and call recordings. This section covers the main operations to list, inspect, update, delete, and download media files. Typical use cases include displaying conversation snapshots in an application, downloading recordings for review, or removing sensitive captures to meet compliance requirements.

hashtag
List available media by conversation or by user

Endpoint: GET /api/v3/medias Description: Returns a paginated list of media (snapshots, captures, recordings) with optional filters such as type, conversationId, status, and creation date range. When to use:

  • Display all media associated with a conversation in your app’s UI.

  • Filter to only show recent snapshots or recordings.

  • Implement bulk download or cleanup tools.

hashtag
This call returns a list of media.

get
/api/v3/medias
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
statusstring · enumOptional

Limit result set to posts assigned one or more statuses.

Default: completedPossible values:
offsetintegerOptional

Offset the result set by a specific number of items.

limitintegerOptional

Maximum number of items to be returned in result set.

Default: 10
sincestringOptional

Limit response to media created after a given ISO 8601 compliant UTC date (format: 2020-01-01T15:00:00Z).

untilstringOptional

Limit response to media created before a given ISO 8601 compliant UTC date (format: 2020-01-01T16:00:00Z).

searchstringOptional

Limit results to those matching a string.

orderbystring · enumOptional

Sort collection by object attribute.

Default: datePossible values:
orderstring · enumOptional

Order sort attribute ascending or descending.

Default: descPossible values:
media_typestring · enumOptional

Limit result set to attachments of a particular media type.

Possible values:
tagstringOptional

Limit result set to media assigned to a specific tag.

userstringOptional

Limit result set to media attached to a specific user ID (set 'all' to limit result to the enterprise, admin role required).

user_groupintegerOptional

Limit result set to media attached to a specific user group ID.

source_typestring · enumOptional

Limit result set to attachments of a particular source type.

Possible values:
conversation_idstringOptional

Limit result set to attachments from a particular conversation. ID can be a string or an integer.

Responses
chevron-right
200

Good case

application/json
Responseany
get
/api/v3/medias
200

Good case

hashtag
Retrieve details of a specific media

Endpoint: GET /api/v3/medias/{mediaId} Description: Returns full metadata for a specific media item, including type, status, creation time, size, and format. When to use:

  • Check if a recording is ready for download.

  • Get metadata before archiving or sharing a media item.

hashtag
Get media by ID

get
/api/v3/medias/{mediaId}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
mediaIdintegerRequired

Set to the ID of the media that you want to return.

Responses
chevron-right
200

Good case

application/json
Responseany
get
/api/v3/medias/{mediaId}
200

Good case

hashtag
Get the binary file of a capture or a recording (download)

hashtag
Download a media file

Endpoint: GET /api/v3/medias/{mediaId}/download Description: Returns the binary file for the given media item. When to use:

  • Save a snapshot locally for documentation or evidence.

  • Download a full recording for offline review or editing.

  • Transfer media to external processing/storage systems.

hashtag
Download media by ID

get
/api/v3/medias/{mediaId}/download
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
mediaIdintegerRequired

Set to the ID of the media that you want to download.

Responses
chevron-right
200

Download the media.

No content
get
/api/v3/medias/{mediaId}/download
No content

hashtag
Update media metadata

Endpoint: PUT /api/v3/medias/{mediaId} Description: Updates mutable fields of a media item, such as labels, retention date, or custom metadata. When to use:

  • Tag media for case tracking or analytics.

  • Extend or reduce retention for compliance.

  • Add categorization labels for later search.

hashtag
Update media by ID

put
/api/v3/medias/{mediaId}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
mediaIdintegerRequired

The ID of the media to update.

Query parameters
titlestringOptional

The new title of updated media.

latnumberOptional

Latitude of geolocation data.

lngnumberOptional

Longitude of geolocation data.

descriptionstringOptional

The new description of updated media.

Responses
chevron-right
200

OK

application/json
Responseany
put
/api/v3/medias/{mediaId}

hashtag
Delete a media

Endpoint: DELETE /api/v3/medias/{mediaId} Description: Permanently deletes the specified media from storage. When to use:

  • Free up storage space once media has been archived.

  • Remove sensitive snapshots to comply with GDPR or internal policy.

hashtag
Delete media by ID

delete
/api/v3/medias/{mediaId}
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
mediaIdintegerRequired

The ID of the media to delete.

Responses
chevron-right
200

OK

application/json
Responseany
delete
/api/v3/medias/{mediaId}

hashtag
Use case:

PreviousEnterprises, users and user groups managementNextMetrics and reports

Last updated