Pinterest API: pins, boards and the approval you need first

The Pinterest API v5 lives at https://api.pinterest.com/v5. You can create boards and Pins on day one, but on Trial access they are visible only to you, and Pinterest wants a demo video showing the OAuth flow before it grants Standard. Here is the whole path, read on November 11, 2026.

What the API gives you, and the order it gives it in

Pinterest exposes two worlds behind one base URL: organic content (boards, Pins, user accounts, media uploads) and ads (campaigns, audiences, catalogs, reporting). Both use the same bearer token, gated by scopes, and both are rationed by the access tier your app sits in.

The order matters, because almost nobody reads it in advance. You do not get an API key, write code and ship. You get an app approved for Trial, build against limits counted per day rather than per minute, then prove on video that it works before anything you create is visible to anyone else.

Trial access vs Standard access

Two tiers, no others. From Pinterest's access tiers guide, read today:

Read the visibility row twice. On Trial, a Pin your integration creates is a Pin only you can see. Every "it works but nothing appeared" ticket starts there.

To move up: the app must already be approved for Trial and comply with the Developer Guidelines, and you submit a video of your app completing an action with the Pinterest API that shows the OAuth flow. That applies even if you are the only user, and terminal or Postman screen recordings are accepted. Pinterest verifies your use case and your privacy policy link during submission. You go to My apps, select Upgrade on the app card, confirm the information, upload the video, submit. There is no published timeline: requests are "reviewed regularly" and you get an email with the decision. If it is denied and you appeal through a Help Center ticket, allow "a few days".

Getting the app in the first place

Before any of that: create or log into a Pinterest business account, verify your email, accept the Developer Terms of Service on My apps, then submit the app request form. Pinterest reviews it and emails an approval or a denial. Approval for Trial also gets you product-limited test tokens, which expire after 24 hours and suit poking at endpoints, not anything you leave running.

There is a sandbox too, the honest place to learn the request shapes without burning 300 daily writes.

OAuth, scopes, and the token that dies at 60 days

Three grants, and only one of them gives you the whole API:

• Authorization Code, for acting on a user's behalf. The user approves scopes at https://www.pinterest.com/oauth/, lands back on your redirect_uri with a code, and your server exchanges it at oauth/token. This is the only grant with full API coverage.
• Client Credentials, for your own developer account. It requires two-factor authentication and cannot reach some sensitive endpoints.
• Refresh Token, to swap a refresh token for a fresh access token with no user involved.

The authorize call wants client_id, redirect_uri, response_type=code and scope. state is optional and you should send it anyway, since it is what protects the callback from cross-site request forgery.

Scopes read as {entity}:read and {entity}:write, comma or space separated, over the entities ads, billing, biz_access, boards, catalogs, pins and user_accounts. Secret variants exist for private content: boards:read_secret, pins:write_secret. Pinterest's own advice is to "request the minimum number of scopes from your users to meet their business needs", which is also the advice that keeps your app review short.

Now the part that breaks integrations months later. The access token carries expires_in: 2592000, so 30 days. The legacy refresh token had refresh_token_expires_in: 31536000, a year with a hard stop, and Pinterest no longer supports it. The continuous refresh token expires after 60 days but can be refreshed indefinitely, so you have to actually refresh inside that window to keep it alive. Apps created before September 25, 2025 must pass continuous_refresh=true to get it; apps created on or after that date get it automatically. Miss the window and there is no repair call, only the full Authorization Code flow again, with the user in front of the screen. An expired or invalid token answers HTTP 401 with API error code 2.

If that pattern sounds familiar, it is the same shape as every other platform: short token, long token, silent expiry. I wrote up the general version in social media access tokens.

Creating a board and a Pin

Boards come first, because a Pin needs somewhere to live. The create calls are boards/create and pins/create, and the scopes you need are boards:read, boards:write, pins:read and pins:write. The read scopes are not decoration: to create a Pin you need the ID of the board or board section, and that ID comes from a read.

A media_source object carries the image or video. The documented source types are image_url and video_id. For an image Pin, image_url plus board_id, title and description is the whole body. A valid image URL is not optional: Pinterest warns that "A valid image url must be provided to avoid a 400 Bad Request."

Video is three calls plus a poll:

