To manage Pins, Boards, and analytics without manual intervention in the web dashboard, you will use the Pinterest API v5.
Moving beyond the limitations of the standard user interface requires establishing a formal integration through the Pinterest Developer Platform. While Activepieces provides an MIT-licensed core to automate these requests, the initial handshake with Pinterest’s infrastructure depends on a specific set of administrative credentials.
Set up Pinterest API v5 access
Creating a Pinterest Business account
Personal accounts don't have the permissions necessary to create applications, making a Pinterest Business account the foundational requirement for API access. Once the business profile is active, you must complete domain verification to prove ownership of the website associated with the app.

This prevents unauthorized third parties from claiming traffic data from your URL.
Registering your application in the Developer Console
By creating a new application entry within the Pinterest Developer Console, you obtain your unique authentication credentials. The following four prerequisites are mandatory for a functional integration:
- A Pinterest Business account.
- A verified domain.
- The App ID from the Developer Console.
- The App Secret key.
The App ID functions as a public identifier. The App Secret acts as a password that must be stored in a secure environment variable to prevent account takeover.
Setting Pinterest API OAuth scopes and permissions
Pinterest uses the OAuth 2.0 protocol to ensure that an application only accesses the specific data a user has authorized. During the initial configuration, you must define scopes such as boards:read or pins:write to limit the application’s reach.
If these scopes aren't correctly declared in the Developer Console before the authorization code is requested, the API will return a 403 Forbidden error even if the App Secret is valid.

This takes minutes, not a project: automate it in Activepieces free.
Authenticate Pinterest API requests via OAuth
Because Pinterest secures all API v5 endpoints using the OAuth 2.0 protocol, you must implement a refreshable token system to maintain persistent access.
Pinterest three-legged OAuth authorization flow
When the user, the application, and the Pinterest authorization server interact to validate permissions, they are engaging in a three-legged flow.
The process begins when the user is redirected to a Pinterest-hosted consent page to approve specific scopes. Upon approval, Pinterest sends a temporary, one-use authorization code back to your registered Redirect URI.
Building the Pinterest OAuth authorization URL
To initiate the handshake, your application must generate a GET request to the Pinterest authorization endpoint. This URL must include the client_id, the redirect_uri exactly as it appears in the app settings, and a space-separated list of scope values.
Developers should also include a state parameter to serve as a CSRF protection measure. A malformed URL or a mismatch in the Redirect URI will trigger a 400 Bad Request error, preventing the user from seeing the consent screen.

Exchanging the authorization code for an access token
Once you capture the authorization code, you must exchange it for tokens via a POST request to the Pinterest token endpoint.
This request requires Basic Authentication headers, where the username is the Client ID and the password is the Client Secret.
curl -X POST https://api.pinterest.com/v5/oauth/token \
-u "CLIENT_ID:CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTHORIZATION_CODE" \
-d "redirect_uri=https://your-app.com/callback"
The response contains an Access Token for immediate requests and a Refresh Token to generate new credentials.
| Token Type | Duration | Consequence of Expiration |
|---|---|---|
| Access Token | 30 days | A production environment must include a scheduled task or a failure-retry loop to swap the Refresh Token before that mark. |
| Refresh Token | 60 days | If the Refresh Token itself reaches the limit without being used to generate a new pair, the entire connection is severed, requiring a manual re-login by the end user. |
30 days is the duration of the Access Token according to Pinbridge's analysis, so developers must implement a refresh strategy to avoid service interruptions.
As stated by Pinbridge, if the Refresh Token itself reaches the 60-day limit without being used to generate a new pair, the entire connection is severed, requiring a manual re-login by the end user.
Manage Pins and Boards via API
Pinterest API v5 manages content through structured POST and PATCH requests to the /pins and /boards endpoints.
Creating and updating Pins programmatically
The /pins POST endpoint is the primary gateway for programmatic content distribution. You must adhere to exact character and file size constraints to avoid API errors.
| Field | Limit | Consequence of exceeding |
|---|---|---|
| Title | 100 chars | The API returns a validation error, preventing the Pin from being indexed for search. |
| Description | 800 chars | Metadata is truncated or rejected, reducing the context available for the Pinterest algorithm. |
| Image Size | 20MB | High-resolution assets fail to upload, requiring a pre-processing compression step. |
| Video Size | 2GB | Large video files result in request timeouts, necessitating a chunked upload strategy. |

