pinterest-api

仓库: rawveg/skillsforge-marketplace
安装量: 43
排名: #16994

安装

npx skills add https://github.com/rawveg/skillsforge-marketplace --skill pinterest-api

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

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

  • 2 - Rate limit exceeded

  • 3 - Resource not found

  • 4 - Insufficient permissions

  • 8 - 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

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:

← 返回排行榜