Pinterest API

Building with an AI assistant?

This page is the complete Pinterest API reference for Postproxy — every format, parameter, media limit, and example in one place. Click Copy page at the top to copy it as Markdown, then paste it into ChatGPT, Claude, Cursor, or any LLM and it’ll have everything it needs to write your integration.

Postproxy creates image and video Pins on a connected Pinterest account. Every Pin requires media and a destination board. Boards can also be created and deleted through the API.

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
Board management	Create and delete boards — see Board management
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)
alt_text	string	No	Alt text for image Pins (truncated to 500 characters) — see Alt text

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"

Board management

Create and delete boards on the connected Pinterest account. A new board shows up in placements right away, and its id is the board_id you publish to.

Every endpoint is scoped to one connected profile:

/api/profiles/:profile_id/pinterest/...

No extra connection or scope is needed: any Pinterest profile connected to Postproxy can use these endpoints.

Method	Endpoint	Description
POST	/api/profiles/:profile_id/pinterest/create_board	Create a board
DELETE	/api/profiles/:profile_id/pinterest/delete_board	Delete a board and every Pin on it

Create board

POST /api/profiles/:profile_id/pinterest/create_board

Parameter	Type	Required	Description
name	string	Yes	Board name. Must be unique among the account’s boards
description	string	No	Board description
privacy	string	No	PUBLIC (default) or PROTECTED

curl -X POST "https://api.postproxy.dev/api/profiles/prof_abc123/pinterest/create_board" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Summer Recipes",
       "description": "Light dinners for hot days",
       "privacy": "PUBLIC"
     }'

The response is the new placement, in the same shape as List placements:

{
  "id": "1022106146616799123",
  "name": "Summer Recipes",
  "avatar_url": null,
  "metadata": {}
}

Delete board

DELETE /api/profiles/:profile_id/pinterest/delete_board

Parameter	Type	Required	Description
board_id	string	Yes	Placement ID from placements

curl -X DELETE "https://api.postproxy.dev/api/profiles/prof_abc123/pinterest/delete_board?board_id=1022106146616799123" \
     -H "Authorization: Bearer YOUR_API_KEY"

{
  "deleted": true,
  "board_id": "1022106146616799123"
}

Caution

Deleting a board also deletes every Pin on it, on Pinterest. This cannot be undone. The board is removed from the profile’s placements.

Errors

Status	Meaning
400	Missing name or board_id, or an unknown privacy value
403	The connection lacks permission to manage boards
404	Profile not found, or board_id isn’t a placement of this profile
422	Profile is not a Pinterest profile, the connection needs re-authentication, or Pinterest rejected the request (e.g. duplicate board name)
429	Pinterest is rate-limiting; retry after the Retry-After header
502	Pinterest could not be reached

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

What you can’t do

Pinterest’s API doesn’t expose these features, so they aren’t available through Postproxy:

• Carousels or multi-image Pins — each Pin carries a single image or video.
• Idea Pins (the multi-page story format).
• Rich Pins, which depend on meta tags published on your own site.
• Shopping catalogs and product feeds.
• Editing a Pin after it’s been published.

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.