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