SmartNews Media File API

openapi: 3.2.0
info:
  version: 3.0.1
  title: SmartNews Marketing Media File API
  description: '# Previous Versions

    - SmartNews Marketing API (2.0.0): https://ads.smartnews.com/developers/deprecated/v2/index.html

    - **API v2 has been fully disabled.** All requests to `api/ma/v2/*` endpoints now return a `410 Gone` error.'
  contact:
    name: SmartNews Ads Support
servers:
- url: https://ads.smartnews.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: media File
paths:
  /api/ma/v3/ad_accounts/{ad_account_id}/media_files:
    get:
      tags:
      - media File
      summary: List Media Files
      operationId: getMediaFiles
      description: 'Get a paginated list of media files under the specified ad account.

        Note: Soft-deleted (inactive) media files are not returned by this endpoint.'
      parameters:
      - name: Accept-Language
        in: header
        schema:
          $ref: '#/components/schemas/AcceptLanguage'
      - name: ad_account_id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: query
        in: query
        required: false
        description: 'Search query string. Filters media files whose `file_name` contains this value (case-insensitive).

          '
        schema:
          type: string
          minLength: 1
          maxLength: 256
      - name: media_type
        in: query
        required: true
        description: Filter by media type.
        schema:
          $ref: '#/components/schemas/MediaType'
      - name: min_width
        in: query
        required: false
        description: 'Minimum width in pixels. Only media files with `width >= min_width` will be returned.

          '
        schema:
          type: integer
          minimum: 1
      - name: min_height
        in: query
        required: false
        description: 'Minimum height in pixels. Only media files with `height >= min_height` will be returned.

          '
        schema:
          type: integer
          minimum: 1
      - name: aspect_ratio_type
        in: query
        required: false
        description: 'Filter media files by the predefined aspect ratio. Applies to IMAGE media files.

          Only assets whose primary image has the specified `aspect_ratio_type` are returned.

          '
        schema:
          $ref: '#/components/schemas/AspectRatioType'
      - name: sort
        in: query
        required: false
        description: 'Specify the sort order for the results. The format is `{field}:{order}` (e.g. `created_at:desc`).

          Supported fields: `created_at`, `updated_at`. Defaults to `created_at:desc`.

          '
        schema:
          type: array
          items:
            type: string
            pattern: ^(created_at|updated_at):(asc|desc)$
          minItems: 1
          maxItems: 1
          example:
          - created_at:desc
          default:
          - created_at:desc
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      - name: page
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/Page'
      responses:
        '200':
          description: A paginated list of media file objects with pagination metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFilePaginatedResponse'
        '401':
          description: Unauthorized. The access token is either expired or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
              x-examples:
                expiredToken:
                  summary: Access token has expired.
                  value:
                    error:
                      type: UNAUTHORIZED
                      message: Token has expired.
                      retriable: false
                invalidToken:
                  summary: Access token is invalid.
                  value:
                    error:
                      type: UNAUTHORIZED
                      message: Token is invalid.
                      retriable: false
        '403':
          description: Forbidden. Access to the requested resource is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
              examples:
                terms_of_service_not_accepted:
                  summary: User has not accepted the terms of service.
                  value:
                    error:
                      type: TERMS_OF_SERVICE_NOT_ACCEPTED
                      message: The owner of the assets must accept the Ads terms of service.
                      terms_of_service_path: /terms/agreement
                      retriable: false
                access_denied:
                  summary: Access is denied due to insufficient permissions.
                  value:
                    error:
                      type: ACCESS_DENIED
                      message: Access denied.
                      retriable: false
        '404':
          description: The user doesn't have permission to access the resource or the ad account doesn't exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundErrorResponse'
        '429':
          description: Too many requests were made within a short period. Wait a while and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorResponse'
        '500':
          description: Unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponse'
        '503':
          description: The service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableErrorResponse'
    post:
      tags:
      - media File
      summary: Create a Media File
      operationId: postMedia
      description: Create a Media File which can be used in Ad Creatives.
      parameters:
      - name: Accept-Language
        in: header
        schema:
          $ref: '#/components/schemas/AcceptLanguage'
      - name: ad_account_id
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MediaFileRequest'
      responses:
        '200':
          description: '`images` and `videos` fields are required in the response by following the rules:

            | Media Type | Required Fields       |

            |------------|-----------------------|

            | IMAGE      | `images`              |

            | VIDEO      | `images`, `videos`    |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFileResponse'
        '401':
          description: Unauthorized. The access token is either expired or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
              x-examples:
                expiredToken:
                  summary: Access token has expired.
                  value:
                    error:
                      type: UNAUTHORIZED
                      message: Token has expired.
                      retriable: false
                invalidToken:
                  summary: Access token is invalid.
                  value:
                    error:
                      type: UNAUTHORIZED
                      message: Token is invalid.
                      retriable: false
        '403':
          description: Forbidden. Access to the requested resource is denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
              examples:
                terms_of_service_not_accepted:
                  summary: User has not accepted the terms of service.
                  value:
                    error:
                      type: TERMS_OF_SERVICE_NOT_ACCEPTED
                      message: The owner of the assets must accept the Ads terms of service.
                      terms_of_service_path: /terms/agreement
                      retriable: false
                access_denied:
                  summary: Access is denied due to insufficient permissions.
                  value:
                    error:
                      type: ACCESS_DENIED
                      message: Access denied.
                      retriable: false
        '409':
          description: Business Error. The request body is formatted correctly but not correct in the business definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessErrorResponse'
        '422':
          description: Validation Error. The request body doesn't pass the format check or some fields contain invalid values. The `error_fields` shows the fields that don't pass the validations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: Too many requests were made within a short period. Wait a while and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorResponse'
        '500':
          description: Unexpected error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnexpectedErrorResponse'
        '503':
          description: The service is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUnavailableErrorResponse'
        '504':
          description: Upload MediaFile timeout error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayTimeoutErrorResponse'
