{ "openapi": "3.0.0", "info": { "version": "1.0.2", "title": "Media API", "x-metaTitle": "Vonage Media API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Media API in this reference guide. Learn more in Vonage's API documentation.", "description": "The Media API can be used to query, download and delete media items such as audio files for use with other Nexmo APIs.", "x-label": "BETA", "contact": { "name": "Nexmo DevRel", "email": "devrel@nexmo.com", "url": "https://developer.nexmo.com/" } }, "servers": [ { "url": "https://api.nexmo.com/v3/media" } ], "paths": { "/": { "get": { "summary": "List and search media items", "operationId": "list-and-search-media-items", "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "description": "Retrieve the metadata for multiple media items, with the ability to search and paginate.", "parameters": [ { "name": "order", "description": "The order of search results.", "in": "query", "schema": { "type": "string", "example": "ascending", "enum": [ "ascending", "descending" ], "default": "descending" } }, { "name": "page_index", "description": "Which page to retrieve in pagination", "in": "query", "schema": { "type": "integer", "example": 1, "default": 0 } }, { "name": "page_size", "description": "How many items at most per page", "in": "query", "schema": { "type": "integer", "example": 50, "default": 20 } }, { "name": "start_time", "description": "Retrieve results created on or after this timestap.", "in": "query", "schema": { "type": "string", "example": "2020-01-01T14:00:00.000Z", "default": "1 week ago" }, "x-default-is-meta": true }, { "name": "end_time", "description": "Retrieve results created on or before this timestamp.", "in": "query", "schema": { "type": "string", "example": "2020-01-01T14:00:00.000Z" } } ], "responses": { "200": { "description": "Successfully retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "page_size": { "type": "integer", "description": "The amount of records returned in this response.", "default": 0, "example": 20 }, "page_index": { "type": "integer", "description": "The `page_index` used in your request.", "default": 0, "example": 0 }, "_links": { "type": "object", "properties": { "self": { "type": "object", "properties": { "href": { "type": "string", "default": "", "example": "/v3/media?page_size=20&account_id=abcd1234&order=descending" } } }, "first": { "type": "object", "properties": { "href": { "type": "string", "default": "", "example": "/v3/media?page_size=20&account_id=abcd1234&order=descending" } } }, "last": { "type": "object", "properties": { "href": { "type": "string", "default": "", "example": "/v3/media?page_size=20&account_id=abcd1234&order=descending" } } } } }, "count": { "type": "integer", "description": "The total number of records returned by your request.", "default": 0, "example": 1 }, "_embedded": { "type": "object", "description": "A collection of media items. See [retrieve a media item](#retrieve-a-media-item) for a description of the returned fields", "properties": { "media": { "type": "array", "items": { "$ref": "#/components/schemas/Media" } } } } } } } } } } } }, "/:id/info": { "get": { "summary": "Retrieve a media item's metadata", "operationId": "retrieve-a-media-item", "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "description": "Retrieve the metadata for a media item", "responses": { "200": { "description": "Successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Media" } } } } } }, "put": { "summary": "Update a media item's metadata", "operationId": "update-a-media-item", "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "description": "Update the metadata of a previously created media item.", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "public": { "description": "Whether the item is publicly available without authentication.", "type": "boolean", "example": true }, "metadata_primary": { "description": "A string containing metadata about the media file.", "type": "string", "example": "foo,bar" }, "metadata_secondary": { "description": "A string containing further metadata about the media file.", "type": "string", "example": "123" }, "title": { "description": "A string containing a title for the media file.", "type": "string", "example": "Very important recording" }, "description": { "description": "A description of the media file.", "type": "string", "example": "This is a very important recording. Do not delete." }, "mime_type": { "description": "The MIME type of the media file.", "type": "string", "example": "audio/vnd.wave" }, "max_downloads_allowed": { "description": "The maximum number of times the file may be downloaded. Unlimited when not provided.", "type": "integer", "example": 100 } } } } } }, "responses": { "204": { "description": "Successfully updated" } } } }, "/:id": { "get": { "summary": "Retrieve a media item's content", "operationId": "retrieve-a-media-file", "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "description": "Download the file associated with a media item", "responses": { "200": { "description": "Successfully retrieved
\nThe Content-Type header will specify the MIME type of the response body\n", "content": { "*/*": { "schema": { "type": "object" } } } } } }, "delete": { "summary": "Delete a media item", "operationId": "delete-a-media-item", "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "description": "Delete a previously created media item by ID.", "responses": { "204": { "description": "Successfully deleted" } } } } }, "components": { "schemas": { "Media": { "type": "object", "properties": { "id": { "type": "string", "description": "A UUID representing the object.", "example": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab" }, "original_file_name": { "type": "string", "description": "The filename of the object as it was originally uploaded.", "example": "test.wav" }, "mime_type": { "type": "string", "description": "The IETF MIME type of the file.", "example": "audio/vnd.wave" }, "account_id": { "type": "string", "description": "The ID of your Nexmo account. This is the same as your API key.", "example": "abcd1234" }, "store_id": { "type": "string", "description": "An internal identifier of how the file is stored.", "example": "s3" }, "max_downloads_allowed": { "type": "integer", "description": "The maximum number of times the file may be downloaded.", "example": 0 }, "times_downloaded": { "type": "integer", "description": "The number of times the file has been downloaded.", "example": 1 }, "etag": { "type": "string", "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" }, "media_size": { "type": "integer", "description": "The size of the file in bytes", "example": 1234567 }, "time_created": { "type": "string", "description": "A timestamp for the time that the file was created", "example": "2020-01-01T14:00:00.000Z" }, "time_last_updated": { "type": "string", "description": "A timestamp for the time that the file was last modified", "example": "2020-01-01T14:00:00.000Z" }, "public": { "type": "boolean", "description": "Whether the item is available for download without authentication.", "example": false }, "metadata_primary": { "type": "string", "description": "A user set string containing metadata about the media file." }, "metadata_secondary": { "type": "string", "description": "A user set string containing further metadata about the media file." } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "basicAuth": { "type": "http", "scheme": "basic" } } } }