Pinterest API: Create a Pin
How to create and publish a Pin to a specific board via API.
By André LugTo create a Pinterest Pin via API, send POST /api/posts with the connected profile ID, a required board_id under post.options.pinterest, and exactly one image (JPEG or PNG up to 32 MB) or video in media. Add a stable Idempotency-Key — Pinterest itself does not deduplicate Pin creation — then read the targets array for the Pin ID and permalink.
Creating a Pin through the Pinterest API is a single POST request once a Pinterest account is connected. This page covers exactly that request: what fields it needs, what a board ID actually is, and what comes back once the Pin is live. For the full walkthrough — connecting the account, listing boards, and confirming delivery — see How to Post a Pin via API.
What does the create-Pin request look like?
POST /api/posts envelope for every platform. For Pinterest, pass the connected profile ID and put the Pinterest-specific fields under post.options.pinterest. A stable Idempotency-Key makes the request safe to retry for 72 hours if a network call times out — Pinterest itself does not deduplicate Pin creation, so retrying a request without one can create a duplicate Pin.curl -X POST https://postgate.studio/api/posts \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-pin-001" \
-d '{
"post": {
"body": "New arrivals just dropped.",
"options": {
"pinterest": { "board_id": "1099...", "title": "Launch story" }
}
},
"profiles": ["pro_pinterest123"],
"media": ["https://cdn.example.com/launch.jpg"]
}'Is a board ID required on every Pin?
GET /api/profiles/{id}/boards and let the user pick one; PostGate reads boards live and never stores them, so a renamed or newly created board shows up immediately. title is optional but recommended — without it Pinterest falls back to a generic title derived from the Pin description.How much media can a Pin carry?
media takes a single item. Images must be JPEG or PNG up to 32 MB; video follows the rules on the video Pin page. Pinterest’s own Pins Create API documents WEBP as an accepted format, but that only applies to the separate Idea Pin type — standard Pins reject it.How do you read the result?
targets array is what actually happened on Pinterest: delivery status, the Pinterest-assigned Pin ID, and the permalink once it publishes. Pinterest board names and Pin analytics are fetched live from PostGate, never cached as a stale snapshot, so a board rename or a Pin’s save count is always current when you ask for it.Frequently asked questions
Do I need a board ID to post a Pin via the API?
Yes. Pinterest has no concept of posting without a destination board — there is no equivalent to a plain profile feed. Fetch the account's boards from GET /api/profiles/{id}/boards and let the user pick one; PostGate reads boards live and never stores them, so a renamed or newly created board shows up immediately.
Can a Pinterest Pin have multiple images like a carousel?
No. Unlike Instagram or LinkedIn, Pinterest Pins do not support carousels through this API — the media array takes a single item: one image (JPEG or PNG up to 32 MB) or one video.
Does the Pinterest API accept WEBP images?
Not for standard Pins. Pinterest's own Pins Create API documents WEBP as an accepted format, but that only applies to the separate Idea Pin type — standard Pins reject it. Stick to JPEG or PNG, up to 32 MB.
What happens if I retry a Pin creation request that timed out?
Pinterest itself does not deduplicate Pin creation, so retrying a request without protection can create a duplicate Pin. A stable Idempotency-Key on the PostGate request makes it safe to retry for 72 hours — the retry maps onto the original request instead of creating a second Pin.
