openapi: "3.0.0"
info:
  version: 1.0.1
  title: Media API
  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
      description: Retrieve information about 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
      operationId: retrieve-a-media-item
      description: Retrieve information about a single media item
      responses:
        '200':
          description: Successfully retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Media"
    put:
      summary: Update a media item
      operationId: update-a-media-item
      description: Update a previously created media item by ID.
      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
    delete:
      summary: Delete a media item
      operationId: delete-a-media-item
      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.
