openapi: 3.2.0
info:
  title: NewsBreak Advertising Ad API
  version: v1
  description: 'The NewsBreak Advertising API (NewsBreak API for Business) lets technology companies, direct advertisers and agencies programmatically manage the NewsBreak Ads Manager at scale: create and manage organizations, ad accounts and ad-account users; build campaigns, ad sets and ads; upload creative assets to the NewsBreak CDN; configure audience targeting and inventory platforms; manage account spending caps; read conversion tracking events; and run multidimensional performance reports.


    This document was generated by API Evangelist from the operations NewsBreak publishes in its Ad Manager API reference (https://advertising-api.newsbreak.com/hc/en-us). NewsBreak does not publish a machine-readable OpenAPI definition; every path, method, parameter, enumeration and response field here is transcribed from the published reference articles, which are linked per operation via externalDocs.'
  termsOfService: https://www.newsbreak.com/terms
  contact:
    name: NewsBreak Ad Support
    email: adsupport@newsbreak.com
    url: https://advertising-api.newsbreak.com/hc/en-us
servers:
- url: https://business.newsbreak.com/business-api/v1
  description: NewsBreak Advertising API production
security:
- AccessToken: []
tags:
- name: Ad
  description: Ads and their creatives, plus creative asset upload.
paths:
  /ad/create:
    post:
      operationId: createAd
      tags:
      - Ad
      summary: Create an ad
      description: Create an ad under an ad set, with its creative. Creative asset URLs must first be uploaded through uploadAdAssets.
      externalDocs:
        description: 'NewsBreak reference: Create an Ad'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869297161741-Create-an-Ad
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad/getList:
    get:
      operationId: getAds
      tags:
      - Ad
      summary: Get ads
      description: Get all ads for an ad account. Optionally filter by search text, status, campaign or ad set.
      externalDocs:
        description: 'NewsBreak reference: Get Ads'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869300764813-Get-Ads
      parameters:
      - name: adAccountId
        in: query
        required: true
        description: ID of ad account.
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: Query to search.
        schema:
          type: string
      - name: onlineStatus
        in: query
        required: false
        description: Ad status filter.
        schema:
          type: array
          items:
            type: string
            enum:
            - WARNING
            - INACTIVE
            - ACTIVE
            - DELETED
            - PENDING
            - REJECTED
      - name: campaignIds
        in: query
        required: false
        description: Get ads in the given campaigns only.
        schema:
          type: array
          items:
            type: string
      - name: adSetIds
        in: query
        required: false
        description: Get ads in the given ad sets only.
        schema:
          type: array
          items:
            type: string
      - name: pageNo
        in: query
        required: true
        description: Page number.
        schema:
          type: integer
      - name: pageSize
        in: query
        required: true
        description: Page size.
        schema:
          type: integer
          enum:
          - 5
          - 10
          - 20
          - 50
          - 100
          - 200
          - 500
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdPageResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad/update/{adId}:
    put:
      operationId: updateAd
      tags:
      - Ad
      summary: Update an ad
      description: Update an ad and/or its creative.
      externalDocs:
        description: 'NewsBreak reference: Update an Ad'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869332787853-Update-an-Ad
      parameters:
      - name: adId
        in: path
        required: true
        description: ID of the ad to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad/updateStatus/{adId}:
    put:
      operationId: updateAdStatus
      tags:
      - Ad
      summary: Update ad status (ON/OFF)
      description: Enable or disable an ad.
      externalDocs:
        description: 'NewsBreak reference: Update Ad Status (ON/OFF)'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869330859533-Update-Ad-Status-ON-OFF
      parameters:
      - name: adId
        in: path
        required: true
        description: ID of the ad to update.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad/delete/{adId}:
    delete:
      operationId: deleteAd
      tags:
      - Ad
      summary: Delete an ad
      description: Delete an ad.
      externalDocs:
        description: 'NewsBreak reference: Delete an Ad'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869268891661-Delete-an-Ad
      parameters:
      - name: adId
        in: path
        required: true
        description: ID of the ad to delete.
        schema:
          type: string
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
  /ad/uploadAssets:
    post:
      operationId: uploadAdAssets
      tags:
      - Ad
      summary: Upload single ad assets
      description: Upload a single creative asset to the NewsBreak CDN. Only asset URLs returned by this operation are accepted by createAd / updateAd. Optionally saves the media to the ad account's Media Library.
      externalDocs:
        description: 'NewsBreak reference: Upload Single Ad Assets'
        url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869305274509-Upload-Single-Ad-Assets
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadAssetRequest'
      responses:
        '200':
          description: 'Successful response. Check `code` in the body: 0 is success, any other value is an error (see Return Codes).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadAssetResponse'
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
        '403':
          description: Permission denied, not logged in, invalid access token, or rate limit exceeded (return codes 403 / 4031 / 4033 / 4034).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Envelope'
components:
  schemas:
    StatusRequest:
      type: object
      description: Toggle the ON/OFF status of a campaign, ad set or ad.
      properties:
        status:
          type: string
          description: Target status.
          enum:
          - 'ON'
          - 'OFF'
      required:
      - status
    UploadAssetRequest:
      type: object
      properties:
        asset:
          type: string
          format: binary
          description: Asset to be uploaded.
        adAccountId:
          type: string
          description: ID of the ad account of the ad.
        saveToMediaLibrary:
          type: boolean
          description: Save the media to the account's Media Library, making it reusable in the ad platform UI.
        mediaName:
          type: string
          description: Media name, 3-256 characters. Required only when saveToMediaLibrary is true.
      required:
      - asset
      - adAccountId
    Ad:
      type: object
      description: An ad and its creative.
      properties:
        id:
          type: string
          description: Ad ID.
        name:
          type: string
          description: Ad name.
        adAccountId:
          type: string
          description: Ad account ID.
        campaignId:
          type: string
          description: Campaign ID.
        adSetId:
          type: string
          description: Ad set ID.
        clickTrackingUrl:
          type: array
          description: Click tracking URL list.
          items:
            type: string
        impressionTrackingUrl:
          type: array
          description: Impression tracking URL list.
          items:
            type: string
        status:
          type: string
          description: Ad status.
          enum:
          - 'ON'
          - 'OFF'
        onlineStatus:
          type: string
          description: Online status of the ad.
          enum:
          - WARNING
          - INACTIVE
          - ACTIVE
          - DELETED
          - PENDING
          - REJECTED
        creative:
          $ref: '#/components/schemas/Creative'
        createTime:
          type: string
          description: Create time of the ad.
        updateTime:
          type: string
          description: Update time of the ad.
    AdPageResponse:
      type: object
      description: Envelope carrying a page of ads.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          properties:
            pageNo:
              type: integer
              description: Number of current page.
            pageSize:
              type: integer
              description: Size of current page.
            total:
              type: integer
              description: Total size for this search.
            hasNext:
              type: boolean
              description: Whether there is a next page.
            rows:
              type: array
              items:
                $ref: '#/components/schemas/Ad'
    UpdateAdRequest:
      type: object
      description: Ad fields to update. All fields are optional.
      properties:
        name:
          type: string
          description: Descriptive name of the ad.
        clickTrackingUrl:
          type: array
          description: Click tracking URL list.
          items:
            type: string
        impressionTrackingUrl:
          type: array
          description: Impression tracking URL list.
          items:
            type: string
        status:
          type: string
          description: Status of the ad.
          enum:
          - 'ON'
          - 'OFF'
        creative:
          $ref: '#/components/schemas/Creative'
    UploadAssetResponse:
      type: object
      description: Envelope carrying an uploaded asset.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          properties:
            assetUrl:
              type: string
              description: URL of the uploaded image, video or GIF on the NewsBreak CDN.
            mediaId:
              type: string
              description: Media ID.
    AdResponse:
      type: object
      description: Envelope carrying a single ad.
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          $ref: '#/components/schemas/Ad'
    CreateAdRequest:
      type: object
      properties:
        adSetId:
          type: string
          description: ID of ad set.
        name:
          type: string
          description: Descriptive name of the ad.
        clickTrackingUrl:
          type: array
          description: Click tracking URL list.
          items:
            type: string
        impressionTrackingUrl:
          type: array
          description: Impression tracking URL list.
          items:
            type: string
        status:
          type: string
          description: Status of the ad. Default is ON.
          enum:
          - 'ON'
          - 'OFF'
        creative:
          $ref: '#/components/schemas/Creative'
      required:
      - adSetId
      - name
      - creative
    Envelope:
      type: object
      description: The standard NewsBreak response envelope. Every operation returns HTTP 200 with a `code` field; code 0 means success and any other value is an error (see Return Codes).
      properties:
        code:
          type: integer
          description: Status code. 0 is successful; see Return Codes.
        errMsg:
          type: string
          description: Error message when code != 0.
        data:
          type: object
          description: Response object.
    Creative:
      type: object
      description: The creative rendered for an ad.
      properties:
        type:
          type: string
          description: Type of this creative.
          enum:
          - IMAGE
          - VIDEO
          - GIF
          - PLAYABLE_VIDEO
        headline:
          type: string
          description: Title.
        assetUrl:
          type: string
          description: URL of the IMAGE, VIDEO or GIF. Must be an asset uploaded to the NewsBreak CDN via uploadAdAssets, and include your account ID.
        coverUrl:
          type: string
          description: Cover image of the video. Only applicable for VIDEO and PLAYABLE_VIDEO. Must be a NewsBreak CDN asset.
        playableAssetUrl:
          type: string
          description: URL of the interactive playable HTML file. Required when type is PLAYABLE_VIDEO. Must be an .html asset uploaded to the NewsBreak CDN.
        description:
          type: string
          description: Description of this ad.
        callToAction:
          type: string
          description: Text on the button.
        brandName:
          type: string
          description: Brand name of this ad.
        logoUrl:
          type: string
          description: URL of the logo.
        clickThroughUrl:
          type: string
          description: Landing page URL.
      required:
      - type
      - headline
      - assetUrl
      - description
      - callToAction
      - brandName
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: Access-Token
      description: Authorized access token. Generate it in the NewsBreak Ad Manager under Resources -> API Access Tokens ("Generate Token"). The token carries the permissions granted by the advertiser. Keep it secret.
externalDocs:
  description: NewsBreak Ad Manager API reference
  url: https://advertising-api.newsbreak.com/hc/en-us