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

javascript

// 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

bash

# 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:

bash

# Encode client_id:client_secret
echo -n "your_client_id:your_client_secret" | base64

Response:

json

{
  "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

bash

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

bash

curl -X GET https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Response:

json

{
  "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

bash

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

bash

curl -X DELETE https://api.pinterest.com/v5/pins/{PIN_ID} \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Board Management

Create a Board

bash

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

bash

curl -X GET https://api.pinterest.com/v5/boards \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Get Board Pins

bash

curl -X GET https://api.pinterest.com/v5/boards/{BOARD_ID}/pins \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

User Account

Get Current User Account

bash

curl -X GET https://api.pinterest.com/v5/user_account \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Response:

json

{
  "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

bash

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 shown
```
SAVE
```
- Number of times pin was saved
```
PIN_CLICK
```
- Number of clicks to pin destination
```
OUTBOUND_CLICK
```
- Clicks to external website
```
VIDEO_START
```
- Video plays started

Response:

json

{
  "all": {
    "daily_metrics": [
      {
        "date": "2025-01-01",
        "data_status": "READY",
        "metrics": {
          "IMPRESSION": 1250,
          "SAVE": 45,
          "PIN_CLICK": 89
        }
      }
    ]
  }
}

Error Handling

Common Error Response

json

{
  "code": 3,
  "message": "Requested pin not found"
}

Common Error Codes:

```
1
```
- Invalid request parameters
```
2
```
- Rate limit exceeded
```
3
```
- Resource not found
```
4
```
- Insufficient permissions
```
8
```
- Invalid access token

Python Error Handling Example

python

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

javascript

// 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

bash

# 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

python

# 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 data
```
boards:write
```
- Create/update boards
```
pins:read
```
- Read pin data
```
pins:write
```
- Create/update pins
```
user_accounts:read
```
- Read user account data
```
ads: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-Limit
```
```
X-RateLimit-Remaining
```
```
X-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-Reset
```
header 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

pinterest-api

NPX Install

Tags

SKILL.md Content

Pinterest API Skill

When to Use This Skill

Key Concepts

Pinterest API v5 Overview

Core Resources

Access Levels

Quick Reference

OAuth 2.0 Authentication Flow

Step 1: Generate Authorization URL

Step 2: Exchange Code for Access Token

Pin Management

Create a Pin

Get Pin Details

Update a Pin

Delete a Pin

Board Management

Create a Board

List User's Boards

Get Board Pins

User Account

Get Current User Account

Analytics

Get Pin Analytics

Error Handling

Common Error Response

Python Error Handling Example

JavaScript/Node.js Integration

Reference Files

Working with This Skill

For Beginners

For API Integration

For Analytics & Business Features

Best Practices

Common Patterns

Pagination

Bulk Operations

Resources

Official Documentation

OAuth Scopes

Rate Limits

Notes

Troubleshooting

"Invalid access token"

"Insufficient permissions"

"Rate limit exceeded"

"Media upload failed"

Updating