generated: '2026-08-01' method: searched source: https://advertising-api.newsbreak.com/hc/en-us derived_from: - openapi/news-break-advertising-openapi.yml - openapi/news-break-monetization-reporting-openapi.yml summary: >- The NewsBreak Advertising API is a JSON-over-HTTP RPC-style API rather than a resource-oriented REST API: verbs live in the path (/campaign/create, /campaign/getList, /campaign/updateStatus/{id}) rather than in the HTTP method alone, and every response - success or failure - comes back as HTTP 200 wrapping a `code`/`errMsg`/`data` envelope. Pagination is offset-based and consistent across the three list operations. There is no idempotency contract, no request-id tracing header, no conditional-request support and no rate-limit response headers. authentication: style: api-key header: Access-Token detail: authentication/news-break-authentication.yml idempotency: supported: false header: null detail: >- NewsBreak documents no idempotency key, no request deduplication window and no safe-retry contract. createCampaign, createAdSet, createAd, createAdAccount and uploadAdAssets are all unconditionally unsafe to retry - a retried create produces a duplicate object. Because throttling (code 4034) is delivered inside an HTTP 200 body, a naive client that retries on a non-zero code can silently double-create. Callers must implement their own client-side deduplication keyed on their own identifiers, and must read `code` before deciding to retry. agent_guidance: >- Treat every POST as at-most-once. Before retrying a create, call the matching getList operation and search by `name` to confirm whether the first attempt landed. pagination: style: offset applies_to: - openapi/news-break-advertising-openapi.yml#getCampaigns - openapi/news-break-advertising-openapi.yml#getAdSets - openapi/news-break-advertising-openapi.yml#getAds request_parameters: - name: pageNo required: true type: integer description: Page number. - name: pageSize required: true type: integer description: Page size. allowed_values: [5, 10, 20, 50, 100, 200, 500] response_fields: - name: data.pageNo description: Number of current page. - name: data.pageSize description: Size of current page. - name: data.total description: Total number of matching records. - name: data.hasNext description: Whether a next page exists. - name: data.rows description: The array of records for this page. notes: - Both pageNo and pageSize are REQUIRED - there is no implicit default page. - pageSize is a closed enumeration, not a free integer. - No cursor, no link headers, no stable-sort guarantee is documented. - >- getAdAccounts, getEvents, getAdminOrgs and the report operations are unpaginated and return a whole `list` array. filtering: style: repeated query parameters examples: - 'onlineStatus=WARNING&onlineStatus=ACTIVE' - 'campaignIds=1&campaignIds=2' - 'orgIds=123&orgIds=234' free_text: 'A `search` query parameter on getCampaigns, getAdSets and getAds.' notes: - >- getEvents uses an unusual empty-value convention - `os=` (present but empty) means "web events only", while omitting the parameter entirely means "all operating systems". error_envelope: transport: HTTP 200 for both success and most failures media_type: application/json shape: code: integer, 0 on success errMsg: string, present when code != 0 data: object, present when code == 0 detail: errors/news-break-problem-types.yml agent_guidance: >- Never branch on the HTTP status line alone. Parse the body and check `code == 0` before treating a 200 as success. rate_limit_signaling: headers: [] body_code: 4034 detail: rate-limits/news-break-rate-limits.yml agent_guidance: >- There are no RateLimit or Retry-After headers, so a client cannot see how much quota remains. Budget requests against the published QPS/QPM/QPD tier and back off for 5 minutes on a QPM breach, until 00:00 UTC on a QPD breach. versioning: advertising_api: scheme: uri-path current: v1 base_path: /business-api/v1 monetization_api: scheme: document-version current: v0.1 introduced: '2025-01-03' docs: https://doc.msp.newsbreak.com/business-api-doc/docs/overview/versioning detail: lifecycle/news-break-lifecycle.yml money_and_time: currency: USD monetary_unit: >- All Advertising API monetary values (campaign budget, ad set budget, bidRate, account spending cap, report cost/CPM/CPC/CPA) are integers in CENTS. Spending caps are bounded to 0-10,000,000,000 cents ($0-$100M). decimal_pairs: >- Report rows publish both an integer and a *Decimal double for cost, conversion value, CPM, CPC and CPA. A value of -1 (or -1.0) means "not applicable", not zero. timestamps: >- Ad set startTime/endTime are integer unix timestamps. Object createTime/updateTime are unix timestamps returned as STRINGS. Report dates are "YYYY-MM-DD" strings. timezone: >- Report requests take an IANA timezone string (UTC, America/Los_Angeles, Asia/Shanghai). The documented default is PDT, not UTC. The MSP Reporting API instead takes a closed enum (PT/ET/UTC/"Beijing Time") defaulting to UTC. identifiers: format: numeric strings note: >- All object IDs (orgId, adAccountId, campaignId, adSetId, adId, trackingId, mediaId) are numeric values carried as JSON strings. There are no typed ID prefixes. media_upload: operation: openapi/news-break-advertising-openapi.yml#uploadAdAssets content_type: multipart/form-data constraint: >- Creative assetUrl, coverUrl and playableAssetUrl values must be URLs returned by uploadAdAssets on the NewsBreak CDN (static.particlenews.com) and must include the account ID. Externally hosted creative URLs are rejected. not_supported: - request-id / correlation-id header - idempotency keys - conditional requests (ETag / If-Match / If-None-Match) - partial responses / sparse fieldsets / field expansion - webhooks or server-sent events - bulk / batch endpoints (except the array-shaped balance and asset operations) - HATEOAS links see_also: - errors/news-break-problem-types.yml - rate-limits/news-break-rate-limits.yml - authentication/news-break-authentication.yml - lifecycle/news-break-lifecycle.yml