openapi: 3.2.0
info:
  title: Media download API
  version: 1.0.0
servers:
- url: https://{your-bynder-domain}/
security:
- OAuth2:
  - MEDIAHIGHRES
  - ARCHIVEDOWNLOAD
  - DOWNLOADWATERMARK
  - KEYVISUALSDOWNLOAD
- permanentToken:
  - MEDIAHIGHRES
  - ARCHIVEDOWNLOAD
  - DOWNLOADWATERMARK
  - KEYVISUALSDOWNLOAD
tags:
- name: Media download
  description: ''
paths:
  /api/v4/media/{id}/download:
    get:
      summary: Retrieve asset download location
      description: 'Retrieve the download location for an asset.

        __Warning:__ Requires the MEDIAHIGHRES security role.

        __Warning:__ Requires the ARCHIVEDOWNLOAD security role if the asset in question is archived.

        __Warning:__ Requires the DOWNLOADWATERMARK security role if the asset in question is watermarked.

        __Warning:__ Requires the KEYVISUALSDOWNLOAD security role if the asset in question is marked as limited usage.

        '
      tags:
      - Media download
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-0000-0000000000000000
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - original
          - additional
          default: original
      responses:
        '200':
          description: URL from which you can download the requested asset file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  disclaimer:
                    type: string
                    example: <p>1. The photographs and video in the mediabank are to be used by anyone and everyone.</p>
                  s3_file:
                    type: string
                    example: ___TEMPORARY_DOWNLOAD_URL___
        '400':
          description: Invalid type
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid type
                  statuscode:
                    type: string
                    example: '400'
        '404':
          description: Original file not available
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Original file not available
                  statuscode:
                    type: string
                    example: '404'
  /api/v4/media/{id}/{version}/download:
    get:
      summary: Retrieve asset version download location
      description: 'Retrieve the download location for a specific asset version.

        __Warning:__ Requires the MEDIAHIGHRES security role.

        __Warning:__ Requires the ARCHIVEDOWNLOAD security role if the asset in question is archived.

        __Warning:__ Requires the DOWNLOADWATERMARK security role if the asset in question is watermarked.

        __Warning:__ Requires the KEYVISUALSDOWNLOAD security role if the asset in question is marked as limited usage.

        '
      tags:
      - Media download
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-0000-0000000000000000
      - name: version
        in: path
        required: true
        schema:
          type: integer
          example: '3'
      responses:
        '200':
          description: URL from which you can download the requested asset file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  disclaimer:
                    type: string
                    example: <p>1. The photographs and video in the mediabank are to be used by anyone and everyone.</p>
                  s3_file:
                    type: string
                    example: ___TEMPORARY_DOWNLOAD_URL___
  /api/v4/media/{id}/download/{itemId}:
    get:
      summary: Retrieve specific asset item download location
      description: 'Retrieve the download location for a specific asset item.

        __Warning:__ Requires the MEDIAHIGHRES security role.

        __Warning:__ Requires the ARCHIVEDOWNLOAD security role if the asset in question is archived.

        __Warning:__ Requires the DOWNLOADWATERMARK security role if the asset in question is watermarked.

        __Warning:__ Requires the KEYVISUALSDOWNLOAD security role if the asset in question is marked as limited usage.

        '
      tags:
      - Media download
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-0000-0000000000000000
      - name: itemId
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-0000-0000000000000000
      - name: hash
        in: query
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: URL from which you can download the requested asset file.
          content:
            application/json:
              schema:
                type: object
                properties:
                  disclaimer:
                    type: string
                    example: <p>1. The photographs and video in the mediabank are to be used by anyone and everyone.</p>
                  s3_file:
                    type: string
                    example: ___TEMPORARY_DOWNLOAD_URL___
components:
  securitySchemes:
    permanentToken:
      type: apiKey
      in: header
      name: Authorization
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{your-bynder-domain}/v6/authentication/oauth2/token
          scopes:
            MEDIAHIGHRES: ''
            ARCHIVEDOWNLOAD: ''
            DOWNLOADWATERMARK: ''
            KEYVISUALSDOWNLOAD: ''
        authorizationCode:
          authorizationUrl: https://{your-auth-url}
          tokenUrl: https://{your-bynder-domain}/v6/authentication/oauth2/token
          scopes:
            MEDIAHIGHRES: ''
            ARCHIVEDOWNLOAD: ''
            DOWNLOADWATERMARK: ''
            KEYVISUALSDOWNLOAD: ''