Chapter 13 — The Advertiser API: Foundations

The Advertiser API is the programmatic interface to Ads Manager. It supports CRUD-style management of campaigns, ad groups, ads, files, and reporting via JSON.

Base URL

https://api.ads.openai.com/v1

This is not the Conversions API host (bzr.openai.com). They are different services on different domains.

Authentication

API keys are issued in the Settings tab of Ads Manager. Each key is scoped to a single ad account. To manage multiple ad accounts via the API, contact OpenAI directly through openai.com/advertisers/.

Pass the key as a bearer token on every request:

Authorization: Bearer $OPENAI_ADS_API_KEY

Request format

Most endpoints accept application/json. The upload endpoint (Chapter 18) additionally accepts multipart/form-data for binary file uploads.

Rate limits

The API enforces limits per ad account and per IP address. Requests must stay within both.

Scope	Limit
Per endpoint	600 requests / minute
Overall	1,200 requests / minute

If you hit a 429, slow down across all endpoints, not just the one that 429’d. The overall limit (1,200/min) caps the entire integration.

Endpoint families

Resource	Purpose	Chapter
Ad Account	Read account metadata	14
Campaigns	Create, list, retrieve, update, change state	15
Ad Groups	Create, list, retrieve, update, change state	16
Ads	Create, list, retrieve, update, change state	17
Files	Upload creative assets	18
Insights	Query performance data at any scope	19

All resources live inside a single Ad Account.

Object lifecycle

For an ad to deliver, three things must be true:

1. The campaign is active (not paused or archived).
2. The ad group is active.
3. The ad is active and has review_status: approved.

If any link in the chain is paused or archived, no delivery.

The status state machine

Ads, ad groups, and campaigns share the same state machine.

Status	Meaning
active	Eligible to deliver.
paused	Stops delivery. Reversible.
archived	Final state. Irreversible. Use only when permanently retired.

Each resource exposes dedicated state-transition endpoints:

• POST /{resource}/{id}/activate
• POST /{resource}/{id}/pause
• POST /{resource}/{id}/archive

You can also change status via the resource’s POST /{resource}/{id} update endpoint, but the dedicated state endpoints are clearer in code review and audit logs.

review_status (ads only)

Ads have a second, independent status that reflects OpenAI’s review.

Review status	Meaning
in_review	Ad is being reviewed. Reviews typically take a few minutes.
approved	Ad can deliver (assuming it and its parents are active).
rejected	Ad violates an OpenAI ad policy. Edit and the ad is re-reviewed.

review_status is read-only. You cannot set it; OpenAI sets it. Updating an ad’s creative re-triggers review automatically.

Use POST for updates, not PATCH or PUT

Update endpoints across all resources use POST (not PATCH or PUT). All fields are optional on update. Composite objects (budget, bidding_config, creative) must be sent as full objects when included — partial updates of a sub-object are not supported. To clear a nullable field, send null.

OpenAPI spec

The full machine-readable spec is published at https://developers.openai.com/ads/openapi.json. Use it to generate client libraries in your stack of choice.