Docs/API Reference/Pinterest

Pinterest API

Use the Crosspostify API to create image, multi-image and video Pins on Pinterest — with title, description, destination link and board targeting.

Post Types

Image · Multi-image (up to 5) · Video Pin

Board Targeting

Required per Pin

Title

Optional (max 90)

Unique Endpoint

/pinterest-boards

Pinterest is a visual discovery platform where content lives as Pins organized into Boards. The Crosspostify Pinterest API integration lets you programmatically create image, multi-image and video Pins on the boards of your account — with title, description, destination link and board targeting.

Pinterest is unique among Crosspostify-supported platforms in that every Pin must be assigned to a specific board. Use the GET /pinterest-boards/{accountId} endpoint to fetch your boards and their IDs before creating Pins.

This page covers everything specific to Pinterest when using the Crosspostify API. For general authentication, rate limits, and error handling, see the full API Reference.

Pinterest-Specific Parameters

Pinterest has one exclusive parameter — boardId — which is required for every Pin. This is the only platform on Crosspostify that requires content to be assigned to a specific destination before posting. Pinterest also uses link as the Pin's destination URL.

accountId✓ AppliesRequired. The id of the connected Pinterest account from GET /social-accounts (Crosspostify's account ID, not the Pinterest user ID).

title✓ AppliesOptional. The Pin title. Max 90 characters (longer titles are cut, no error).

caption✓ AppliesOptional. The Pin description. Helps with Pinterest search. Max 800 characters (longer text is cut, no error).

link✓ AppliesOptional. Destination URL the Pin opens. Max 2048 characters (longer is cut).

boardId✓ AppliesPinterest exclusive. Required. The board to save this Pin to; fetch board IDs from GET /pinterest-boards/{accountId}. Not checked against your boards when you send the request; a wrong id makes the post fail at publish time.

is_aigc✗ IgnoredTikTok, Instagram and Facebook only — ignored for Pinterest.

thumbnailTimestamp✗ IgnoredTikTok only — ignored for Pinterest (video Pin covers use a fixed early frame).

facebookFirstComment✗ IgnoredFacebook only — ignored for Pinterest.

textFormatPresetId✗ IgnoredFacebook only — ignored for Pinterest.

tiktok / instagram / facebook✗ IgnoredSettings for those platforms — ignored for Pinterest.

boardId is required for every Pin

Unlike other platforms where posts go to a general feed, every Pinterest Pin must be saved to a specific board. Always fetch your board IDs first using GET /pinterest-boards/{accountId} and store them for reuse. A Pinterest entry without boardId rejects the whole request with 400 {"accountId": "<id>", "error": "Missing boardId", "message": "boardId is required for Pinterest posts"}.

Supported Endpoints

Pinterest supports image, multi-image and video Pins, plus a dedicated endpoint for fetching your boards:

No text-only Pins

Every Pin needs an image or a video; /post/text only accepts Facebook and Threads. Multi-image Pins (up to 5 images) are created with POST /post/images.

POST/post/imageImage Pin

Create an image Pin on a Pinterest board. Image Pins are the core Pinterest format — Pinterest recommends vertical images (2:3 ratio) for the feed.

Image Pin Notes

Vertical images (2:3 ratio, 1000×1500px) take up more feed space (Pinterest's recommendation)
title is shown prominently on the Pin detail page — make it keyword-rich
caption maps to the Pin description — include relevant keywords for Pinterest SEO
link is the destination URL the Pin opens
boardId is required — fetch your board IDs from GET /pinterest-boards/{accountId}
Upload your image first via POST /media and pass the returned id as mediaId. The image is sent to Pinterest as uploaded (no resizing or cropping)
scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdstringrequired

The id of the uploaded image file, returned by POST /media.

scheduledDatestringoptional

Optional. ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets such as +01:00 are converted to UTC; no offset = UTC). Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects, one per Pin. The same accountId may appear several times (e.g. with different boardIds).

posts[].accountIdstringrequired

The id of the connected Pinterest account from GET /social-accounts (Crosspostify's account ID, not the Pinterest user ID).

posts[].boardIdstringrequired

The board to save this Pin to. Retrieve board IDs from GET /pinterest-boards/{accountId}. Not checked when you send the request; a wrong id makes the post fail at publish time.

posts[].titlestringoptional

The Pin title. Shown on the Pin detail page. Keyword-rich titles help Pinterest search. Max 90 characters (longer titles are cut, no error).

posts[].captionstringoptional

Optional (default empty). The Pin description. Max 800 characters (longer text is cut, no error).

posts[].linkstringoptional

Destination URL of the Pin. Max 2048 characters (longer is cut).

Response

202 Accepted. status is SCHEDULED because the request has a scheduledDate (without one it is QUEUED). Publishing happens afterwards: check the result with GET /posts?id=<id> (PROCESSING, then PUBLISHED with postUrl https://pinterest.com/pin/<id>, or FAILED with error).

{ "mediaId": "img_12345", "message": "Image post created successfully", "posts": [ { "id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d", "platform": "pinterest", "socialAccountId": "acc_pinterest_789", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_pinterest_789",
        "title": "10 Minimalist Living Room Ideas",
        "caption": "Transform your living space with these clean, modern design ideas. Perfect for small apartments and open-plan homes.",
        "boardId": "549755885175",
        "link": "https://example.com/living-room-ideas"
      }
    ]
  }'

POST/post/imagesMulti-image Pin

Create one Pin with several images (up to 5) on a Pinterest board. A single image id gives a normal image Pin.

Multi-image Pin Notes

1 to 5 image ids, in the order given in mediaIds
All images must have the same aspect ratio (tolerance 0.01). This is checked for the whole request whenever a Pinterest account is in it
Use each image id only once; duplicate ids are rejected when a Pinterest account is in the request
title, caption and link are applied to every image of the Pin
boardId is required — same as image Pins
scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdsarrayrequired

Ordered array of 1 to 5 image ids from POST /media, all with the same aspect ratio.

scheduledDatestringoptional

Optional. ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets such as +01:00 are converted to UTC; no offset = UTC). Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects, one per Pin. The same accountId may appear several times (e.g. with different boardIds).

posts[].accountIdstringrequired

The id of the connected Pinterest account from GET /social-accounts (Crosspostify's account ID, not the Pinterest user ID).

posts[].boardIdstringrequired

The board to save this Pin to. Retrieve board IDs from GET /pinterest-boards/{accountId}.

posts[].titlestringoptional

The Pin title, used for every image. Max 90 characters (longer titles are cut, no error).

posts[].captionstringoptional

Optional (default empty). The Pin description, used for every image. Max 800 characters (longer text is cut, no error).

posts[].linkstringoptional

Destination URL, used for every image. Max 2048 characters (longer is cut).

Validation Errors

These errors reject the whole request with 400; nothing is posted.

// More than 5 images { "affected_accounts": ["acc_pinterest_789"], "error": "Too many images", "max_images": 5, "message": "Pinterest supports a maximum of 5 images per post", "platform": "pinterest" } // Images with different aspect ratios (details names the first id) { "details": "Media ID img_001 is invalid or unauthorized", "error": "Invalid media ID", "message": "Pinterest requires all images in a multiple image post to have the same aspect ratio" } // The same image id sent twice { "details": "Media ID img_001 is invalid or unauthorized", "error": "Invalid media ID", "message": "One or more media items not found" }

Response

{ "mediaIds": ["img_001", "img_002", "img_003"], "message": "Multiple images post created successfully", "posts": [ { "id": "6a1f3e8d-2c4b-4d7a-9e5f-8b0c1d2e3f4a", "platform": "pinterest", "socialAccountId": "acc_pinterest_789", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/images" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaIds": ["img_001", "img_002", "img_003"],
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_pinterest_789",
        "title": "3 Small Living Room Layouts",
        "caption": "Three layouts that make a small living room feel bigger. Save this Pin for your next makeover.",
        "boardId": "549755885175",
        "link": "https://example.com/small-living-rooms"
      }
    ]
  }'

POST/post/videoVideo Pin

Create a video Pin on a Pinterest board. Video Pins autoplay silently in the feed and are excellent for tutorials, recipes, and product demos.

Video Pin Notes

Video Pins autoplay silently in the feed — design for no-sound viewing
Vertical video (2:3 or 9:16) takes up more feed space and performs better
boardId is required — same as image Pins
The cover is a fixed frame at the very start of the video (thumbnailTimestamp is ignored for Pinterest), so open with a strong visual
Upload your video first via POST /media and pass the returned id as mediaId
While Pinterest processes the video, GET /posts shows PROCESSING. If processing takes longer than 10 minutes, the post fails with "Video processing did not complete in time (10 minutes)"
scheduledDate accepts any ISO 8601 date-time. Z or an offset (e.g. +01:00) is converted to UTC; no offset means UTC. It must be in the future.

Request Body

mediaIdstringrequired

The id of the uploaded video file, returned by POST /media.

scheduledDatestringoptional

Optional. ISO 8601 date-time in the future, e.g. 2030-01-15T10:00:00Z (offsets such as +01:00 are converted to UTC; no offset = UTC). Omit it (or send null) to post immediately.

postsarrayrequired

Array of post objects, one per Pin. The same accountId may appear several times (e.g. with different boardIds).

posts[].accountIdstringrequired

The id of the connected Pinterest account from GET /social-accounts (Crosspostify's account ID, not the Pinterest user ID).

posts[].boardIdstringrequired

The board to save this Pin to. Retrieve board IDs from GET /pinterest-boards/{accountId}.

posts[].titlestringoptional

The Pin title. Shown on the Pin detail page. Max 90 characters (longer titles are cut, no error).

posts[].captionstringoptional

Optional (default empty). The Pin description. Max 800 characters (longer text is cut, no error).

posts[].linkstringoptional

Destination URL of the Pin. Max 2048 characters (longer is cut).

Response

{ "mediaId": "vid_12345", "message": "Video post created successfully", "posts": [ { "id": "8c2f0b6e-1d4a-4c1e-9a57-3f2d6b1e0a99", "platform": "pinterest", "socialAccountId": "acc_pinterest_789", "status": "SCHEDULED" } ] }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "scheduledDate": "2030-01-15T10:00:00Z",
    "posts": [
      {
        "accountId": "acc_pinterest_789",
        "title": "Easy 15-Minute Pasta Recipe",
        "caption": "This creamy garlic pasta comes together in just 15 minutes with pantry staples. Save this Pin for your next weeknight dinner!",
        "boardId": "549755885176"
      }
    ]
  }'

GET/pinterest-boards/{accountId}

Fetch the boards of a connected Pinterest account. Use the returned id values as boardId when creating Pins. This is a Pinterest-exclusive endpoint not available for other platforms.

Fetching Boards

Replace {accountId} in the URL with the id of the Pinterest account from GET /social-accounts
Returns up to 200 boards (first page only; there is no paging)
Secret boards are not returned with Crosspostify's current Pinterest permissions
privacy is Pinterest's own value, e.g. "PUBLIC". url and description may be empty strings
Board IDs are stable (renaming a board does not change its id) — safe to cache and reuse across Pin creation requests

Path Parameters

accountIdstringrequired

The id of the connected Pinterest account from GET /social-accounts (Crosspostify's account ID, not the Pinterest user ID).

Response

{ "boards": [ { "description": "Modern and minimalist living room ideas", "id": "549755885175", "name": "Living Room Inspiration", "privacy": "PUBLIC", "url": "" }, { "description": "Meals ready in 30 minutes or less", "id": "549755885176", "name": "Quick Weeknight Recipes", "privacy": "PUBLIC", "url": "" } ], "success": true, "total": 2 }

Errors

// 404: unknown id, not your account, or not a Pinterest account { "error": "Pinterest account not found" } // 500: Pinterest did not answer (after 3 attempts) { "error": "Failed to fetch boards", "message": "<error from Pinterest>" }

Code Example

curl -X GET "https://v1.api.crosspostify.com/pinterest-boards/acc_pinterest_789" \
  -H "X-API-Key: your_api_key_here"

Boards

Pinterest Boards are the organizational unit of Pinterest. Every Pin must belong to a board. Boards can be public or secret, and are managed directly in Pinterest — not via the Crosspostify API.

Public Boards

Visible to all Pinterest users
Pins appear in Pinterest search and recommendations
Best for content you want to be discovered
Returned in GET /pinterest-boards with privacy: "PUBLIC"

Secret Boards

Only visible to you and invited collaborators
Pins do not appear in search or recommendations
Not available through the API with the current Pinterest permissions
Not listed by GET /pinterest-boards

Pin to multiple boards in one call

You can include multiple entries in the posts array — each with a different boardId — to save the same Pin to multiple boards simultaneously in a single API call. Each entry counts toward that account's limits of 30 posts per minute and 150 per UTC day.

Content Guidelines

Pinterest is a visual search engine as much as a social platform. Optimizing your Pins for search and visual appeal is key to long-term discoverability.

Image Pin Requirements

Format: JPG, PNG or WEBP (converted to JPEG on upload)
Recommended ratio: 2:3 (1000×1500px)
Square (1:1) and 4:5 also supported
Max file size: 20 MB via Crosspostify
Multi-image Pins: up to 5 images, all with the same aspect ratio
Vertical images get more feed real estate

Video Pin Requirements

Format: MP4 or MOV, max 100 MB (Crosspostify upload limit)
Recommended ratio: 2:3 or 9:16 (vertical)
Square (1:1) also supported
Duration: 4 seconds to 15 minutes (Pinterest's limits; not checked by Crosspostify)
Videos autoplay silently — design for mute

Pinterest SEO Tips

Title: max 90 chars via Crosspostify — lead with keywords
Description: max 800 chars — use natural language
Pinterest is a search engine — keywords matter
Pins have a long shelf life (months to years)
Board name and description also affect SEO
Consistent pinning beats sporadic bulk posting

Scheduling

Any future time works: no minimum lead time
ISO 8601 with Z or an offset (e.g. +01:00); no offset = UTC
Omit scheduledDate to post immediately
Published within about a minute of the scheduled time
No maximum scheduling window