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.

Profiles and profile groups

Every post targets one or more profiles. A profile is one connected account — for Pinterest, a Pinterest account (each post also needs a destination board, selected via placements). Reference one in a request by its id (the prof_abc123 in the examples below) or by the platform name "pinterest", which selects the group’s Pinterest profile (a group holds at most one profile per platform). List what’s connected with GET /api/profiles.

Profiles live in profile groups — containers that organize the accounts for one brand, client, or project. List groups with GET /api/profile_groups, and connect a new Pinterest profile with the Initialize Connection endpoint.

Example: get profiles and profile groups

List the profiles you can post to — GET /api/profiles:

curl -X GET "https://api.postproxy.dev/api/profiles" \
     -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "prof_abc123",
      "name": "My Company",
      "platform": "pinterest",
      "status": "active",
      "profile_group_id": "grp_xyz789",
      "expires_at": null,
      "post_count": 64,
      "avatar_url": "https://cdn.postproxy.dev/uploads/avatar_prof_abc123.jpg"
    }
  ]
}

List your profile groups — GET /api/profile_groups:

curl -X GET "https://api.postproxy.dev/api/profile_groups" \
     -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    { "id": "grp_xyz789", "name": "Main Brand", "profiles_count": 5 },
    { "id": "grp_def456", "name": "Client Project", "profiles_count": 3 }
  ]
}

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.

Stats

Postproxy records periodic stat snapshots you can pull as a timeseries; field names pass through from Pinterest unchanged.

Profile stats

Account-level metrics, refreshed roughly every 23 hours via the Profile stats endpoint (GET /api/profiles/:id/stats).

Fields: follower_count, following_count, pin_count, board_count, monthly_views, analytics_30d (nested 30-day rollup)

# Fetch the profile stats timeseries
curl "https://api.postproxy.dev/api/profiles/prof_abc123/stats" \
     -H "Authorization: Bearer YOUR_API_KEY"

Post stats

Per-Pin engagement, captured after publish via the Post stats endpoint (GET /api/posts/stats).

Fields: impressions, likes, comments, saved, outbound_clicks

# Fetch post stats
curl "https://api.postproxy.dev/api/posts/stats?post_ids=post_abc123&profiles=pinterest" \
     -H "Authorization: Bearer YOUR_API_KEY"

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.