pinterest-api

What this skill does

# 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) {