pinterest-api
Pinterest API v5 Development - Authentication, Pins, Boards, Analytics
When & Why to Use This Skill
This Claude skill provides comprehensive technical guidance and code implementation patterns for the Pinterest API v5. It streamlines the development lifecycle by offering expert assistance with OAuth 2.0 authentication flows, Pin and Board management, and the integration of Pinterest analytics. Designed for developers and growth engineers, it ensures best practices in rate limiting, error handling, and secure data management to build robust Pinterest-integrated applications.
Use Cases
- Automated Content Publishing: Programmatically create, update, and organize Pins and Boards to automate social media marketing workflows.
- Custom Analytics Dashboards: Fetch and aggregate real-time Pinterest performance metrics like impressions, saves, and clicks into internal business intelligence tools.
- Secure Third-Party Integrations: Implement robust OAuth 2.0 authentication to allow users to securely connect their Pinterest accounts to your web or mobile apps.
- E-commerce Syncing: Automatically generate Pins from product catalogs to keep Pinterest boards synchronized with the latest inventory and pricing.
- Business Account Management: Manage ad accounts and large-scale business profiles through API-driven automation for improved operational efficiency.
| name | pinterest-api |
|---|---|
| description | Pinterest API v5 Development - Authentication, Pins, Boards, Analytics |
Pinterest API Skill
Comprehensive assistance with Pinterest API v5 development, including OAuth authentication, pin/board management, analytics, and API integration patterns.
When to Use This Skill
This skill should be triggered when:
- Implementing Pinterest OAuth 2.0 authentication flows
- Creating, updating, or managing Pins and Boards via API
- Integrating Pinterest analytics and metrics into applications
- Building Pinterest API clients or SDKs
- Working with Pinterest user account data
- Debugging Pinterest API requests or responses
- Implementing Pinterest sharing features in web/mobile apps
- Setting up Pinterest business account integrations
- Working with Pinterest ad account APIs
Key Concepts
Pinterest API v5 Overview
- Base URL:
https://api.pinterest.com/v5/ - Authentication: OAuth 2.0 with access tokens
- Rate Limiting: Token-based rate limits (varies by endpoint)
- Response Format: JSON
- Required Headers:
Authorization: Bearer {access_token}
Core Resources
- Pins: Individual pieces of content (images, videos) saved to Pinterest
- Boards: Collections that organize Pins by theme or topic
- Sections: Subsections within Boards for additional organization
- User Account: Pinterest user profile and account information
- Ad Accounts: Business accounts for advertising functionality
Access Levels
- Public Access: Read-only access to public data
- User Authorization: Full access to user's Pins, Boards, and account
- Business Access: Additional analytics and ad account management (requires appropriate roles)
Quick Reference
OAuth 2.0 Authentication Flow
Step 1: Generate Authorization URL
// Redirect user to Pinterest authorization page
const authUrl = `https://www.pinterest.com/oauth/?client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&response_type=code&scope=boards:read,pins:read,user_accounts:read`;
window.location.href = authUrl;
Step 2: Exchange Code for Access Token
# After user authorizes, exchange authorization code for access token
curl -X POST https://api.pinterest.com/v5/oauth/token \
--header "Authorization: Basic {BASE64_ENCODED_CLIENT_CREDENTIALS}" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "code={AUTHORIZATION_CODE}" \
--data-urlencode "redirect_uri={REDIRECT_URI}"
Base64 Encoding Client Credentials:
# Encode client_id:client_secret
echo -n "your_client_id:your_client_secret" | base64
Response:
{
"access_token": "pina_ABC123...",
"token_type": "bearer",
"expires_in": 2592000,
"refresh_token": "DEF456...",
"scope": "boards:read,pins:read,user_accounts:read"
}
Pin Management
Create a Pin
curl -X POST https://api.pinterest.com/v5/pins \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"link": "https://example.com/my-article",
"title": "My Amazing Pin Title",
"description": "Detailed description of the pin content",
"board_id": "123456789",
"media_source": {
"source_type": "image_url",
"url": "https://example.com/image.jpg"
}
}'
Get Pin Details
curl -X GET https://api.pinterest.com/v5/pins/{PIN_ID} \
-H "Authorization: Bearer {ACCESS_TOKEN}"
Response:
{
"id": "987654321",
"created_at": "2025-01-15T10:30:00",
"link": "https://example.com/my-article",
"title": "My Amazing Pin Title",
"description": "Detailed description of the pin content",
"board_id": "123456789",
"media": {
"media_type": "image",
"images": {
"150x150": { "url": "...", "width": 150, "height": 150 },
"400x300": { "url": "...", "width": 400, "height": 300 },
"originals": { "url": "...", "width": 1200, "height": 800 }
}
}
}
Update a Pin
curl -X PATCH https://api.pinterest.com/v5/pins/{PIN_ID} \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"title": "Updated Pin Title",
"description": "Updated description",
"link": "https://example.com/updated-link"
}'
Delete a Pin
curl -X DELETE https://api.pinterest.com/v5/pins/{PIN_ID} \
-H "Authorization: Bearer {ACCESS_TOKEN}"
Board Management
Create a Board
curl -X POST https://api.pinterest.com/v5/boards \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "My New Board",
"description": "A collection of my favorite ideas",
"privacy": "PUBLIC"
}'
Privacy Options: PUBLIC, PROTECTED, SECRET
List User's Boards
curl -X GET https://api.pinterest.com/v5/boards \
-H "Authorization: Bearer {ACCESS_TOKEN}"
Get Board Pins
curl -X GET https://api.pinterest.com/v5/boards/{BOARD_ID}/pins \
-H "Authorization: Bearer {ACCESS_TOKEN}"
User Account
Get Current User Account
curl -X GET https://api.pinterest.com/v5/user_account \
-H "Authorization: Bearer {ACCESS_TOKEN}"
Response:
{
"account_type": "BUSINESS",
"id": "123456789",
"username": "myusername",
"website_url": "https://example.com",
"profile_image": "https://i.pinimg.com/...",
"follower_count": 1500,
"following_count": 320,
"board_count": 25,
"pin_count": 450
}
Analytics
Get Pin Analytics
curl -X GET "https://api.pinterest.com/v5/pins/{PIN_ID}/analytics?start_date=2025-01-01&end_date=2025-01-31&metric_types=IMPRESSION,SAVE,PIN_CLICK" \
-H "Authorization: Bearer {ACCESS_TOKEN}"
Available Metrics:
IMPRESSION- Number of times pin was shownSAVE- Number of times pin was savedPIN_CLICK- Number of clicks to pin destinationOUTBOUND_CLICK- Clicks to external websiteVIDEO_START- Video plays started
Response:
{
"all": {
"daily_metrics": [
{
"date": "2025-01-01",
"data_status": "READY",
"metrics": {
"IMPRESSION": 1250,
"SAVE": 45,
"PIN_CLICK": 89
}
}
]
}
}
Error Handling
Common Error Response
{
"code": 3,
"message": "Requested pin not found"
}
Common Error Codes:
1- Invalid request parameters2- Rate limit exceeded3- Resource not found4- Insufficient permissions8- Invalid access token
Python Error Handling Example
import requests
def create_pin(access_token, board_id, title, image_url):
url = "https://api.pinterest.com/v5/pins"
headers = {
"Authorization": f"Bearer {access_token}",
"Content-Type": "application/json"
}
data = {
"board_id": board_id,
"title": title,
"media_source": {
"source_type": "image_url",
"url": image_url
}
}
try:
response = requests.post(url, headers=headers, json=data)
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
error_data = e.response.json()
print(f"Error {error_data.get('code')}: {error_data.get('message')}")
return None
except requests.exceptions.RequestException as e:
print(f"Request failed: {str(e)}")
return None
JavaScript/Node.js Integration
// Pinterest API Client Example
class PinterestClient {
constructor(accessToken) {
this.accessToken = accessToken;
this.baseUrl = 'https://api.pinterest.com/v5';
}
async request(endpoint, options = {}) {
const url = `${this.baseUrl}${endpoint}`;
const headers = {
'Authorization': `Bearer ${this.accessToken}`,
'Content-Type': 'application/json',
...options.headers
};
const response = await fetch(url, {
...options,
headers
});
if (!response.ok) {
const error = await response.json();
throw new Error(`Pinterest API Error: ${error.message}`);
}
return response.json();
}
async createPin(boardId, title, imageUrl, description = '', link = '') {
return this.request('/pins', {
method: 'POST',
body: JSON.stringify({
board_id: boardId,
title: title,
description: description,
link: link,
media_source: {
source_type: 'image_url',
url: imageUrl
}
})
});
}
async getUserBoards() {
return this.request('/boards');
}
async getPinAnalytics(pinId, startDate, endDate) {
const params = new URLSearchParams({
start_date: startDate,
end_date: endDate,
metric_types: 'IMPRESSION,SAVE,PIN_CLICK'
});
return this.request(`/pins/${pinId}/analytics?${params}`);
}
}
// Usage
const client = new PinterestClient('your_access_token');
const pin = await client.createPin('board_id', 'Pin Title', 'https://example.com/image.jpg');
Reference Files
This skill includes comprehensive documentation in references/:
- api.md - Complete Pinterest API v5 endpoint reference extracted from official documentation
Use view to read reference files when detailed information about specific endpoints is needed.
Working with This Skill
For Beginners
- Start by understanding OAuth 2.0 authentication flow (see Quick Reference above)
- Get your API credentials from Pinterest Developer Portal
- Test authentication with curl commands before implementing in your application
- Use the provided Python/JavaScript examples as starting templates
For API Integration
- Implement OAuth flow to obtain access tokens
- Store refresh tokens securely for long-term access
- Use the Pin/Board management examples for CRUD operations
- Implement proper error handling for rate limits and API errors
For Analytics & Business Features
- Ensure you have appropriate business account access
- Use analytics endpoints to track Pin performance
- Aggregate metrics across date ranges for reporting
- Implement caching to avoid unnecessary API calls
Best Practices
- Token Security: Never expose access tokens in client-side code or version control
- Rate Limiting: Implement exponential backoff for rate limit errors
- Pagination: Use cursor-based pagination for large result sets
- Webhooks: Consider using webhooks for real-time updates instead of polling
- Scopes: Request only the minimum OAuth scopes needed for your application
Common Patterns
Pagination
# Initial request
curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25" \
-H "Authorization: Bearer {ACCESS_TOKEN}"
# Follow-up with bookmark from response
curl -X GET "https://api.pinterest.com/v5/boards/{BOARD_ID}/pins?page_size=25&bookmark={BOOKMARK}" \
-H "Authorization: Bearer {ACCESS_TOKEN}"
Bulk Operations
# Create multiple pins efficiently
def bulk_create_pins(access_token, board_id, pin_data_list):
results = []
for pin_data in pin_data_list:
result = create_pin(
access_token,
board_id,
pin_data['title'],
pin_data['image_url']
)
results.append(result)
time.sleep(0.5) # Respect rate limits
return results
Resources
Official Documentation
- Pinterest API v5 Docs: https://developers.pinterest.com/docs/api/v5/
- API Quickstart: https://github.com/pinterest/api-quickstart
- OAuth Documentation: https://developers.pinterest.com/docs/getting-started/authentication/
OAuth Scopes
Common scopes you'll need:
boards:read- Read board databoards:write- Create/update boardspins:read- Read pin datapins:write- Create/update pinsuser_accounts:read- Read user account dataads:read- Read ad account analytics (business accounts)
Rate Limits
- Pinterest implements per-user rate limiting
- Typical limits: 1000 requests per hour per user
- Rate limit headers in response:
X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset
Notes
- Pinterest API v5 is the current version (as of 2025)
- All endpoints require authentication via OAuth 2.0
- Access tokens expire after 30 days
- Use refresh tokens to obtain new access tokens
- Business accounts have access to additional analytics features
- Video pins require special handling compared to image pins
- Some features require app review by Pinterest
Troubleshooting
"Invalid access token"
- Verify token hasn't expired (30-day lifetime)
- Use refresh token to obtain new access token
- Check Authorization header format:
Bearer {token}
"Insufficient permissions"
- Verify OAuth scopes include required permissions
- Business features require verified business account
- Some operations require board/pin ownership
"Rate limit exceeded"
- Implement exponential backoff
- Cache responses when possible
- Use webhooks instead of polling
- Check
X-RateLimit-Resetheader for retry time
"Media upload failed"
- Verify image URL is publicly accessible
- Check image meets size requirements (max 10MB)
- Ensure image format is supported (JPG, PNG, GIF)
- For video, use video-specific endpoints
Updating
This skill was generated from Pinterest's official API documentation. To get the latest API changes:
- Visit https://developers.pinterest.com/docs/api/v5/
- Check changelog for API updates
- Review deprecation notices
- Update OAuth scopes if new features added