1. POST https://api.pinterest.com/v5/media with {"media_type": "video"}. You get back a media_id, an upload_url and an upload_parameters block.
2. POST the file to upload_url as multipart/form-data, passing every key of upload_parameters as a form field alongside the .mp4, .mov or .m4v. No Authorization header on this one. Success is 204 No Content.
3. GET /v5/media/{media_id} until the status reads succeeded. Processing takes a few seconds, and during it creative_type may still say REGULAR before it flips to VIDEO.
4. POST /v5/pins with media_source.source_type set to video_id, the media_id, and a cover_image_url. Success is 201 Created with the Pin ID.

Two ceilings to know before designing a bulk import: 2,000 boards of any type, including group boards you did not create, and 200,000 Pins on a personal account, secret Pins and your Pins on group boards included. If you are re-pinning content that already exists on Pinterest, pins/save is the right call instead of pins/create, precisely so you do not spend those entity limits.

One recent trap: apps registered on or after September 14, 2026 can get 403 PINNER_DATA_ACCESS_DENIED when they request a board or Pin belonging to a non-business user without Pinterest's authorization. Test with a business account.

pinterest api python: the shape of it

No SDK required, requests is enough. This is the create-Pin call with the documented fields:

import os, requests

TOKEN = os.environ["PINTEREST_ACCESS_TOKEN"]
BASE = "https://api.pinterest.com/v5"
headers = {"Authorization": f"Bearer {TOKEN}"}

boards = requests.get(f"{BASE}/boards", headers=headers, timeout=30).json()
board_id = boards["items"][0]["id"]

pin = requests.post(
    f"{BASE}/pins",
    headers=headers,
    json={
        "board_id": board_id,
        "title": "Weeknight pasta",
        "description": "Ten minutes, one pan.",
        "link": "https://example.com/recipes/weeknight-pasta",
        "media_source": {"source_type": "image_url",
                         "url": "https://example.com/img/pasta.jpg"},
    },
    timeout=30,
)
print(pin.status_code, pin.json())

Watch x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset on every response. On Trial they count down a daily budget, so a retry loop on a failing call can end your testing day before lunch. Pinterest publishes no price for API access: the tiers and these limits are the rationing.

Where Pinterest sits next to the other platform APIs

Pinterest sits on the easier half of the spectrum: ordinary OAuth, simple entities, short create calls. What it charges instead is the review, the app form then the demo video then the wait, before anything you publish is visible to anyone else. Meta also charges an app review but hands you public visibility from the start, covered in the Instagram Graph API guide. The cross-platform view, rate limits per network included, is in the social media API guide and the rate limits reference.

One thing to be straight about: PlugKit does not publish to Pinterest. It covers Instagram, Facebook, LinkedIn, TikTok, YouTube, X, Threads, Bluesky, WhatsApp and Telegram, and Pinterest is not on that list today. If Pinterest is your main channel, write against v5 yourself, or pick a tool that names it.

FAQ

Is the Pinterest API free?

Pinterest does not publish a price for API access. What it rations is requests and visibility: Trial access caps you at 1,000 requests a day per app and keeps the boards and Pins you create visible only to their creator, while Standard moves the limits to 100 requests per second per user per app. Ads endpoints still require an ad account.

How do I get Standard access to the Pinterest API?

Get the app approved for Trial first, stay inside the Developer Guidelines, then go to My apps and select Upgrade on the app card. The submission asks for your use case, a privacy policy link, and a video of your app completing an API action that shows the OAuth flow. A terminal or Postman recording counts. Pinterest emails the decision.

Why can nobody see the Pins my app creates?

Because the app is on Trial access, where boards and Pins are visible only to their creator. That is documented behaviour, not a bug in your code. Upgrading to Standard is what makes them public.

How long does a Pinterest access token last?

The access token lasts 30 days (expires_in: 2592000). The continuous refresh token expires after 60 days but can be refreshed forever, so you must refresh inside that window. Apps created before September 25, 2025 need continuous_refresh=true to get it. An expired token returns HTTP 401 with API error code 2.

Can I post to Pinterest from an AI agent?

Only by writing against v5 yourself or using a tool that supports Pinterest. There is no Pinterest MCP server from Pinterest, and PlugKit does not cover Pinterest. The pattern for the platforms that are covered is in MCP or REST API for your agent.

AB

Antoine BlancoFounder of PlugKit. Runs his own Instagram, YouTube and X accounts through the API and MCP server described here.