Skip to content

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.

Image Pin request
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
}
Illustrative request
Example line 1

POST {{API_BASE_URL}}/v1/posts

Illustrative request
Example line 2

x-access-key: YOUR_API_KEY

Illustrative request
Example line 3

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.

POST /v1/posts field map
FieldLocationPurposeRequiredness / notes
contentRequest bodyPin description / content textShown in Image Pin example
platforms[].platformRequest bodyTarget platform; use pinterest for PinterestShown in Image Pin example
platforms[].accountIdRequest bodyConnected Pinterest account identifierShown in Image Pin example
platforms[].platformSpecificData.boardIdRequest bodyTarget board for Board TargetingEvery Pin must target a board
platforms[].platformSpecificData.titleRequest bodyPin titleShown in Image Pin example
platforms[].platformSpecificData.linkRequest bodyHTTPS destination URL for Link AttributionAttach an HTTPS destination URL
mediaItems[].typeRequest bodyMedia type; image in the worked exampleExactly one image or one video per Pin
mediaItems[].urlRequest bodyMedia URLShown in Image Pin example
publishNowRequest bodyImmediate publishing flagtrue in the Image Pin example
scheduledForRequest bodyFuture publication time for Scheduled PublishingUse with optional IANA timezone
successResponse bodyOverall request successtrue in the 202 example
statusResponse bodyPublishing statuspublished in the 202 example
postIdResponse bodyCreated post identifierShown in the 202 example
platforms[].platformPostUrlResponse bodyLive Pinterest Pin URLUse to confirm publication

Preserved from source Image Pin example and FAQ; requiredness beyond the example is not independently verified.

Pre-flight validation matrix
CheckPass conditionFailure action
Media countExactly one image or one videoRemove extra media items or add the missing single item
BoardboardId present in platformSpecificDataLook up the correct board and add boardId before sending
Destination linkHTTPS URL when a link is attachedReplace non-HTTPS links with an HTTPS destination URL
Image formatJPG, PNG, or WebPConvert the image to a supported format
Image size guidance1000 × 1500 pixels, 2:3 aspect ratio, up to 32 MBResize or recompress the image to the recommended dimensions and size
Timing modepublishNow for immediate publishing or scheduledFor for future publicationSet 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.

Image Pin response
202

{
  "success": true,
  "status": "published",
  "postId": "post_vwx234",
  "platforms": [
    {
      "platform": "pinterest",
      "success": true,
      "platformPostUrl": "https://www.pinterest.com/pin/98765/"
    }
  ]
}