Media API

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 Specification

Available Operations

List and search media items

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

gethttps://api.nexmo.com/v3/media/

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Query Parameters

order

string

Defaultdescending

exampleascending

The order of search results.

Must be one of:ascendingdescending

page_index

integer

example1

Which page to retrieve in pagination

page_size

integer

Default20

example50

How many items at most per page

start_time

string

Default1 week ago

example2020-01-01T14:00:00.000Z

Retrieve results created on or after this timestap.

end_time

string

example2020-01-01T14:00:00.000Z

Retrieve results created on or before this timestamp.

Responses
Content Type
application/json

Successfully retrieved

page_size

integer

example20

The amount of records returned in this response.

page_index

integer

The page_index used in your request.

_links

object

self

object

href

string

example/v3/media?page_size=20&account_id=abcd1234&order=descending

first

object

href

string

example/v3/media?page_size=20&account_id=abcd1234&order=descending

last

object

href

string

example/v3/media?page_size=20&account_id=abcd1234&order=descending

count

integer

example1

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

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

A UUID representing the object.

original_file_name

string

exampletest.wav

The filename of the object as it was originally uploaded.

mime_type

string

exampleaudio/vnd.wave

The IETF MIME type of the file.

account_id

string

exampleabcd1234

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

store_id

string

examples3

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

example1

The number of times the file has been downloaded.

etag

string

exampleaaaaaaaabbbbccccdddd0123456789ab

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

example1234567

The size of the file in bytes

time_created

string

example2020-01-01T14:00:00.000Z

A timestamp for the time that the file was created

time_last_updated

string

example2020-01-01T14:00:00.000Z

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 Response

{
   "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": "string",
            "metadata_secondary": "string"
         }
      ]
   }
}

Retrieve a media item

Retrieve information about a single media item

gethttps://api.nexmo.com/v3/media/:id/info

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Responses
Content Type
application/json

Successfully retrieved

string

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

A UUID representing the object.

original_file_name

string

exampletest.wav

The filename of the object as it was originally uploaded.

mime_type

string

exampleaudio/vnd.wave

The IETF MIME type of the file.

account_id

string

exampleabcd1234

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

store_id

string

examples3

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

example1

The number of times the file has been downloaded.

etag

string

exampleaaaaaaaabbbbccccdddd0123456789ab

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

example1234567

The size of the file in bytes

time_created

string

example2020-01-01T14:00:00.000Z

A timestamp for the time that the file was created

time_last_updated

string

example2020-01-01T14:00:00.000Z

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 Response

{
   "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": "string",
   "metadata_secondary": "string"
}

Update a media item

Update a previously created media item by ID.

puthttps://api.nexmo.com/v3/media/:id/info

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
multipart/form-data

public

boolean

exampletrue

Whether the item is publicly available without authentication.

metadata_primary

string

examplefoo,bar

A string containing metadata about the media file.

metadata_secondary

string

example123

A string containing further metadata about the media file.

title

string

exampleVery important recording

A string containing a title for the media file.

description

string

exampleThis is a very important recording. Do not delete.

A description of the media file.

mime_type

string

exampleaudio/vnd.wave

The MIME type of the media file.

max_downloads_allowed

integer

example100

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

Example Request

POST /v3/media/:id/info HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 204

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

POST /v3/media/:id/info HTTP/1.1
Host: api.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 204

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

Responses

Successfully updated

Delete a media item

Delete a previously created media item by ID.

deletehttps://api.nexmo.com/v3/media/:id

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Responses

Successfully deleted

Media API

Available Operations

List and search media items

Authentication

Query Parameters

Responses Content Typeapplication/json

Example Response

Retrieve a media item

Authentication

Responses Content Typeapplication/json

Example Response

Update a media item

Authentication

Request Body Content Typemultipart/form-data

Example Request

Responses

Delete a media item

Authentication

Responses

Responses
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
multipart/form-data