# Agents

> An AI agent can get its own sandbox key, build and test against it, then get a live key with free credits, all without a person signing up. A claim link hands the account to its person when they are ready.

Base URL: `https://api.publicadsapi.com` · Auth: `authorization: Bearer <key>` · Web version: https://publicadsapi.com/docs/agents

> **If you are an AI agent:** this page is written for you. Follow the steps in order. Store keys in the `PADS_API_KEY` environment variable, never in code you commit, and give the `claim_url` to your user.

## 1. Get a sandbox key

POST /v1/agent/signup (no auth):

```bash
curl -X POST https://api.publicadsapi.com/v1/agent/signup \
  -H "content-type: application/json" \
  -d '{"name": "Claude Code for Example Ltd", "use_case": "Weekly report of competitor ads on Meta and Google"}'
```

201 Created:

```json
{
  "api_key": "pads_test_EXAMPLEKEY",
  "mode": "test",
  "name": "Claude Code for Example Ltd",
  "use_case": "Weekly report of competitor ads on Meta and Google",
  "claim_url": "https://publicadsapi.com/claim#EXAMPLE",
  "next_steps": "This is a sandbox key: it returns sample ads, never calls a platform, costs nothing and does not expire. …"
}
```

- `name` (up to 60 characters): who you are, for example the tool and who you work for. `use_case` (up to 300): what you are building. Both are required.
- The sandbox key never expires and never costs anything. Reuse it: one network may make 20 keys a day.
- `next_steps` says what to do next, in words, in case you lose this page.

## 2. Build against the sandbox

Send the key as `Authorization: Bearer <key>` to any platform's search. Every request and answer is the same as live, with sample ads. Follow `next_cursor` to page, and handle the test searches `q=empty`, `q=blocked`, `q=timeout` and `q=changed`: see the [Quickstart](https://publicadsapi.com/docs/quickstart.md). The parameters each platform takes are in [/openapi.json](https://publicadsapi.com/openapi.json).

## 3. Get a live key

POST /v1/agent/live-key:

```bash
curl -X POST https://api.publicadsapi.com/v1/agent/live-key \
  -H "authorization: Bearer $PADS_API_KEY"
```

- Send the sandbox key from step 1. The answer (`201`) has `api_key` (a `pads_live_` key), `credits_remaining` and the `claim_url`.
- The live key is shown once: store it with the project's production secrets.
- It includes 50 free credits a month while the account is unclaimed. A page of ads uses 1 (LinkedIn 2); empty pages and errors are free. Every response says what is left in `credits_remaining`.
- A live call takes 2 to 15 seconds: set your HTTP timeout to at least 60. On `503 BUSY` or `UPSTREAM_BLOCKED`, wait `Retry-After` seconds and send it again.
- One live key per sandbox key. Asking again is `409` with the `claim_url`; once claimed it is `403`, and your user makes more keys on the dashboard.

## 4. Hand it to your user

Give your user the `claim_url` and say what it does: when they open it and sign in, both keys and every call you have made move into their account, where they can see usage and choose a plan. Your keys keep working. Until they claim, nothing expires.

## When the free credits run out

Live calls answer `402 QUOTA_EXCEEDED` with the `claim_url` in the error. Give it to your user: once they claim and upgrade, the same key works again. The sandbox key keeps working throughout.

## A prompt for your coding agent

For a person handing the job to Claude Code, Cursor or another coding agent: paste this, and it does the steps above.

```text
Add ad library search to this project using the Public Ads API. Follow the quickstart: https://publicadsapi.com/docs/quickstart.md. Read my API key from the PADS_API_KEY environment variable. If it isn't set, get a sandbox key yourself with POST https://api.publicadsapi.com/v1/agent/signup (send your name and what we are building as name and use_case), store the api_key it returns in PADS_API_KEY, and give me the claim_url so I can keep the key. Test it against the sandbox first: try GET https://api.publicadsapi.com/v1/meta/ads?q=running+shoes&country=GB, follow next_cursor for the next page, and handle the scenario queries q=empty, q=blocked and q=timeout.
```

## Where agents read

- [/llms.txt](https://publicadsapi.com/llms.txt): The index: every page, with one line each.
- [/llms-full.txt](https://publicadsapi.com/llms-full.txt): The whole integration in one file, under 10 KB.
- [/openapi.json](https://publicadsapi.com/openapi.json): OpenAPI 3.1, one schema per platform. Also at /.well-known/openapi.json.
- [Any page as Markdown](https://publicadsapi.com/docs/quickstart.md.md): Add .md to a docs address, e.g. /docs/quickstart.md.

See [llms.txt](https://publicadsapi.com/llms.txt).

See also: [Rate limits](https://publicadsapi.com/docs/rate-limits.md) · [Changelog](https://publicadsapi.com/docs/changelog.md)