Pinterest API for Pins: Complete Guide to Creating and Managing Pins in 2026

Mastering the Pinterest API for Pins is essential for developers and marketers looking to automate content discovery and drive traffic through visual search. Unlike other social platforms, Pinterest functions as a discovery engine, making the programmatic creation and management of Pins a powerful strategy for long-term growth.

In this guide, we will explore the core endpoints of the Pinterest API for Pins, covering how to create, list, update, and analyze Pins programmatically. We will also dive into the specific rate limits, authorization scopes, and data structures required to build robust Pinterest integrations. All information is based on the official Pinterest API v5 documentation.

Creating a Pin (POST /pins)

The core function of the Pinterest API for Pins is the creation of new content. This endpoint allows you to upload an image or video directly to a specific board or board section.

This function is intended solely for publishing new content created by the user. Required scopes include pins:write and boards:read. According to Pinterest’s official endpoint reference, sandbox support is enabled for testing purposes.

Request Parameters

When creating a Pin via the Pinterest API for Pins, you must construct a JSON payload containing the following key fields:

Field	Type	Description
board_id	string (required)	The ID of the board where the Pin will be saved.
media_source	object (required)	Image Base64-based media source or image URL.
title	string (optional)	Max 100 characters.
description	string (optional)	Max 800 characters.
link	string (optional)	Destination URL (Max 2048 chars).
alt_text	string (optional)	Accessibility text (Max 500 chars).

Example Request Body

{
  "title": "Summer Outfit Inspiration",
  "description": "The perfect look for a sunny day at the beach.",
  "link": "https://www.yourfashionblog.com/summer-looks",
  "board_id": "1234567890",
  "media_source": {
    "source_type": "image_base64",
    "content_type": "image/jpeg",
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
  },
  "alt_text": "A woman wearing a summer dress on the beach"
}

Python Example: Create a Pin

Here is a practical Python implementation for creating a Pin using the Pinterest API for Pins:

import requests
import base64

ACCESS_TOKEN = "your_access_token"
BOARD_ID = "1234567890"

# Read and encode image
with open("my_image.jpg", "rb") as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode("utf-8")

url = "https://api.pinterest.com/v5/pins"
headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json"
}

