Media API BETA

The Media API can be used to query, download and delete media items such as audio files for use with other Nexmo APIs.

Download OpenAPI 3 Definition
Improve this specification

List and search media items

Retrieve information about multiple media items with the ability to search and paginate.

GET https://api.nexmo.com/v3/media

Query Parameter

Key Description Example Default
order
string

The order of search results.


Must be one of: assending or descending 		assending descending
page_index
integer

Which page to retrieve in pagination

 1 0
page_size
integer

How many items at most per page

 50 20
start_time
string

Retrieve results created on or after this timestap.

 2020-01-01T14:00:00.000Z 1 week ago
end_time
string

Retrieve results created on or before this timestamp.

 2020-01-01T14:00:00.000Z None

View response field descriptions

Response Fields

Field Description
page_size

The amount of records returned in this response.
page_index

The page_index used in your request.
count

The total number of records returned by your request.
_embedded

A collection of media items. See retrieve a media item for a description of the returned fields
Field Description
media
array of objects
Field Description
id

A UUID representing the object.
original_file_name

The filename of the object as it was originally uploaded.
mime_type

The IETF MIME type of the file.
account_id

The ID of your Nexmo account. This is the same as your API key.
store_id

An internal identifier of how the file is stored.
max_downloads_allowed

The maximum number of times the file may be downloaded.
times_downloaded

The number of times the file has been downloaded.
etag

An identifier for the content. This will change if the content of the file has been changed (i.e. if you upload a new version of the file). For more information see Wikipedia: HTTP ETag
media_size

The size of the file in bytes
time_created

A timestamp for the time that the file was created
time_last_updated

A timestamp for the time that the file was last modified
public

Whether the item is available for download without authentication.
metadata_primary

A user set string containing metadata about the media file.
metadata_secondary

A user set string containing further metadata about the media file.

 
{
  "page_size": 20,
  "page_index": 0,
  "_links": {
    "self": {
      "href": "/v3/media?page_size=20&account_id=abcd1234&order=descending"
    },
    "first": {
      "href": "/v3/media?page_size=20&account_id=abcd1234&order=descending"
    },
    "last": {
      "href": "/v3/media?page_size=20&account_id=abcd1234&order=descending"
    }
  },
  "count": 1,
  "_embedded": {
    "media": [
      {
        "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
        "original_file_name": "test.wav",
        "mime_type": "audio/vnd.wave",
        "account_id": "abcd1234",
        "store_id": "s3",
        "max_downloads_allowed": 0,
        "times_downloaded": 1,
        "etag": "aaaaaaaabbbbccccdddd0123456789ab",
        "media_size": 1234567,
        "time_created": "2020-01-01T14:00:00.000Z",
        "time_last_updated": "2020-01-01T14:00:00.000Z",
        "public": false,
        "metadata_primary": "abc123",
        "metadata_secondary": "abc123"
      }
    ]
  }
}

Retrieve a media item

Retrieve information about a single media item

GET https://api.nexmo.com/v3/media/:id/info

View response field descriptions

Response Fields

Field Description
id

A UUID representing the object.
original_file_name

The filename of the object as it was originally uploaded.
mime_type

The IETF MIME type of the file.
account_id

The ID of your Nexmo account. This is the same as your API key.
store_id

An internal identifier of how the file is stored.
max_downloads_allowed

The maximum number of times the file may be downloaded.
times_downloaded

The number of times the file has been downloaded.
etag

An identifier for the content. This will change if the content of the file has been changed (i.e. if you upload a new version of the file). For more information see Wikipedia: HTTP ETag
media_size

The size of the file in bytes
time_created

A timestamp for the time that the file was created
time_last_updated

A timestamp for the time that the file was last modified
public

Whether the item is available for download without authentication.
metadata_primary

A user set string containing metadata about the media file.
metadata_secondary

A user set string containing further metadata about the media file.

 
{
  "id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "original_file_name": "test.wav",
  "mime_type": "audio/vnd.wave",
  "account_id": "abcd1234",
  "store_id": "s3",
  "max_downloads_allowed": 0,
  "times_downloaded": 1,
  "etag": "aaaaaaaabbbbccccdddd0123456789ab",
  "media_size": 1234567,
  "time_created": "2020-01-01T14:00:00.000Z",
  "time_last_updated": "2020-01-01T14:00:00.000Z",
  "public": false,
  "metadata_primary": "abc123",
  "metadata_secondary": "abc123"
}

Update a media item

Update a previously created media item by ID.

PUT https://api.nexmo.com/v3/media/:id/info

Request body multipart/form-data

Key Description Example Default
public
boolean

Whether the item is publicly available without authentication.

 true None
metadata_primary
string

A string containing metadata about the media file.

 foo,bar None
metadata_secondary
string

A string containing further metadata about the media file.

 123 None
title
string

A string containing a title for the media file.

 Very important recording None
description
string

A description of the media file.

 This is a very important recording. Do not delete. None
mime_type
string

The MIME type of the media file.

 audio/vnd.wave None
max_downloads_allowed
integer

The maximum number of times the file may be downloaded. Unlimited when not provided.

 100 None 
Successfully updated

Delete a media item

Delete a previously created media item by ID.

DELETE https://api.nexmo.com/v3/media/:id/info 
Successfully deleted