components:
  schemas:
    UnauthorizedError:
      type: object
      allOf:
      - $ref: '#/components/schemas/UnauthorizedErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    ValidationErrorExtension:
      required:
      - type
      - error_fields
      properties:
        type:
          type: string
          enum:
          - VALIDATION_ERROR
        error_fields:
          type: array
          items:
            type: object
            properties:
              field_name:
                type: string
                description: "The field name that doesn't pass the validation.\\\nFor nested fields, the field name will be in the format of JSON path with dot notation.\\\nHere are some examples:\\\n  - `landing_page_url`(a root level field)\\\n  - `ad.creative.headline`(a nested object field)\\\n  - `creative.image_creative_info.media_file_ids`(an array in a nested object)\\\n  - `creative.carousel_creative_info.carousel_cards[0].caption`(a field of an object in an array)\\\n"
              reason:
                type: string
    MediaFileResponse:
      type: object
      required:
      - media_file_id
      - ad_account_id
      - media_type
      - file_name
      - images
      - created_at
      - status
      properties:
        media_file_id:
          type: integer
          format: int64
          description: ID of the media file.
        ad_account_id:
          type: integer
          format: int64
          description: ID of the Ad Account that the media file belongs to.
        media_type:
          $ref: '#/components/schemas/MediaType'
        file_name:
          type: string
          description: Name of the media file when the file is uploaded.
        images:
          type: object
          required:
          - full
          - half
          - original
          properties:
            full:
              $ref: '#/components/schemas/ImageResponse'
            half:
              $ref: '#/components/schemas/ImageResponse'
            original:
              $ref: '#/components/schemas/ImageResponse'
          description: 'The definitions of this field are different depending on the Media Type:

            | Media Type | Definition                                           |

            |------------|------------------------------------------------------|

            | IMAGE      | The image files (Full/Half/Original).                |

            | VIDEO      | The auto-generated thumbnails of the uploaded video. |

            '
        videos:
          type: object
          required:
          - high
          - middle
          - low
          - original
          properties:
            high:
              $ref: '#/components/schemas/VideoResponse'
            middle:
              $ref: '#/components/schemas/VideoResponse'
            low:
              $ref: '#/components/schemas/VideoResponse'
            original:
              $ref: '#/components/schemas/VideoResponse'
          description: The video files (High/Middle/Low/Original).
        thumbnail_media_file_id:
          type: integer
          format: int64
          description: The media_file_id of the auto-generated thumbnail. Only Available for `VIDEO` media file.
        created_at:
          type: string
          format: date-time
          description: The date-time at which the media file was created.
        updated_at:
          type: string
          format: date-time
          description: The date-time at which the media file was last updated.
        status:
          $ref: '#/components/schemas/MediaFileStatus'
    ResourceNotFoundErrorExtension:
      type: object
      required:
      - type
      - resource_type
      properties:
        type:
          type: string
          enum:
          - NOT_FOUND
          - DELETED
        resource_type:
          type: string
          enum:
          - CAMPAIGN
          - AD_GROUP
          - AD
          - MEDIA_FILE
          - AD_ACCOUNT
          - PIXEL
          - CUSTOM_AUDIENCE
          - PIXEL_URL_CONFIGURATION
          - AM_CONFIGURATION
          - CATALOG
          - STORE_SET
          - RULE
    UnexpectedErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - UNEXPECTED_ERROR
    BusinessErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - BUSINESS_ERROR
    MediaFileStatus:
      type: string
      description: 'The status of the media file.

        - `ACTIVE`: The media file is visible in the Media Library.

        - `INACTIVE`: The media file has been soft-deleted and is no longer visible in the Media Library.


        Note: Even if a media file is set to `INACTIVE`, it will still be visible in the creatives where it is used.

        '
      enum:
      - ACTIVE
      - INACTIVE
    UnexpectedErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/UnexpectedError'
    MediaType:
      type: string
      description: The type of the media file.
      enum:
      - IMAGE
      - VIDEO
    VideoResponse:
      type: object
      required:
      - width
      - height
      - url
      - length
      - filesize
      - aspect_ratio_type
      - video_quality
      - created_at
      properties:
        width:
          type: integer
          description: The width of the ad video in pixels.
        height:
          type: integer
          description: The height of the ad video in pixels.
        url:
          $ref: '#/components/schemas/VideoSchemas_Url'
        length:
          type: integer
          description: The length of the video in ms.
        filesize:
          type: integer
          description: The file size of video file.
        aspect_ratio_type:
          $ref: '#/components/schemas/AspectRatioType'
        video_quality:
          type: string
          enum:
          - ORIGINAL
          - HIGH
          - MIDDLE
          - LOW
          description: The quality of the video according to the delivery spec.
        created_at:
          type: string
          format: date-time
          description: The date-time at which this record was created
    ResourceNotFoundErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ResourceNotFoundError'
    UnexpectedError:
      type: object
      allOf:
      - $ref: '#/components/schemas/UnexpectedErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    ServiceUnavailableErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ServiceUnavailableError'
    PaginationInfoResponse:
      description: 'An object describing pagination parameters for this response.

        '
      type: object
      required:
      - page
      - page_size
      - total_pages
      - total_objects
      properties:
        page:
          type: integer
          description: The current page, where the first page starts at 1, and the last page corresponds to `total_pages`.
          example: 1
        page_size:
          type: integer
          description: 'The page size as specified in the request (note: the actual number of items in the response may be less if this is the last page of data.)'
          example: 100
        total_pages:
          type: integer
          description: The total number of pages for this query.
          example: 10
        total_objects:
          type: integer
          description: The total number of objects that exist across all pages.
          example: 987
    BusinessErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/BusinessError'
    ServiceUnavailableErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - UNDER_MAINTENANCE
    ServiceUnavailableError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ServiceUnavailableErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    ForbiddenErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ForbiddenError'
    ValidationErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ValidationError'
    ImageResponse:
      type: object
      required:
      - width
      - height
      - url
      - filesize
      - aspect_ratio_type
      - image_scale
      - created_at
      properties:
        width:
          type: integer
          description: The width of the ad image in pixels.
        height:
          type: integer
          description: The height of the ad image in pixels.
        url:
          $ref: '#/components/schemas/Url'
        filesize:
          type: integer
          description: The file size of image file.
        aspect_ratio_type:
          $ref: '#/components/schemas/AspectRatioType'
        image_scale:
          type: string
          enum:
          - FULL
          - HALF
          - ORIGINAL
          description: The scale of the image according to the delivery spec.
        created_at:
          type: string
          format: date-time
          description: The date-time at which this record was created.
    MediaFileRequest:
      type: object
      required:
      - file_name
      - media_type
      - media_file
      properties:
        file_name:
          description: 'The filename of the uploaded file.

            '
          type: string
        media_type:
          $ref: '#/components/schemas/MediaType'
        media_file:
          type: string
          format: binary
          description: "If the same file has been uploaded under the same ad account in the past, the existing media file will be returned.\n\nThere are 2 types of media which can be uploaded:\n- IMAGE\n- VIDEO\n\n## 1. IMAGE\n\nActual Image file to be uploaded to represent the visual image.\\\nMax File Size: 5 MiB\\\nAn image which width exceeds Full Size Max Width will be automatically resized to Full Size Max Width.\\\nA small size image can be uploaded if its width exceeds Min Width.\\\nThe aspect ratio of the image must match one the of pre-defined aspect ratios.\\\nMin Width and Full Size Max Width for each pre-defined Aspect Ratio Type are as follows:\n\n| Pre-defined aspect ratio | Min Width    | Full Size Max Width | Example image size |\n|--------------------------|--------------|---------------------|--------------------|\n| 1:1                      | 300 pixels   | 600 pixels          | 300px x 300px      |\n| 6:5                      | 500 pixels   | 1080 pixels         | 600px x 500px      |\n| 16:9                     | 600 pixels   | 1280 pixels         | 1280px x 720px     |\n| 1.91:1                   | 600 pixels   | 1280 pixels         | 1200px x 628px     |\n\nAllowed Format\n  - JPEG\n  - PNG\n  - GIF (animated GIF is not allowed)\n\n## 2. VIDEO\nActual Video file to be uploaded to represent the visual video.\n\n### Videos that pass the below conditions are allowed to upload:\n- Video Length: 3 (seconds) <= video length <= 60 (seconds)\n- Aspect Ratio: 16:9\n- Minimum Video Resolution: 360p\n- Maximum File size: 100 MiB\n\nAllowed Format\n  - MP4\n"
    Url:
      type: string
      description: The storage full url path of the image file.
    Page:
      type: integer
      minimum: 1
      default: 1
      example: 2
      description: 'The page of data to retrieve. The first page starts at 1, and each page will contain at most `page_size` items (the last page may contain less).


        To get the maximum available page number, refer to the `total_pages` field in the response''s `pagination` object.

        '
    AcceptLanguage:
      type: string
      description: 'The language to use for system generated text within API responses.


        The currently supported languages are English (`en`, `en-*`) and Japanese (`ja`, `ja-JP`)

        '
      example: en-US
    RateLimitedError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ErrorBase'
      - type: object
        required:
        - type
        properties:
          type:
            type: string
            enum:
            - TOO_MANY_REQUESTS
    GatewayTimeoutErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBase'
    UnauthorizedErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/UnauthorizedError'
    BusinessError:
      type: object
      allOf:
      - $ref: '#/components/schemas/BusinessErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    AspectRatioType:
      type: string
      enum:
      - ASPECT_RATIO_1_1
      - ASPECT_RATIO_6_5
      - ASPECT_RATIO_16_9
      - ASPECT_RATIO_191_100
      description: The predefined enums for the aspect ratio of images and videos.
    RateLimitedErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/RateLimitedError'
    VideoSchemas_Url:
      type: string
      description: The full url path of the video file.
    MediaFilePaginatedResponse:
      type: object
      description: A paginated list of media files with pagination metadata.
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/MediaFileResponse'
        pagination:
          $ref: '#/components/schemas/PaginationInfoResponse'
    ResourceNotFoundError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ResourceNotFoundErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    ErrorBase:
      type: object
      required:
      - message
      - retriable
      properties:
        message:
          type: string
        retriable:
          type: boolean
    UnauthorizedErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - UNAUTHORIZED
    ForbiddenError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ForbiddenErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
    ForbiddenErrorExtension:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - TERMS_OF_SERVICE_NOT_ACCEPTED
          - ACCESS_DENIED
        terms_of_service_path:
          type: string
          example: /terms/agreement
          description: The path that the user must open in a browser to accept the terms of service. The hostname matches the API hostname.
    ValidationError:
      type: object
      allOf:
      - $ref: '#/components/schemas/ValidationErrorExtension'
      - $ref: '#/components/schemas/ErrorBase'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT