Pinterest Posting API
The Pinterest Posting API gives developers and operators a single route for creating and scheduling Pins, without taking on Pinterest integration upkeep.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "pinterest",
"accountId": "pin_111",
"platformSpecificData": {
"boardId": "1143210755351402924",
"title": "10 Design Tips",
"link": "https://example.com/design-tips"
}
}
],
"mediaItems": [
{
"type": "image",
"url": "https://cdn.example.com/pin-image.jpg"
}
],
"publishNow": true
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
You can aim a Pin at a chosen board, add a clickable destination, and verify delivery from the response.
Add Pinterest publishing without maintaining Pinterest's API integration yourself
This page covers adding Pinterest to a product, automation, agency workflow, or AI system while avoiding ongoing Pinterest integration upkeep. A practical rollout follows three stages: obtain an API key, build against the endpoint, and expose Pinterest next to other major platforms through one interface. After a single connection, publishing, scheduling, and data reads share the same API rather than separate per-platform integrations.
Requests and responses vary by format, yet the route stays constant; only format-specific fields change. The Image Pin request and response examples appear under their human-readable titles in the code examples section. Treat that example as your baseline and consult the field map before sending anything.
Everything you need for Pinterest publishing
Pin Creation covers making Pins from images, titles, and descriptions via the endpoint. Board Targeting directs a Pin to a named board through boardId inside platformSpecificData. Link Attribution adds an HTTPS destination so clicks can return to your site or product. Image Optimization calls for JPG, PNG, or WebP files sized according to documented guidance. Scheduled Publishing defers delivery to a later moment. Cross-Post to Other Platforms sends one visual asset to Pinterest, Instagram, and Facebook together in a single request.
Run a local checklist before calling the endpoint: exactly one media item, type image or video, boardId present, any link using HTTPS, image dimensions and file size within guidance, and a clear choice between immediate publishNow and scheduledFor. Correct any failed check in your payload first, instead of sending a request that cannot meet the Pin rules.
Scheduling, editing, and confirming publication
Immediate delivery uses publishNow set to true. For Scheduled Publishing, supply scheduledFor plus an optional IANA timezone; the Pin queues and goes out at that time, retaining its board and other Pinterest settings. Until delivery occurs, content, media, platform options, and timing stay editable, including title, visual, board, link, and publish time.
Confirmation comes from the response: read status and platformPostUrl. A published result carries the live Pin address for storage or display. Anything other than published should not be treated as live; inspect the returned fields and retry or reschedule as indicated.
Direct Pinterest API vs unified endpoint
A direct Pinterest build leaves authentication, board discovery and identifiers, media rules, destination links, Pin creation, and keeping pace with API changes to your team. A unified endpoint hides that work behind /v1/posts, shared with other supported networks. Pick direct only when native Pinterest control matters enough to justify that upkeep. Pick unified when shipping Pin Creation, Board Targeting, Link Attribution, and Scheduled Publishing quickly matters more.
Need more than publishing? Pinterest scheduling queues Pins and lets you set date, time, and timezone. Pinterest analytics feeds performance data into a product, dashboard, or report. For stack fit: developers can use typed SDKs and REST, no-code teams can trigger publishing from familiar tools, and AI agents with MCP can publish and schedule through the same API. The same pattern also reaches other supported platforms, including Instagram and Facebook for shared visual content.
| Field | Location | Purpose | Requiredness / notes |
|---|---|---|---|
| content | Request body | Pin description / content text | Shown in Image Pin example |
| platforms[].platform | Request body | Target platform; use pinterest for Pinterest | Shown in Image Pin example |
| platforms[].accountId | Request body | Connected Pinterest account identifier | Shown in Image Pin example |
| platforms[].platformSpecificData.boardId | Request body | Target board for Board Targeting | Every Pin must target a board |
| platforms[].platformSpecificData.title | Request body | Pin title | Shown in Image Pin example |
| platforms[].platformSpecificData.link | Request body | HTTPS destination URL for Link Attribution | Attach an HTTPS destination URL |
| mediaItems[].type | Request body | Media type; image in the worked example | Exactly one image or one video per Pin |
| mediaItems[].url | Request body | Media URL | Shown in Image Pin example |
| publishNow | Request body | Immediate publishing flag | true in the Image Pin example |
| scheduledFor | Request body | Future publication time for Scheduled Publishing | Use with optional IANA timezone |
| success | Response body | Overall request success | true in the 202 example |
| status | Response body | Publishing status | published in the 202 example |
| postId | Response body | Created post identifier | Shown in the 202 example |
| platforms[].platformPostUrl | Response body | Live Pinterest Pin URL | Use to confirm publication |
Preserved from source Image Pin example and FAQ; requiredness beyond the example is not independently verified.
| Check | Pass condition | Failure action |
|---|---|---|
| Media count | Exactly one image or one video | Remove extra media items or add the missing single item |
| Board | boardId present in platformSpecificData | Look up the correct board and add boardId before sending |
| Destination link | HTTPS URL when a link is attached | Replace non-HTTPS links with an HTTPS destination URL |
| Image format | JPG, PNG, or WebP | Convert the image to a supported format |
| Image size guidance | 1000 × 1500 pixels, 2:3 aspect ratio, up to 32 MB | Resize or recompress the image to the recommended dimensions and size |
| Timing mode | publishNow for immediate publishing or scheduledFor for future publication | Set one timing mode intentionally and add an IANA timezone when scheduling |
Derived only from source constraints; no additional Pinterest rules invented.
Frequently asked questions
What can I publish with the Pinterest Posting API?
Each Pin carries a single visual asset: either one image or one video. A board destination is mandatory. Optional details include a title, description, destination link, alt text, dominant color, and, for video, a cover image.
Why use a unified endpoint instead of the Pinterest API directly?
Going direct means your team owns authentication, discovering boards and their identifiers, checking media rules, wiring destination links, creating Pins, and keeping up with Pinterest API changes. A unified endpoint places that work behind /v1/posts, the same route used for other supported networks.
Do I need my own Pinterest developer app?
No separate developer app is needed for this workflow. Pinterest connection happens through the OAuth flow tied to the supported publishing setup, with the underlying authentication and integration handled there.
What image size should I use for Pinterest?
Aim for 1000 × 1500 pixels (2:3). Keep the file at or below 32 MB.
Can I schedule Pinterest Pins?
Yes. Send scheduledFor to /v1/posts and, if needed, an IANA timezone. The Pin waits in queue until that moment, keeping the chosen board and other Pinterest settings intact.
Can I edit or reschedule a Pinterest Pin before it publishes?
Yes, as long as delivery has not happened yet. Content, media, platform options, and timing remain editable, so title, visual, board, link, and publish time can all be revised beforehand.
How do I know whether my Pinterest Pin is actually published?
Check the returned status together with platformPostUrl. When status shows published, that field holds the live Pin address you can save or display.
202
{
"success": true,
"status": "published",
"postId": "post_vwx234",
"platforms": [
{
"platform": "pinterest",
"success": true,
"platformPostUrl": "https://www.pinterest.com/pin/98765/"
}
]
}