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

Media

The Media object contains information about the request and details of the media object.

  • Key
    Description
  • 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.

Example Model

{
  "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
}

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: assendingordescending
    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


200 HTTP 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
      }
    ]
  }
}

Retrieve a media item

Retrieve information about a single media item

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

View response field descriptions


200 HTTP 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
}

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

204 HTTP response 

No content

Delete a media item

Delete a previously created media item by ID.

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

204 HTTP response 

No content