Getting started
API keys and auth
One credential for everything server-side. The pixel and the agentic postback need no key.
Keys
Mint under API keys in the console. Shown once; only a hash is stored. Keep it in a server secret manager, never in a browser or a repo.
Authorization: Bearer fbadv_…Scopes
| Scope | Lets a key | Used by |
|---|---|---|
ingest | report conversions | Server postback |
read | read reports, campaigns, billing, pixel, team | Reporting API, MCP read tools |
manage | create, edit, pause, resume, invite, test clicks | MCP write tools |
No scope implies another, and none manages keys. One key per system.
Test mode
- A test key starts with
fbadv_test_. It only records test clicks (bfc_test_…), so a leaked staging key can never record a live conversion. - Reporting and MCP refuse test keys (
401). - Test clicks: Events → Verify, or the MCP tool
create_test_click. Valid about 30 minutes, never billed.
Rate limits
| Surface | Limit |
|---|---|
| Reporting API, MCP | 120 requests per minute per key |
| Postback, identity matching | Burst limit per minute; 5,000 email digests per day |
| Client-side tag | Per IP; 20 browser events per click |
A 429 carries Retry-After. Retry 429, 5xx and network errors; fix 4xx.
Conventions
- Base URL
https://freebuff.com. - Money in integer cents (
2000= $20.00). - Days are Pacific calendar days,
YYYY-MM-DD, inclusive. - Timestamps you send are ISO 8601 with a zone.
- Errors are
{ "error": "snake_case_code" }. eventIdis the idempotency key. Same id again = same result.
Errors
| Status | Body | Meaning |
|---|---|---|
| 401 | unauthorized | No key, revoked key, missing scope, or a test key where a live one is needed. |
| 403 | test_mode_key | A test key reported a live click. |
| 404 | not_found | The API is not enabled for this account yet. |
| 429 | rate_limited | Wait Retry-After seconds and resend. |