Available Operations
 
 

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.

Available Operations:

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/
Host https://api.nexmo.com
GET /v3/media/

Query Parameter

order
string

The order of search results.

Must be one of: ascending or descending
page_index
integer

Which page to retrieve in pagination

page_size
integer

How many items at most per page

start_time
string

Retrieve results created on or after this timestap.

end_time
string

Retrieve results created on or before this timestamp.

Responses

200 Successfully retrieved
page_size
integer

The amount of records returned in this response.

page_index
integer

The page_index used in your request.

count
integer

The total number of records returned by your request.

_embedded
object

A collection of media items. See retrieve a media item for a description of the returned fields

media
array of objects
id
string

A UUID representing the object.

original_file_name
string

The filename of the object as it was originally uploaded.

mime_type
string

The IETF MIME type of the file.

account_id
string

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

store_id
string

An internal identifier of how the file is stored.

max_downloads_allowed
integer

The maximum number of times the file may be downloaded.

times_downloaded
integer

The number of times the file has been downloaded.

etag
string

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
integer

The size of the file in bytes

time_created
string

A timestamp for the time that the file was created

time_last_updated
string

A timestamp for the time that the file was last modified

public
boolean

Whether the item is available for download without authentication.

metadata_primary
string

A user set string containing metadata about the media file.

metadata_secondary
string

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

Example Responses

200
{
  "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
Host https://api.nexmo.com
GET /v3/media/:id/info

Responses

200 Successfully retrieved
id
string

A UUID representing the object.

original_file_name
string

The filename of the object as it was originally uploaded.

mime_type
string

The IETF MIME type of the file.

account_id
string

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

store_id
string

An internal identifier of how the file is stored.

max_downloads_allowed
integer

The maximum number of times the file may be downloaded.

times_downloaded
integer

The number of times the file has been downloaded.

etag
string

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
integer

The size of the file in bytes

time_created
string

A timestamp for the time that the file was created

time_last_updated
string

A timestamp for the time that the file was last modified

public
boolean

Whether the item is available for download without authentication.

metadata_primary
string

A user set string containing metadata about the media file.

metadata_secondary
string

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

Example Responses

200
{
  "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
Host https://api.nexmo.com
PUT /v3/media/:id/info

Request body multipart/form-data

public
boolean

Whether the item is publicly available without authentication.

metadata_primary
string

A string containing metadata about the media file.

metadata_secondary
string

A string containing further metadata about the media file.

title
string

A string containing a title for the media file.

description
string

A description of the media file.

mime_type
string

The MIME type of the media file.

max_downloads_allowed
integer

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

Example Request

{
  "public": true,
  "metadata_primary": "foo,bar",
  "metadata_secondary": "123",
  "title": "Very important recording",
  "description": "This is a very important recording. Do not delete.",
  "mime_type": "audio/vnd.wave",
  "max_downloads_allowed": 100
}

Example Responses

204
Successfully updated

Delete a media item

Delete a previously created media item by ID.

DELETE https://api.nexmo.com/v3/media/:id
Host https://api.nexmo.com
DELETE /v3/media/:id

Example Responses

204
Successfully deleted