Once a Pin is live, the PATCH /pins/{pin_id} endpoint enables metadata updates, though it can't swap the underlying media asset.
Retrieving Board metadata and Pin lists
The structural hierarchy needed to sync external databases is provided by the GET /boards and GET /boards/{board_id}/pins endpoints.
Pagination is enforced via a bookmark parameter. A script attempting to pull a complete library without handling cursor-based navigation will only receive the first batch of results.
Accessing Pinterest Analytics and user metrics
Analytics are retrieved through the /analytics sub-resources, specifically targeting the /pins/{pin_id}/analytics and /boards/{board_id}/analytics paths. These endpoints return a time-series data model that includes IMPRESSION, SAVE, and CLICKTHROUGH counts.
Because Pinterest calculates these metrics asynchronously, a request for data on a Pin created within the last few hours often returns empty values. You must implement a delay or a recurring polling schedule to capture the engagement data.
Because Pinterest calculates these metrics asynchronously, a request for data on a Pin created within the last few hours often returns empty values.
You can follow the rest of this with the builder open. Start free, no card.
Monitor Pinterest API rate limits
Pinterest restricts programmatic access to determine the volume of content an application can distribute or retrieve.
Understanding the Trial vs. Standard access levels
Every new application begins at the Trial level, which limits the total number of unique users who can authenticate with the app. Once an application exceeds the minimum threshold for active users and demonstrates stable error rates, you can apply for Standard access.
Moving to the Standard tier increases the per-minute request limits, allowing a business to scale its automated pinning strategies.
How Pinterest calculates rate limit resets
Pinterest manages traffic using fixed rate limits, calculating usage based on the number of requests made within each one-minute window.
| Operation Type | Requests per Minute | Consequence for the Developer |
|---|---|---|
| GET/Read | 1,000 | High-frequency analytics and board monitoring are sustainable. |
| POST/Write | 100 | Bulk image uploads must be staggered to avoid 429 errors. |
| Search | 10 | Keyword discovery must be cached heavily to prevent service blocks. |
Reading Pinterest API rate limit headers
Through the x-ratelimit-remaining and x-ratelimit-limit fields in the HTTP response headers, the API returns real-time feedback on remaining capacity.
If the remaining count hits zero, the x-ratelimit-reset header contains a Unix timestamp indicating how long the execution thread must sleep before the server will accept the next packet.
Troubleshooting common Pinterest API errors and production failures
Fixing Pinterest API 429 rate limit errors
Pinterest returns a 429 status code when an application exceeds its allotted call volume. To prevent permanent blocking, the Pinterest developer documentation mandates an exponential backoff strategy:
- Wait 1s
- Wait 2s
- Wait 4s
- Wait 8s
- Wait 16s before final failure.
Fixing Pinterest API 401 unauthorized token errors
When the Authorization header contains a token that is missing or expired, the API returns a 401 Unauthorized error. You must implement a refresh flow using the refresh_token provided during the initial OAuth handshake to maintain a valid session.

Fixing Pinterest API 403 forbidden scope errors
The 403 Forbidden error occurs when the access token lacks the specific scopes required for the requested endpoint. The application must be re-authorized with the correct scope string, such as pins:write or ads:read, as defined in the Pinterest API Scopes documentation.
Automating Pinterest workflows without manual API maintenance
Connecting Pinterest to your tech stack in Activepieces
Activepieces manages the entire Pinterest authentication lifecycle for enterprise teams. When you create a new connection, the platform initiates a secure OAuth flow that requests specific scopes (such as boards:read or pins:write).

This abstraction handles the background exchange of authorization codes for refresh tokens, bypassing the need to build a custom callback listener or a secure database for storing sensitive client secrets.
Activepieces allows teams to generate missing integrations with AI and add them privately to their own instance, ensuring that a missing connector never blocks a Pinterest sync.
Check the open-source monorepo, the catalogue of 750 integrations is counted directly from it, not published as a marketing figure, ensuring that the number reflects actual, deployable code.
Roughly 60% of these integrations are community-contributed, built by users who needed specific functionality that wasn't yet in the vendor's queue, meaning the platform's utility is heavily driven by its own user base.
Triggering actions on new Pins or Board updates
Mapping a creative workflow starts with defining a trigger that monitors account activity. This allows you to bridge the gap between design tools and social distribution without writing polling scripts.
Once a Pin is detected, the flow passes the metadata to subsequent steps for analysis or cross-posting. This modular approach allows for complex logic, such as using AI to generate SEO descriptions for a WordPress post based on the original Pin’s image context.
Activepieces syncs these flows to git and promotes them through Release Management, ensuring that changes to a Pinterest marketing pipeline are versioned and reviewed like software.
Check Activepieces' own documentation for Git Sync and Release Management to see how this works across both self-hosted and cloud environments.
The production checklist for scaling Pinterest integrations
Transitioning from a trial environment to Standard access requires a hardened architecture that accounts for Pinterest’s strict OAuth lifecycles.
Moving to "Standard" access requires a formal App Review where Pinterest employees verify that your application provides a clear value proposition. To survive this transition and maintain uptime, you must implement the following production-readiness items:
- Refresh token rotation logic to prevent authentication expiration when access tokens lapse.
- 429 error handling with exponential backoff to respect rate limits and avoid temporary IP blacklisting.
- Webhook verification using the
x-pinterest-signatureheader to ensure incoming data originates from Pinterest and not a malicious actor. - App Review submission documentation, including a screencast of the integration, to satisfy the manual audit requirements for Standard tier access.
Frequently asked questions about the Pinterest API?
Can I upload video Pins via the API?
Provided you first register a unique media upload URL through the /media endpoint, you can upload video Pins programmatically. This multi-step handshake is necessary because the Pinterest API v5 doesn't support direct binary uploads within the standard Pin creation request.
How do I access private Boards through the API?
Private boards are accessible only if the application requests and the user grants the boards:read scope during the OAuth 2.0 authorization flow. Without this specific permission, the API returns a filtered list that excludes secret content.
Is there a cost for using the Pinterest API?
Standard access to the Pinterest API v5 is currently provided at no financial cost to developers who successfully complete the app review process. While there's no per-request fee, the platform enforces strict rate limits based on the application's tier.
Build it
Set this up in minutes.
No code required. Connect your accounts, and Activepieces runs it from there.
Start free Talk to sales


