The Burnpedia API

Returns the authenticated account: plan, connected Pinterest accounts, and your current rate-limit status. Also returns `pins_today` (used / limit / remaining / unlimited — `limit` is null when unlimited), `plan_name`, a ready-to-print `plan_summary` sentence, and `upgrade_url` (null when you are already on the top plan). Render `plan_summary` rather than composing your own — it is built from the live plan table and honours an active trial. `pins_today.resets_at` is when the daily allowance comes back, as a UTC instant — format it in your reader's own timezone rather than saying "tomorrow". It is null on an unlimited plan. While a Pro trial is running you also get a `trial` object (active, plan, days_left, ends_at, upgrade_url); it is ABSENT when no trial is running, so its presence is the check. `trial.upgrade_url` is a short-lived link that lands on checkout with the plan already chosen. Treat it as opaque: do not construct one, do not modify it, and do not store it — it expires within a day.

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

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

Creates a public board on the selected Pinterest account.

Your scheduled, publishing, published, and failed pins. Filter with `status`, narrow to one website with `site` or `link_prefix`, and paginate with `limit` + `offset`.

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. No image? Set `cover: true` and we design one from the `title` — free, no AI points, and the same design every time for the same `link`. `image_url` wins when both are sent, so you can pass `cover: true` on every call and let the presence of a photo decide. Pass a `cover` object instead of `true` to force a look — it takes `palette` and `layout` (band, stack, frame, edge). `cover: {"ai": true}` sets the title over a photograph generated for it — that one costs AI points, and if it cannot be made you get the free cover instead and are not charged.

Retrieve a single pin you own by its Burnpedia id.

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

Deletes a pin from your Burnpedia queue.

Immediately publishes a scheduled pin to Pinterest.

Generates a Pinterest-shaped background photograph from a text prompt and returns a public `image_url` you pass straight to `POST /v1/pins`. Costs AI points (the response tells you how many, and how many you have left); nothing is charged if generation fails. ⚠️ This returns a PHOTOGRAPH with no text on it — titles, logos and the template library are composed in the Burnpedia dashboard, not here. `aspect` is optional and must be one of the vertical pin shapes 2:3, 9:16 or 1:2; omit it and one is chosen for you.

Writes a Pin title, description and keyword list from whatever you know about the post — send any of `topic`, `title`, `link` or `board_name`. Costs AI points (the response tells you how many, and how many you have left); nothing is charged if the request fails. ⚠️ This returns TEXT only — it does not draw anything. Setting that text on a photograph is the designer’s canvas work, which is free.

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

Impressions, saves, pin clicks and outbound clicks for the pins linking to one website, from our cached copy of Pinterest's per-pin analytics — so it costs none of your Pinterest rate limit and is safe to call on every page render. The window **ends two days ago** (`through_date`), because Pinterest reports about that late; treat anything after it as not-yet-reported rather than zero. Per-post rows (`pins`) are included on paid plans; every plan gets the site `totals`. `totals` covers **every** Pin matching the filter, while `pins` carries at most `pins_list_max` of them, newest first — compare `pins_listed` with `pins_total`, or read `pins_truncated`, to know whether the table is showing all of them.

Records how many times readers pressed a save button on your own website, per day, so the numbers can sit beside what your Pins for those pages earned. Send a host and a map of `YYYY-MM-DD` to a whole number, at most 90 dates per call. Each report REPLACES the stored count for the days it names, so re-sending a rolling window is safe and is how a gap heals — never send deltas. It carries no information about any visitor, and there is no field for one.

YOUR best-performing pins, ranked by engagement — the same list the Winning Pins gallery in the dashboard is built from. Each row carries the Pinterest pin id, the title, the destination link, an absolute image URL, and the impressions, saves, pin clicks and outbound clicks Pinterest reported for it. The window is the last 30 days and the list is the top 12 — both fixed, because Pinterest clamps this endpoint to a 90-day window and rate-limits it hard (60 analytics requests a minute per connected account, shared across every analytics call), so an open `limit` would let one integration exhaust the same budget its own dashboard needs. Titles and images are merged from pins you scheduled with us, so a pin Pinterest reports on but has no title for still renders. These are YOUR pins: there is no way to read another account’s analytics, here or anywhere in the Pinterest API.

The colours, font and logo saved on your account, as `{ panel, accent, text, font, logo_url, logo_position }`. `has_kit` is false until you have saved one — an all-blank kit and no kit at all mean different things.

Stores a brand kit on the account so the same colours are available on every site you run. Send `{ "brand_kit": { "panel": "#ffffff", "accent": "#e11d48", "text": "#111111" } }`. A kit whose title colour does not reach 4.5:1 against its background is refused — an unreadable kit here would be handed to every other site you connect. Send a kit with no colours to clear it.