openapi: 3.1.0
info:
  title: Snapchat Ads Ad Accounts Media API
  description: The Snapchat Ads API allows developers to programmatically create, manage, and optimize advertising campaigns on the Snapchat platform. It provides endpoints for managing organizations, ad accounts, campaigns, ad squads, ads, creatives, media, funding sources, audience segments, and measurement reporting. The API supports the full advertising lifecycle from campaign setup through reporting and optimization.
  version: '1.0'
  contact:
    name: Snap for Developers
    url: https://developers.snap.com
  termsOfService: https://snap.com/en-US/terms
servers:
- url: https://adsapi.snapchat.com/v1
  description: Production Server
security:
- bearerAuth: []
tags:
- name: Media
  description: Media endpoints handle uploading and managing media assets such as images and videos used in creatives.
paths:
  /adaccounts/{ad_account_id}/media:
    get:
      operationId: listMedia
      summary: List All Media for an Ad Account
      description: Retrieves all media objects associated with the specified ad account.
      tags:
      - Media
      parameters:
      - $ref: '#/components/parameters/adAccountId'
      responses:
        '200':
          description: Successful retrieval of media
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_status:
                    type: string
                  request_id:
                    type: string
                  media:
                    type: array
                    items:
                      type: object
                      properties:
                        media:
                          $ref: '#/components/schemas/Media'
        '401':
          description: Unauthorized
        '404':
          description: Ad account not found
    post:
      operationId: createMedia
      summary: Create a Media Object
      description: Creates a new media object under the specified ad account. The media object must be created before uploading the actual media file.
      tags:
      - Media
      parameters:
      - $ref: '#/components/parameters/adAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                media:
                  type: array
                  items:
                    $ref: '#/components/schemas/Media'
      responses:
        '200':
          description: Media object created successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /media/{media_id}/upload:
    post:
      operationId: uploadMedia
      summary: Upload Media Content
      description: Uploads the actual media file content to an existing media object. Supports images, videos, and playable media. Maximum chunk size is 32MB per request.
      tags:
      - Media
      parameters:
      - $ref: '#/components/parameters/mediaId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The media file to upload (image, video, or ZIP for playable)
      responses:
        '200':
          description: Media uploaded successfully
        '400':
          description: Bad request - invalid file or exceeds size limit
        '401':
          description: Unauthorized
        '404':
          description: Media object not found
components:
  parameters:
    mediaId:
      name: media_id
      in: path
      required: true
      description: The unique identifier of the media object
      schema:
        type: string
    adAccountId:
      name: ad_account_id
      in: path
      required: true
      description: The unique identifier of the ad account
      schema:
        type: string
  schemas:
    Media:
      type: object
      description: A Media object represents an uploaded media asset such as an image, video, or playable content used in creatives.
      properties:
        id:
          type: string
          description: The unique identifier of the media object
        updated_at:
          type: string
          format: date-time
          description: Timestamp of last update
        created_at:
          type: string
          format: date-time
          description: Timestamp of creation
        name:
          type: string
          description: The name of the media object
        ad_account_id:
          type: string
          description: The ID of the parent ad account
        type:
          type: string
          description: The type of media
          enum:
          - IMAGE
          - VIDEO
          - PLAYABLE
        media_status:
          type: string
          description: The processing status of the media
          enum:
          - PENDING_UPLOAD
          - READY
          - ERROR
  securitySchemes:
    bearerAuth:
      type: oauth2
      description: OAuth 2.0 authorization. Access tokens are obtained via the authorization code flow and expire after 3600 seconds. Refresh tokens can be used to obtain new access tokens.
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.snapchat.com/accounts/oauth2/auth
          tokenUrl: https://accounts.snapchat.com/login/oauth2/access_token
          scopes:
            snapchat-marketing-api: Access to the Snapchat Marketing API
externalDocs:
  description: Snapchat Ads API Documentation
  url: https://developers.snap.com/api/marketing-api/Ads-API/introduction