A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Pinterest API is how an app or AI agent works with a Pinterest account: creating a Pin, organising boards and board sections, reading the signed-in user account, searching that user's Pins and boards, and pulling analytics. Access is granted through an OAuth access token, and the token carries scopes such as pins:read, boards:write, and user_accounts:read that set which areas a call can read or write. New apps start on a trial access tier with low daily caps and request standard access for higher per-minute limits.
How an app or AI agent connects to Pinterest determines what it can reach. There is a route for making calls on behalf of a user, and an alpha server that exposes Pinterest advertising data to agents, and each is governed by the access token behind it and the OAuth scopes that token carries.
The REST API takes JSON requests, returns JSON, and pages through lists with a bookmark cursor, at https://api.pinterest.com/v5. A call authenticates with an OAuth 2.0 access token sent as a Bearer token, and the token's scopes plus the signed-in user's roles decide what it can reach.
A first-party Model Context Protocol server, shipped 17 June 2026, exposes Pinterest advertising data to AI agents and LLM clients. It is in alpha with named partners only and is read-only at launch, giving an agent read access to campaign performance, analytics, keyword insights, and Taste Graph signals, with any change still routed through a person. It does not cover general content like Pins or boards.
An app sends the user to Pinterest to authorize a chosen set of scopes, gets an authorization code, and exchanges it for an access token and a refresh token. The access token represents the signed-in user and is sent as a Bearer token. Scopes are fixed at authorization time, and the user must also hold the right role on the board or account being touched.
A client-credentials flow issues an app-context token without a specific user, used for app-level operations that do not act on one person's content. It authenticates the same way, as a Bearer token, and is limited to what an app-level token is allowed to do.
The Pinterest API is split into areas an agent can act on, like Pins, boards, board sections, the signed-in user account, search, and analytics. Each area has its own methods, and a write here creates or removes real content on a person's profile.
Methods for listing, reading, creating, updating, and deleting Pins.
Methods for listing, reading, creating, updating, and deleting boards.
Methods for working with the sections inside a board.
Methods for registering and tracking media uploads for video Pins.
Methods for searching the signed-in user's own Pins and boards.
Methods for reading the signed-in user account, its followers, and its analytics.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PinsMethods for listing, reading, creating, updating, and deleting Pins.8 | ||||||
| GET | /v5/pins | List the Pins owned by the signed-in user. | read | pins:read | Current | |
Returns public Pins; pins:read_secret is also needed to include secret Pins. Acts onpin Permission (capability) pins:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/pins/{pin_id} | Get a single Pin by id. | read | pins:read | Current | |
A secret Pin requires pins:read_secret. Acts onpin Permission (capability) pins:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v5/pins | Create a Pin on a board, from an image URL or a registered media upload. | write | pins:write | Current | |
Also reads boards (boards:read) to place the Pin; a secret board needs the secret scopes. Acts onpin Permission (capability) pins:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v5/pins/{pin_id} | Update an existing Pin, such as its title, description, or board. | write | pins:write | Current | |
A secret Pin requires pins:write_secret. Acts onpin Permission (capability) pins:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v5/pins/{pin_id} | Delete a Pin permanently. | write | pins:write | Current | |
Irreversible; a secret Pin requires pins:write_secret. Acts onpin Permission (capability) pins:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v5/pins/{pin_id}/save | Save (repin) an existing Pin to one of the user's boards. | write | pins:write | Current | |
Also reads and writes the destination board (boards:read, boards:write). Acts onpin Permission (capability) pins:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/pins/{pin_id}/analytics | Get analytics for a single Pin, such as impressions, saves, and clicks. | read | pins:read | Current | |
Read-only. Acts onpin_analytics Permission (capability) pins:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/pins/analytics | Get analytics for multiple Pins in one request. | read | pins:read | Current | |
Read-only; limited to a set of Pin ids per call. Acts onpin_analytics Permission (capability) pins:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BoardsMethods for listing, reading, creating, updating, and deleting boards.6 | ||||||
| GET | /v5/boards | List the boards owned by or shared with the signed-in user. | read | boards:read | Current | |
Returns public boards; boards:read_secret is needed to include secret boards. Acts onboard Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/boards/{board_id} | Get a single board by id. | read | boards:read | Current | |
A secret board requires boards:read_secret. Acts onboard Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v5/boards | Create a board for the signed-in user. | write | boards:write | Current | |
A secret board requires boards:write_secret. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v5/boards/{board_id} | Update a board's name, description, or privacy. | write | boards:write | Current | |
A secret board requires boards:write_secret. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v5/boards/{board_id} | Delete a board and all of the Pins on it. | write | boards:write | Current | |
Irreversible; removes the board's Pins. A secret board requires boards:write_secret. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/boards/{board_id}/pins | List the Pins on a board. | read | boards:read | Current | |
Also reads Pins (pins:read); a secret board needs the secret scopes. Acts onpin Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Board sectionsMethods for working with the sections inside a board.5 | ||||||
| GET | /v5/boards/{board_id}/sections | List the sections within a board. | read | boards:read | Current | |
A secret board requires boards:read_secret. Acts onboard_section Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v5/boards/{board_id}/sections | Create a section within a board. | write | boards:write | Current | |
A secret board requires boards:write_secret. Acts onboard_section Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v5/boards/{board_id}/sections/{section_id} | Update a board section, such as its title. | write | boards:write | Current | |
A secret board requires boards:write_secret. Acts onboard_section Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v5/boards/{board_id}/sections/{section_id} | Delete a section from a board. | write | boards:write | Current | |
A secret board requires boards:write_secret. Acts onboard_section Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/boards/{board_id}/sections/{section_id}/pins | List the Pins within a board section. | read | boards:read | Current | |
Also reads Pins (pins:read); a secret board needs the secret scopes. Acts onpin Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MediaMethods for registering and tracking media uploads for video Pins.3 | ||||||
| POST | /v5/media | Register a media upload to get a media_id and an upload location for a video Pin. | write | pins:write | Current | |
Registers the upload; the file is then sent to the returned location and referenced by media_id at Pin creation. Acts onmedia_upload Permission (capability) pins:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/media | List the media uploads registered by the signed-in user. | read | pins:read | Current | |
Read-only. Acts onmedia_upload Permission (capability) pins:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/media/{media_id} | Get the status and details of a registered media upload. | read | pins:read | Current | |
Read-only; used to check that a video has finished processing before creating the Pin. Acts onmedia_upload Permission (capability) pins:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchMethods for searching the signed-in user's own Pins and boards.2 | ||||||
| GET | /v5/search/pins | Search the signed-in user's own Pins by a term. | read | pins:read | Current | |
Also reads boards (boards:read); secret content requires the secret read scopes. Acts onpin Permission (capability) pins:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/search/boards | Search the signed-in user's own boards by a term. | read | boards:read | Current | |
Secret boards require boards:read_secret. Acts onboard Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
User account & analyticsMethods for reading the signed-in user account, its followers, and its analytics.3 | ||||||
| GET | /v5/user_account | Get the signed-in user's account profile and type. | read | user_accounts:read | Current | |
Read-only. Acts onuser_account Permission (capability) user_accounts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/user_account/analytics | Get account-level analytics for the signed-in user. | read | user_accounts:read | Current | |
Read-only. Acts onuser_account_analytics Permission (capability) user_accounts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v5/user_account/followers | List the followers of the signed-in user. | read | user_accounts:read | Current | |
Read-only. Acts onfollower Permission (capability) user_accounts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Pinterest does not offer a general webhook system for content events like a Pin being created. An app learns about new activity by calling the API, and lead-ad and conversion features have their own narrow delivery mechanisms.
| Event | What it signals | Triggered by |
|---|
Pinterest limits how fast an app can call, by sorting every endpoint into a rate-limit category and capping calls per app and per user. The ceiling depends on whether the app is on trial access or standard access.
Pinterest sorts every endpoint into a rate-limit category and applies limits per app and per user, not by a per-method point cost. The overall ceiling depends on the access tier: a trial-access app is capped at roughly 1,000 requests per day across all requests, while a standard-access app gets 100 requests per second per user per app, with separate per-minute limits per category (for example ads:read at 1,000 per minute, org_write at 100 per minute). Going over returns HTTP 429, and the response carries x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers so a caller can pace itself. Limits are subject to change.
List endpoints are cursor-based. A page_size parameter sets how many items come back, defaulting to 25 and capping at 250. The response includes a bookmark string, and a caller passes that bookmark back on the next request to fetch the following page; an empty bookmark means there are no more pages.
A single page returns at most 250 items, the maximum value of page_size. Media for video Pins is uploaded out of band: an app registers an upload, receives a media_id and storage location, uploads the file there, then references the media_id when creating the Pin.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed: a parameter is missing, has the wrong type, or fails validation. | Read the error message, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | No valid access token was provided, or the token has expired. | Refresh the access token with the refresh token, or re-run the OAuth flow, then resend. |
| 403 | Forbidden | The token is valid but lacks the scope for this call, or the user lacks the role on the board or account being touched. | Re-authorize with the needed scope, or have the user granted the right role, then resend. |
| 404 | Not Found | The requested object does not exist or is not visible to this token, for example a secret Pin without a secret scope. | Verify the object id and confirm the token has the scope and role to see it. |
| 409 | Conflict | The request conflicts with the current state of the resource, for example a duplicate or competing operation. | Re-fetch the resource, reconcile the state, and retry the operation. |
| 429 | Too Many Requests | A rate-limit category was exceeded for the app or the user. | Back off using the x-ratelimit-reset header, then retry. Apply for standard access for higher limits. |
| 500 | Internal Server Error | An error on Pinterest's side. It is rare. | Retry with backoff, and contact Pinterest support if it persists. |
Pinterest carries one major API version in the path, v5, and ships dated, mostly additive releases tracked by a minor version number rather than minting a new major version for each change.
v5 is the only supported major version of the Pinterest API, with v3 deprecated in June 2023. It carries the version in the path and ships dated minor releases (5.x) through the changelog and the published OpenAPI description, most additive and some marked breaking. The OpenAPI description was at version 5.28.0 when last verified.
A batch of advertising-focused minor releases published together, several flagged as breaking on ads, ad-group, audience, and ad-account endpoints.
An additive release across bulk operations and catalogs.
An additive release on ad-group conversion reporting.
Build against v5 and follow the changelog for additive and occasionally breaking minor releases.
Pinterest API changelog ↗Bollard AI sits between a team's AI agents and Pinterest. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.