openapi: 3.1.0
info:
  title: Snapchat Ads Ad Accounts Ad Squads 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: Ad Squads
  description: Ad Squads organize ads within a campaign, defining targeting, budget, schedule, and bid strategy.
paths:
  /campaigns/{campaign_id}/adsquads:
    get:
      operationId: listAdSquadsByCampaign
      summary: List All Ad Squads for a Campaign
      description: Retrieves all ad squads associated with the specified campaign.
      tags:
      - Ad Squads
      parameters:
      - $ref: '#/components/parameters/campaignId'
      responses:
        '200':
          description: Successful retrieval of ad squads
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_status:
                    type: string
                  request_id:
                    type: string
                  adsquads:
                    type: array
                    items:
                      type: object
                      properties:
                        adsquad:
                          $ref: '#/components/schemas/AdSquad'
        '401':
          description: Unauthorized
        '404':
          description: Campaign not found
  /adaccounts/{ad_account_id}/adsquads:
    get:
      operationId: listAdSquadsByAdAccount
      summary: List All Ad Squads for an Ad Account
      description: Retrieves all ad squads associated with the specified ad account.
      tags:
      - Ad Squads
      parameters:
      - $ref: '#/components/parameters/adAccountId'
      responses:
        '200':
          description: Successful retrieval of ad squads
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_status:
                    type: string
                  request_id:
                    type: string
                  adsquads:
                    type: array
                    items:
                      type: object
                      properties:
                        adsquad:
                          $ref: '#/components/schemas/AdSquad'
        '401':
          description: Unauthorized
        '404':
          description: Ad account not found
    post:
      operationId: createAdSquad
      summary: Create an Ad Squad
      description: Creates a new ad squad under the specified ad account.
      tags:
      - Ad Squads
      parameters:
      - $ref: '#/components/parameters/adAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                adsquads:
                  type: array
                  items:
                    $ref: '#/components/schemas/AdSquad'
      responses:
        '200':
          description: Ad squad created successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /adsquads/{ad_squad_id}:
    get:
      operationId: getAdSquad
      summary: Get a Specific Ad Squad
      description: Retrieves details for a specific ad squad by its ID.
      tags:
      - Ad Squads
      parameters:
      - $ref: '#/components/parameters/adSquadId'
      responses:
        '200':
          description: Successful retrieval of ad squad
          content:
            application/json:
              schema:
                type: object
                properties:
                  request_status:
                    type: string
                  request_id:
                    type: string
                  adsquads:
                    type: array
                    items:
                      type: object
                      properties:
                        adsquad:
                          $ref: '#/components/schemas/AdSquad'
        '401':
          description: Unauthorized
        '404':
          description: Ad squad not found
    put:
      operationId: updateAdSquad
      summary: Update an Ad Squad
      description: Updates an existing ad squad.
      tags:
      - Ad Squads
      parameters:
      - $ref: '#/components/parameters/adSquadId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                adsquads:
                  type: array
                  items:
                    $ref: '#/components/schemas/AdSquad'
      responses:
        '200':
          description: Ad squad updated successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Ad squad not found
    delete:
      operationId: deleteAdSquad
      summary: Delete an Ad Squad
      description: Deletes a specific ad squad by its ID.
      tags:
      - Ad Squads
      parameters:
      - $ref: '#/components/parameters/adSquadId'
      responses:
        '200':
          description: Ad squad deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Ad squad not found
components:
  schemas:
    AdSquad:
      type: object
      description: An Ad Squad organizes ads within a campaign, defining targeting criteria, budget allocation, schedule, and bid strategy.
      properties:
        id:
          type: string
          description: The unique identifier of the ad squad
        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 ad squad
        campaign_id:
          type: string
          description: The ID of the parent campaign
        status:
          type: string
          description: The status of the ad squad
          enum:
          - ACTIVE
          - PAUSED
        type:
          type: string
          description: The delivery type of the ad squad
          enum:
          - SNAP_ADS
          - STORY_ADS
        placement:
          type: string
          description: Where ads will be placed
        bid_micro:
          type: integer
          format: int64
          description: The bid amount in micro-currency units
        daily_budget_micro:
          type: integer
          format: int64
          description: Daily budget in micro-currency units
        lifetime_budget_micro:
          type: integer
          format: int64
          description: Lifetime budget in micro-currency units
        start_time:
          type: string
          format: date-time
          description: The start time of the ad squad
        end_time:
          type: string
          format: date-time
          description: The end time of the ad squad
        targeting:
          type: object
          description: Targeting criteria for the ad squad
  parameters:
    adSquadId:
      name: ad_squad_id
      in: path
      required: true
      description: The unique identifier of the ad squad
      schema:
        type: string
    adAccountId:
      name: ad_account_id
      in: path
      required: true
      description: The unique identifier of the ad account
      schema:
        type: string
    campaignId:
      name: campaign_id
      in: path
      required: true
      description: The unique identifier of the campaign
      schema:
        type: string
  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