Authentication and keys

Send the key

GET /v1/meta/ads?q=running+shoes HTTP/1.1
Host: api.publicadsapi.com
Authorization: Bearer $PADS_API_KEY

No header, or one that is not Bearer <key>, is 401 UNAUTHENTICATED. A key that is not ours or has been revoked is 401 INVALID_KEY. Neither uses credits.

Sandbox and live keys

Both kinds take the same requests and answer in the same shapes, so code built against the sandbox works live by changing the key.

What the sandbox returns

• Each platform has a few sample ads with every field filled the way that platform fills it: Meta's EU reach, Google's text read from an image, TikTok's reach range, LinkedIn's payer.
• Pages hold 3 ads, so you can test paging with next_cursor. Meta's active and format, and Google's format, filter the samples; other filters are checked and echoed in query but return the same ads.
• Every id a sandbox search returns works with GET /v1/ads/{id}. Any other id is 404 AD_NOT_FOUND.
• These searches answer as a platform sometimes does: q=empty, q=blocked, q=timeout, q=changed (also as company or a domain's first part). For one ad, the ids meta_blocked, google_blocked, tiktok_blocked, linkedin_blocked and the same with _timeout and _changed. See Test your error handling.

Create, store and revoke keys

• Create and revoke keys on Keys. A revoked key stops working at once.
• Keep a key in an environment variable such as PADS_API_KEY and call the API from your server. A key in a web page or an app can be read by anyone who has it.
• A live key is shown once. Lost one? Create another and revoke the old one.
• Use one key per app or environment, so you can see each one's calls on the dashboard and revoke one without the others.