openapi: 3.1.0
info:
title: NewsBreak Advertising 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
externalDocs:
description: NewsBreak Ad Manager API reference
url: https://advertising-api.newsbreak.com/hc/en-us
servers:
- url: https://business.newsbreak.com/business-api/v1
description: NewsBreak Advertising API production
tags:
- name: Organization
description: Organizations the calling user administers.
- name: Ad Account
description: Ad accounts under an organization and the users who can access them.
- name: Campaign
description: 'Campaigns: the objective-level container for ad sets.'
- name: Ad Set
description: 'Ad sets: budget, bidding, schedule, platforms and audience targeting.'
- name: Ad
description: Ads and their creatives, plus creative asset upload.
- name: Report
description: Synchronous and saved custom performance reports.
- name: Account Billing
description: Account-level spending caps and remaining budget.
- name: Event Management
description: Conversion tracking events (pixel and postback).
security:
- AccessToken: []
paths:
/org/admin-orgs:
get:
operationId: getAdminOrgs
tags:
- Organization
summary: Get org admin's organizations
description: Get all organizations where the calling user holds the ORG_ADMIN role. The caller is identified by the access token — no request parameters are required.
externalDocs:
description: 'NewsBreak reference: Get Org Admin''s Organizations'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/45246356925965-Get-Org-Admin-s-Organizations
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/OrganizationListResponse'
'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-account/create:
post:
operationId: createAdAccount
tags:
- Ad Account
summary: Create an ad account
description: Create an ad account under an organization.
externalDocs:
description: 'NewsBreak reference: Create An Ad Account'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/45689340192781-Create-An-Ad-Account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAdAccountRequest'
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/AdAccountResponse'
'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-account/getGroupsByOrgIds:
get:
operationId: getAdAccounts
tags:
- Ad Account
summary: Get ad accounts
description: Get all ad accounts' IDs and names for each organization, grouped by organization ID and name. Users only receive ad accounts they have access to.
externalDocs:
description: 'NewsBreak reference: Get Ad Accounts'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869173867789-Get-Ad-Accounts
parameters:
- name: orgIds
in: query
required: true
description: IDs of organizations.
schema:
type: array
items:
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/AdAccountGroupsResponse'
'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-account/addUser:
post:
operationId: addAdAccountUser
tags:
- Ad Account
summary: Add a user to an ad account
description: Grant a user access to an ad account under an organization. If the user does not yet exist, an account is created and an invitation email is sent. The user is also granted an organization-level
membership role if they don't already have one.
externalDocs:
description: 'NewsBreak reference: Add a User to an Ad Account'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/46938559949069-Add-a-User-to-an-Ad-Account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddAdAccountUserRequest'
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/Envelope'
'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-account/deleteUser:
post:
operationId: deleteAdAccountUser
tags:
- Ad Account
summary: Remove a user from an ad account
description: Revoke a user's access to an ad account under an organization. This removes only the user's ad-account-level role; any organization-level role is left unchanged.
externalDocs:
description: 'NewsBreak reference: Remove a User from an Ad Account'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/46938642910477-Remove-a-User-from-an-Ad-Account
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAdAccountUserRequest'
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/Envelope'
'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'
/campaign/create:
post:
operationId: createCampaign
tags:
- Campaign
summary: Create a campaign
description: Create a campaign under an ad account.
externalDocs:
description: 'NewsBreak reference: Create a Campaign'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869159614477-Create-a-Campaign
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCampaignRequest'
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/CampaignResponse'
'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'
/campaign/getList:
get:
operationId: getCampaigns
tags:
- Campaign
summary: Get campaigns
description: Get all campaigns for an ad account. Optionally filter to return only certain campaigns.
externalDocs:
description: 'NewsBreak reference: Get Campaigns'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869190998925-Get-Campaigns
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: Campaign status filter.
schema:
type: array
items:
type: string
enum:
- WARNING
- INACTIVE
- ACTIVE
- DELETED
- 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/CampaignPageResponse'
'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'
/campaign/update/{campaignId}:
put:
operationId: updateCampaign
tags:
- Campaign
summary: Update a campaign
description: Update a campaign.
externalDocs:
description: 'NewsBreak reference: Update a Campaign'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869170482061-Update-a-Campaign
parameters:
- name: campaignId
in: path
required: true
description: ID of the campaign to update.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCampaignRequest'
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/CampaignResponse'
'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'
/campaign/updateStatus/{campaignId}:
put:
operationId: updateCampaignStatus
tags:
- Campaign
summary: Update campaign status (ON/OFF)
description: Enable or disable a campaign.
externalDocs:
description: 'NewsBreak reference: Update Campaign Status (ON/OFF)'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869222017549-Update-Campaign-Status-ON-OFF
parameters:
- name: campaignId
in: path
required: true
description: ID of the campaign 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/CampaignResponse'
'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'
/campaign/delete/{campaignId}:
delete:
operationId: deleteCampaign
tags:
- Campaign
summary: Delete a campaign
description: Delete a campaign. The returned campaign has onlineStatus DELETED.
externalDocs:
description: 'NewsBreak reference: Delete a Campaign'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869167992077-Delete-a-Campaign
parameters:
- name: campaignId
in: path
required: true
description: ID of the campaign 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/CampaignResponse'
'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-set/create:
post:
operationId: createAdSet
tags:
- Ad Set
summary: Create an ad set
description: Create an ad set under a campaign, including budget, bidding, schedule and targeting.
externalDocs:
description: 'NewsBreak reference: Create an Ad Set'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869216635789-Create-an-Ad-Set
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAdSetRequest'
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/AdSetResponse'
'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-set/getList:
get:
operationId: getAdSets
tags:
- Ad Set
summary: Get ad sets
description: Get all ad sets for an ad account. Optionally filter by search text, status or campaign.
externalDocs:
description: 'NewsBreak reference: Get Ad Sets'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869226813965-Get-Ad-Sets
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 set status filter.
schema:
type: array
items:
type: string
enum:
- WARNING
- INACTIVE
- ACTIVE
- DELETED
- READY
- COMPLETED
- name: campaignIds
in: query
required: false
description: Get ad sets in the given campaigns 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/AdSetPageResponse'
'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-set/update/{adSetId}:
put:
operationId: updateAdSet
tags:
- Ad Set
summary: Update an ad set
description: Update an ad set. All body fields are optional; only supplied fields are changed.
externalDocs:
description: 'NewsBreak reference: Update An Ad Set'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869314889229-Update-An-Ad-Set
parameters:
- name: adSetId
in: path
required: true
description: ID of the ad set to update.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAdSetRequest'
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/AdSetResponse'
'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-set/updateStatus/{adSetId}:
put:
operationId: updateAdSetStatus
tags:
- Ad Set
summary: Update ad set status (ON/OFF)
description: Enable or disable an ad set.
externalDocs:
description: 'NewsBreak reference: Update Ad Set Status (ON/OFF)'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869247409677-Update-Ad-Set-Status-ON-OFF
parameters:
- name: adSetId
in: path
required: true
description: ID of the ad set 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/AdSetResponse'
'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-set/delete/{adSetId}:
delete:
operationId: deleteAdSet
tags:
- Ad Set
summary: Delete an ad set
description: Delete an ad set.
externalDocs:
description: 'NewsBreak reference: Delete an Ad Set'
url: https://advertising-api.newsbreak.com/hc/en-us/articles/37869211527949-Delete-an-Ad-Set
parameters:
- name: adSetId
in: path
required: true
description: ID of the ad set 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/AdSetResponse'
'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/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:
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/news-break/refs/heads/main/openapi/news-break-advertising-openapi.yml