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.

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.

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
200

Good case

application/json
Responseany
get
/api/v3/medias
GET /api/v3/medias HTTP/1.1
Host: cloud.apizee.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Good case

{
  "total": 200,
  "next_offset": 10,
  "data": [
    {
      "id": 1,
      "hash": "effd54e0-4dbb-11ea-884d-5df05d0af01",
      "created": "2020-01-01T00:00:00+00:00",
      "owner": {
        "id": 1000,
        "name": "John Doe"
      },
      "title": "media-3npGq6km5jx2s4ct-1538745137",
      "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "filename": "media-3npGq6km5jx2s4ct-1538745137.png",
      "status": "completed",
      "media_type": "image",
      "source_type": "unknown",
      "filesize": 122619,
      "geoloc": {
        "lat": -17.494911,
        "lng": -149.493584
      },
      "thumbnail_url": "https://cloud.apizee.com/media/showVideo/1/hash/effd54e0-4dbb-11ea-884d-5df05d0af01?thumbnail=1",
      "url": "https://cloud.apizee.com/media/showVideo/1/hash/effd54e0-4dbb-11ea-884d-5df05d0af01"
    }
  ]
}

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.

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
200

Good case

application/json
Responseany
get
/api/v3/medias/{mediaId}
GET /api/v3/medias/{mediaId} HTTP/1.1
Host: cloud.apizee.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Good case

{
  "id": 1,
  "hash": "effd54e0-4dbb-11ea-884d-5df05d0af01",
  "created": "2020-01-01T00:00:00+00:00",
  "owner": {
    "id": 1000,
    "name": "John Doe"
  },
  "title": "media-3npGq6km5jx2s4ct-1538745137",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "filename": "media-3npGq6km5jx2s4ct-1538745137.png",
  "status": "completed",
  "media_type": "image",
  "source_type": "unknown",
  "filesize": 122619,
  "geoloc": {
    "lat": -17.494911,
    "lng": -149.493584
  },
  "thumbnail_url": "https://cloud.apizee.com/media/showVideo/1/hash/effd54e0-4dbb-11ea-884d-5df05d0af01?thumbnail=1",
  "url": "https://cloud.apizee.com/media/showVideo/1/hash/effd54e0-4dbb-11ea-884d-5df05d0af01"
}

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

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.

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
200

Download the media.

No content
get
/api/v3/medias/{mediaId}/download
GET /api/v3/medias/{mediaId}/download HTTP/1.1
Host: cloud.apizee.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

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.

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
200

OK

application/json
Responseany
put
/api/v3/medias/{mediaId}
PUT /api/v3/medias/{mediaId} HTTP/1.1
Host: cloud.apizee.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "hash": "effd54e0-4dbb-11ea-884d-5df05d0af01",
  "created": "2020-01-01T00:00:00+00:00",
  "owner": {
    "id": 1000,
    "name": "John Doe"
  },
  "title": "media-3npGq6km5jx2s4ct-1538745137",
  "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "filename": "media-3npGq6km5jx2s4ct-1538745137.png",
  "status": "completed",
  "media_type": "image",
  "source_type": "unknown",
  "filesize": 122619,
  "geoloc": {
    "lat": -17.494911,
    "lng": -149.493584
  },
  "thumbnail_url": "https://cloud.apizee.com/media/showVideo/1/hash/effd54e0-4dbb-11ea-884d-5df05d0af01?thumbnail=1",
  "url": "https://cloud.apizee.com/media/showVideo/1/hash/effd54e0-4dbb-11ea-884d-5df05d0af01"
}

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.

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
200

OK

application/json
Responseany
delete
/api/v3/medias/{mediaId}
DELETE /api/v3/medias/{mediaId} HTTP/1.1
Host: cloud.apizee.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[]

Use case:

PreviousEnterprises, users and user groups managementNextMetrics and reports

Last updated