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
COMMUNITYNO AUTH0 INSTALLS
OpenAPI Specificationv3.0
{
"openapi": "3.0.0",
"servers": [
{
"url": "https://api.nexmo.com/v3/media"
}
],
"info": {
"contact": {
"email": "devrel@nexmo.com",
"name": "Nexmo DevRel",
"url": "https://developer.nexmo.com/"
},
"description": "The Media API can be used to query, download and delete media items such as audio files for use with other Nexmo APIs.",
"title": "Media API",
"version": "1.0.2",
"x-label": "BETA",
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_www.vonage.com_content_dam_vonage_us-en_api_illustrations_Mobile_APIs_Services.svg"
},
"x-origin": [
{
"format": "openapi",
"url": "https://raw.githubusercontent.com/nexmo/api-specification/master/definitions/media.yml",
"version": "3.0"
}
],
"x-providerName": "nexmo.com",
"x-serviceName": "media"
},
"paths": {
"/": {
"get": {
"description": "Retrieve information about multiple media items with the ability to search and paginate.",
"operationId": "list-and-search-media-items",
"parameters": [
{
"description": "The order of search results.",
"in": "query",
"name": "order",
"schema": {
"default": "descending",
"enum": [
"ascending",
"descending"
],
"example": "ascending",
"type": "string"
}
},
{
"description": "Which page to retrieve in pagination",
"in": "query",
"name": "page_index",
"schema": {
"default": 0,
"example": 1,
"type": "integer"
}
},
{
"description": "How many items at most per page",
"in": "query",
"name": "page_size",
"schema": {
"default": 20,
"example": 50,
"type": "integer"
}
},
{
"description": "Retrieve results created on or after this timestap.",
"in": "query",
"name": "start_time",
"schema": {
"default": "1 week ago",
"example": "2020-01-01T14:00:00.000Z",
"type": "string"
},
"x-default-is-meta": true
},
{
"description": "Retrieve results created on or before this timestamp.",
"in": "query",
"name": "end_time",
"schema": {
"example": "2020-01-01T14:00:00.000Z",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"_embedded": {
"description": "A collection of media items. See [retrieve a media item](#retrieve-a-media-item) for a description of the returned fields",
"properties": {
"media": {
"items": {
"$ref": "#/components/schemas/Media"
},
"type": "array"
}
},
"type": "object"
},
"_links": {
"properties": {
"first": {
"properties": {
"href": {
"default": "",
"example": "/v3/media?page_size=20&account_id=abcd1234&order=descending",
"type": "string"
}
},
"type": "object"
},
"last": {
"properties": {
"href": {
"default": "",
"example": "/v3/media?page_size=20&account_id=abcd1234&order=descending",
"type": "string"
}
},
"type": "object"
},
"self": {
"properties": {
"href": {
"default": "",
"example": "/v3/media?page_size=20&account_id=abcd1234&order=descending",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"count": {
"default": 0,
"description": "The total number of records returned by your request.",
"example": 1,
"type": "integer"
},
"page_index": {
"default": 0,
"description": "The `page_index` used in your request.",
"example": 0,
"type": "integer"
},
"page_size": {
"default": 0,
"description": "The amount of records returned in this response.",
"example": 20,
"type": "integer"
}
},
"type": "object"
}
}
},
"description": "Successfully retrieved"
}
},
"summary": "List and search media items"
}
},
"/:id": {
"delete": {
"description": "Delete a previously created media item by ID.",
"operationId": "delete-a-media-item",
"responses": {
"204": {
"description": "Successfully deleted"
}
},
"summary": "Delete a media item"
}
},
"/:id/info": {
"get": {
"description": "Retrieve information about a single media item",
"operationId": "retrieve-a-media-item",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Media"
}
}
},
"description": "Successfully retrieved"
}
},
"summary": "Retrieve a media item"
},
"put": {
"description": "Update a previously created media item by ID.",
"operationId": "update-a-media-item",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"properties": {
"description": {
"description": "A description of the media file.",
"example": "This is a very important recording. Do not delete.",
"type": "string"
},
"max_downloads_allowed": {
"description": "The maximum number of times the file may be downloaded. Unlimited when not provided.",
"example": 100,
"type": "integer"
},
"metadata_primary": {
"description": "A string containing metadata about the media file.",
"example": "foo,bar",
"type": "string"
},
"metadata_secondary": {
"description": "A string containing further metadata about the media file.",
"example": "123",
"type": "string"
},
"mime_type": {
"description": "The MIME type of the media file.",
"example": "audio/vnd.wave",
"type": "string"
},
"public": {
"description": "Whether the item is publicly available without authentication.",
"example": true,
"type": "boolean"
},
"title": {
"description": "A string containing a title for the media file.",
"example": "Very important recording",
"type": "string"
}
},
"type": "object"
}
}
}
},
"responses": {
"204": {
"description": "Successfully updated"
}
},
"summary": "Update a media item"
}
}
},
"components": {
"schemas": {
"Media": {
"properties": {
"account_id": {
"description": "The ID of your Nexmo account. This is the same as your API key.",
"example": "abcd1234",
"type": "string"
},
"etag": {
"description": "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](https://en.wikipedia.org/wiki/HTTP_ETag)",
"example": "aaaaaaaabbbbccccdddd0123456789ab",
"type": "string"
},
"id": {
"description": "A UUID representing the object.",
"example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"type": "string"
},
"max_downloads_allowed": {
"description": "The maximum number of times the file may be downloaded.",
"example": 0,
"type": "integer"
},
"media_size": {
"description": "The size of the file in bytes",
"example": 1234567,
"type": "integer"
},
"metadata_primary": {
"description": "A user set string containing metadata about the media file.",
"type": "string"
},
"metadata_secondary": {
"description": "A user set string containing further metadata about the media file.",
"type": "string"
},
"mime_type": {
"description": "The IETF MIME type of the file.",
"example": "audio/vnd.wave",
"type": "string"
},
"original_file_name": {
"description": "The filename of the object as it was originally uploaded.",
"example": "test.wav",
"type": "string"
},
"public": {
"description": "Whether the item is available for download without authentication.",
"example": false,
"type": "boolean"
},
"store_id": {
"description": "An internal identifier of how the file is stored.",
"example": "s3",
"type": "string"
},
"time_created": {
"description": "A timestamp for the time that the file was created",
"example": "2020-01-01T14:00:00.000Z",
"type": "string"
},
"time_last_updated": {
"description": "A timestamp for the time that the file was last modified",
"example": "2020-01-01T14:00:00.000Z",
"type": "string"
},
"times_downloaded": {
"description": "The number of times the file has been downloaded.",
"example": 1,
"type": "integer"
}
},
"type": "object"
}
}
}
}