Authentication Quick start Endpoints Examples Rate limits Errors

Authentication

Every request is authenticated with an API key sent as a bearer token. Create keys from your dashboard → API tab (Agency plan). Keep them secret — a key carries full access to your account. The base URL for all requests is:

https://burnpedia.app/api/v1

Quick start

List the boards on your active Pinterest account — your first successful call:

curl https://burnpedia.app/api/v1/boards \
  -H "Authorization: Bearer bp_live_YOUR_API_KEY"

Endpoints

Everything you need to fully integrate Burnpedia — accounts, boards, the whole pin lifecycle, and analytics.

GET/v1/me

Returns the authenticated account: plan, connected Pinterest accounts, and your current rate-limit status.

GET/v1/accounts

Every Pinterest account connected to your Burnpedia workspace, with the id you pass as `account` to scope other calls.

GET/v1/boards

Boards on a connected Pinterest account. Pass `?account=<id>` to choose which one; defaults to your active account.

POST/v1/boards

Creates a public board on the selected Pinterest account.

GET/v1/pins

Your scheduled, publishing, published, and failed pins. Filter with `status` and paginate with `limit` + `offset`.

POST/v1/pins

Schedules a pin (or publishes immediately with `publish_now: true`). Provide `board_id` or a `board_name` (auto-created). Counts against your plan’s daily pin limit and the write rate limit.

GET/v1/pins/{id}

Retrieve a single pin you own by its Burnpedia id.

PATCH/v1/pins/{id}

Edit the title, description, link, board, or scheduled time of a pin that has not published yet.

DELETE/v1/pins/{id}

Deletes a pin from your Burnpedia queue.

POST/v1/pins/{id}/publish

Immediately publishes a scheduled pin to Pinterest.

GET/v1/analytics

Impressions, saves, pin clicks, outbound clicks, and derived rates for the connected account. Pinterest returns at most the last 90 days.

GET/v1/analytics/top-pins

Your best-performing pins over a window, ranked by engagement.

Schedule a Pin

Create a scheduled Pin (or publish immediately with publish_now: true). Pick your language:

curl -X POST https://burnpedia.app/api/v1/pins \
  -H "Authorization: Bearer bp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/image.jpg",
    "title": "How to grow on Pinterest",
    "description": "Fresh pins, scheduled automatically.",
    "link": "https://yoursite.com/post",
    "board_name": "Pinterest Tips",
    "scheduled_at": "2026-08-01T15:00:00Z"
  }'

Rate limits

Calls are capped per key so your integration always stays within Pinterest’s own API limits — you can never accidentally get your account throttled. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and (on a 429) Retry-After.

Category	Per minute	Per day	Applies to
Reads (GET)	120	20,000	boards, pins, me, accounts
Writes (POST/PATCH/DELETE)	20	1,000	each maps to a Pinterest write — kept Pinterest-safe
Analytics	30	2,000	Pinterest analytics is rate-limited hard

Errors

Errors return a consistent JSON body: { "error": { "code", "message" } }. Switch on error.code:

Code	HTTP	Meaning
unauthorized	401	No API key was provided.
invalid_api_key	401	The key is malformed, unknown, revoked, or expired.
plan_required	403	The account is not on the Agency plan.
validation_failed	400	One or more fields failed validation (see `fields`).
not_found	404	The requested resource does not exist or is not yours.
limit_reached	402	Your plan’s daily pin limit was reached.
rate_limited	429	Too many requests this minute — slow down.
daily_limit	429	The per-day rate limit for this key was reached.
no_pinterest_account	400	No Pinterest account is connected.
pinterest_error	502	Pinterest returned an error for the call.

Ready to build?

The API ships with the Agency plan. Create your key and make your first call in minutes.

Get the Agency plan →

The Burnpedia API