Help center

OpenAdLibrary API and MCP documentation

Query the public ad catalogue programmatically with the same leak-safe data available in the product.

Create and protect an API key

Create a key from Settings. A key is shown once when it is created, so store it securely and revoke it if it is exposed.

Authenticate requests

Send the key in the x-api-key header or as Authorization: Bearer <key>. The same key can authenticate the REST API and the hosted MCP endpoint.

REST API

The public API exposes leak-safe ad-library fields and supports filtering and pagination. It also publishes the redirect chain behind an ad — the tracker URL the click starts on, every hop it passes through, and the advertiser URL it ends on — through /api/v1/ads/{id}/chain, /api/v1/chains/{chainHash} and /api/v1/chains/match. Chain URLs are credential-scrubbed, while attribution parameters such as subid, click_id and utm_* stay intact. The API does not expose private account data or internal identifiers. The interactive reference loads on this page when JavaScript is available.

Quotas and responses

Free accounts receive a small daily allowance; subscribed accounts receive the full plan quota. Check the live quota shown beside your keys in Settings. A depleted plan allowance can return 402 Payment Required, while burst or subscribed-plan rate limits return 429 Too Many Requests.

Hosted MCP endpoint

Connect an MCP-compatible assistant to https://mcp.openadlibrary.com/mcp and provide the key in the Authorization header. Machine-readable documentation is also available in llms.txt and llms-full.txt.