payload = {
    "title": "My Automated Pin",
    "description": "Created via the Pinterest API for Pins",
    "link": "https://yourwebsite.com/article",
    "board_id": BOARD_ID,
    "media_source": {
        "source_type": "image_base64",
        "content_type": "image/jpeg",
        "data": encoded_image
    },
    "alt_text": "Descriptive alt text for accessibility"
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code in [200, 201]:
    print(f"Pin created successfully: {response.json()['id']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

Understanding Media Source Types

The Pinterest API for Pins supports multiple media source types for uploading content:

Retrieving Pins (GET /pins)

You can retrieve a single Pin or list all Pins owned by the authenticated user using the Pinterest API for Pins read endpoints. This is useful for syncing your CMS with your Pinterest presence.

Get a Single Pin

Java Example Implementation:

import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {
    public static void main(String[] args) throws IOException {
        URL url = new URL("https://api.pinterest.com/v5/pins/{pin_id}");
        HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
        httpConn.setRequestMethod("GET");

        httpConn.setRequestProperty("Authorization", "Bearer ");
        httpConn.setRequestProperty("Content-Type", "application/json");
        httpConn.setRequestProperty("Accept", "application/json");

        InputStream responseStream = httpConn.getResponseCode() / 100 == 2
                ? httpConn.getInputStream()
                : httpConn.getErrorStream();
        Scanner s = new Scanner(responseStream).useDelimiter("\\A");
        String response = s.hasNext() ? s.next() : "";
        System.out.println(response);
    }
}

List Multiple Pins

The GET /pins endpoint allows you to list Pins with powerful filtering options. You can filter by creative type or exclude repins to find only your organic content.

• pin_filter: exclude_native, exclude_repins, or has_been_promoted.
• page_size: Max 250 items per page (Default: 25).
• include_protected_pins: boolean to include Pins from protected boards.

Analyzing Performance with the Pinterest API for Pins

The Pinterest API for Pins provides robust analytics to measure the performance of your visual content. You can request both lifetime metrics and daily metrics for specific time ranges of up to 90 days.

Response data spans diverse metrics including Impressions, Outbound Clicks, Pin Clicks, and Saves. Note that for Pins created before 2023-03-20, lifetime metrics may be limited to Video and Idea Pins. For comprehensive guidance on interpreting these metrics, Pinterest Business Analytics provides detailed documentation on leveraging data to optimize your content strategy.

Available Metrics

Metric	Description
IMPRESSION	Number of times the Pin was shown on screen.
PIN_CLICK	Clicks on the Pin to view close-up.
OUTBOUND_CLICK	Clicks through to the destination URL.
SAVE	Number of saves (repins) by other users.
SAVE_RATE	Percentage of impressions that resulted in saves.
VIDEO_MRC_VIEW	Video views (MRC standard).
VIDEO_AVG_WATCH_TIME	Average watch time in milliseconds.

Updating and Maintaining Pins with the Pinterest API

Content on Pinterest often needs a refresh. The Pinterest API for Pins supports updating metadata through the PATCH method and removal via the DELETE method.

Update Pin (PATCH /pins/{pin_id})

You can update a Pin’s title, description, and link. For carousel Pins, you can also modify the slots data. This operations requires pins:write scope.

Delete Pin (DELETE /pins/{pin_id})

If a Pin is no longer relevant, you can delete it permanently. This returns a 204 status code upon success. Be careful, as this action cannot be undone.

Saving Existing Pins (POST /pins/{pin_id}/save)

Beyond creating original content, the Pinterest API for Pins allows you to save existing public Pins to your own boards. This is the API equivalent of the “Save” button on Pinterest’s web interface.

The request body only requires the board_id where you want to save the Pin, and optionally a board_section_id for more granular organization.

Pinterest API Rate Limits Explained

Understanding rate limits is crucial when working with the Pinterest API for Pins. Pinterest categorizes rate limits by operation type:

Category	Operations	Use Case
org_read	GET /pins, GET /pins/{id}	Reading Pin data and listings
org_write	POST /pins, PATCH, DELETE	Creating and modifying Pins
org_analytics	GET /pins/{id}/analytics	Retrieving performance metrics

When you exceed a rate limit, the API returns a 429 Too Many Requests response. Always implement exponential backoff in your application to handle these gracefully.

Comparison: Pinterest API vs Other Social APIs

Frequently Asked Questions About the Pinterest API for Pins

Automate Pinterest Strategy with Repostit

Managing a visual discovery engine like Pinterest requires consistency. Manually creating, pinning, and analyzing content via the Pinterest API for Pins can be complex and time-consuming. Repostit streamlines this workflow for you.

Conclusion

The Pinterest API for Pins offers granular control over your visual content strategy. By leveraging endpoints for creation, retrieval, and analysis, developers can build powerful tools that enhance content discovery. Whether you are building a custom integration or seeking a deeper understanding of the platform, mastering these endpoints is the key to unlocking Pinterest’s full potential.

As we’ve explored throughout this guide, the Pinterest Pins API provides comprehensive functionality for every stage of the Pin lifecycle. From creating visually stunning Pins with the POST endpoint, to analyzing performance metrics with the analytics endpoint, each feature is designed to help you maximize engagement on the platform.

Remember these key takeaways when working with the Pinterest API for Pins:

• Authentication: Always use OAuth 2.0 with the appropriate scopes (pins:read, pins:write) for secure API access
• Rate Limits: Monitor your org_read, org_write, and org_analytics quotas through response headers
• Image Optimization: Use the recommended 2:3 aspect ratio (1000×1500 pixels) for maximum visibility in Pinterest feeds
• Analytics: Leverage the analytics endpoint to track IMPRESSION, OUTBOUND_CLICK, and SAVE metrics for data-driven optimization
• Error Handling: Implement robust error handling for 429 (rate limit) and 401 (authentication) responses

The visual nature of Pinterest makes it uniquely valuable for brands, content creators, and marketers. With over 450 million monthly active users searching for inspiration, products, and ideas, programmatic Pin management through the API opens doors to massive audience reach that would be impossible to achieve manually.

For developers looking to streamline their Pinterest workflow without the complexity of direct API integration, tools like Repostit offer a user-friendly alternative that handles authentication, rate limiting, and cross-platform publishing automatically.