Pinterest

Publish single-image, multi-image and video pins to a Pinterest board via the API v5. The platform id is pinterest. Pinterest is a URL-ingest platform: pins are created in a single call by handing Pinterest the public media URL(s). Pinterest has no comments API, so first-comment and thread containers are ignored.

A board and at least one image are required

Every pin needs a target board_id and at least one media item — there are no text-only pins. A request without board_id is rejected with a 400 before publishing, and a request with no image fails the same way.

Supported content

Single-image pin — one image.
Multi-image pin — 2–5 images.
Video pin — requires a pre-registered video_media_id plus a cover image.

Limits

Property	Value
Title	100 characters
Description	800 characters
Alt text	500 characters
Multi-image pin	2–5 images
Media	Public HTTPS images; video uses an async pipeline; at least one media item required
First comment	No (no comments API)
Token lifetime	Access token 30d · refresh token 1y

Configuration fields

Set under config.pinterest:

Field	Type	Required	Notes
`board_id`	string	Yes	The board the pin is created on. Use the MCP `list_pinterest_boards` tool to find ids.
`title`	string	No	Pin title, ≤100 characters. Falls back to the container content.
`link`	string	No	Destination URL the pin links to.
`alt_text`	string	No	Accessibility text, ≤500 characters. Falls back to the media’s alt text.
`video_media_id`	string	Video only	The `media_id` from the out-of-band `POST /v5/media` registration.
`cover_image_url`	string	Video only	Public HTTPS cover image for a video pin.

The container’s content becomes the pin description (≤800 characters).

Required scopes

Configure scopes on the BYOK network record. When none are set, PostFuze requests:

pins:read
pins:write
boards:read
boards:write
user_accounts:read

Create a post

A single-image pin on a specific board, with a title, link and alt text:

curl

curl https://api.postfuze.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": ["acct_pin_01"],
    "containers": [
      {
        "content": "A clean, minimal developer dashboard built with the PostFuze component library.",
        "media": [{ "id": "media_dashboard" }]
      }
    ],
    "config": {
      "pinterest": {
        "board_id": "987654321012345678",
        "title": "Developer Dashboard UI",
        "link": "https://postfuze.com/playground",
        "alt_text": "Screenshot of the PostFuze playground dashboard"
      }
    }
  }'

201 Created

{
	"id": "post_c700",
	"status": "queued",
	"default_config": {
		"pinterest": { "board_id": "987654321012345678", "title": "Developer Dashboard UI", "link": "https://postfuze.com/playground", "alt_text": "Screenshot of the PostFuze playground dashboard" }
	},
	"containers": [
		{ "id": "ctr_p1", "position": 0, "role": "main", "content": "A clean, minimal developer dashboard built with the PostFuze component library." }
	],
	"targets": [
		{ "id": "tgt_pin1", "social_account_id": "acct_pin_01", "platform": "pinterest", "status": "queued", "platform_post_id": null }
	]
}

If board_id is missing, the target fails fast with a 400 error rather than being queued. See Posts for how per-target errors surface in error_code / error_message.