Pinterest API

Postproxy creates image and video Pins on a connected Pinterest account. Every Pin requires media and a destination board.

Every request below uses the base URL https://api.postproxy.dev and an Authorization: Bearer YOUR_API_KEY header. Replace YOUR_API_KEY and the example IDs with your own.

At a glance

Platform ID	pinterest
Formats	pin
Character limit	500 (description); title 100
Media	Required
Placements	Boards — selected with board_id
Comments	No
Direct messages	No
Post chains	No

Publishing

Parameters

Parameter	Type	Required	Description
board_id	string	Yes	Board to pin to — fetch from placements
title	string	No	Pin title (max 100 characters)
destination_link	string	No	Destination URL (max 2,048 characters)
cover_url / cover_file	string / file	No	Cover image (video Pins only)
thumb_offset	integer	No	Thumbnail offset in seconds (video Pins only)

Media	Max size	Formats	Count	Duration
Image	32 MB	jpg, gif, png, webp	1	—
Video	2 GB	mp4, mov	1	4 s – 15 min

• Media is required. The post body becomes the Pin description.

# Image Pin with a destination link
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "10 Tips for Better Photography" },
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/image.jpg"],
       "platforms": {
         "pinterest": {
           "title": "10 Tips for Better Photography",
           "board_id": "987654321",
           "destination_link": "https://example.com/blog/photography-tips"
         }
       }
     }'

# Video Pin with a cover image
curl -X POST "https://api.postproxy.dev/api/posts" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "post": { "body": "Watch: editing a photo in 30 seconds" },
       "profiles": ["prof_abc123"],
       "media": ["https://example.com/video.mp4"],
       "platforms": {
         "pinterest": {
           "title": "30-Second Edit",
           "board_id": "987654321",
           "cover_url": "https://example.com/cover.jpg",
           "destination_link": "https://example.com/tutorials"
         }
       }
     }'

Placements

A Pinterest profile pins to one of its boards. List them with the placements endpoint — each board’s id is the board_id you pass when creating a Pin. board_id is always required.

# List boards (placements)
curl "https://api.postproxy.dev/api/profiles/prof_abc123/placements" \
     -H "Authorization: Bearer YOUR_API_KEY"

Comments

Not supported through the API.

Direct messages

Not supported.

Webhooks

Subscribe with the Webhooks API:

curl -X POST "https://api.postproxy.dev/api/webhooks" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "url": "https://example.com/webhooks/postproxy",
       "events": ["platform_post.published", "platform_post.failed", "platform_post.insights"]
     }'

Events relevant to Pinterest:

Event	When
post.processed	A post is ready to publish
platform_post.published	A post was published to the platform
platform_post.failed	A post failed to publish (retries exhausted)
platform_post.failed_waiting_for_retry	A publish attempt failed; will retry
platform_post.insights	New analytics snapshot
profile.connected / .disconnected	Connection state changed
profile.stats	New profile stats snapshot
media.failed	A media attachment failed to process

Notes

• board_id and media are both required on every Pin.
• cover_url / cover_file and thumb_offset apply to video Pins only.
• Add a destination_link to drive traffic from the Pin to your site.