Pinterest Upload API

This section details how to upload images, carousels (up to 5 images), and videos (Pins) to Pinterest using the API.

Base URL

https://api.multi-upload-tool.com/api/v1

Authentication

All requests require an API Token in the header: x-api-key: YOUR_API_TOKEN

1. Get User Boards (Required)

Before uploading a Pin, you must obtain a valid board_id from the user’s Pinterest account.

Endpoint

GET /pinterest/boards

Query Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	The ID of the connected Pinterest account (from `/accounts`).

Example Request


curl -X GET "https://api.multi-upload-tool.com/api/v1/pinterest/boards?accountId=123" \
  -H "x-api-key: YOUR_API_TOKEN"

Example Response


{
  "success": true,
  "data": [
    {
      "id": "123456789",
      "name": "My Board",
      "description": "Board description",
      "privacy": "PUBLIC"
    },
    {
      "id": "987654321",
      "name": "Another Board",
      "privacy": "SECRET"
    }
  ]
}

2. Upload Pin

Upload a single image or video file to a Pinterest Board.

Endpoint

POST /upload

Content-Type

multipart/form-data

Parameters

Query Parameters

Parameter	Type	Required	Description
`async`	string	No	Default `"true"`.

Body Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	The ID of the connected Pinterest account.
`pinterest_board_id`	string	Yes	The ID of the Pinterest Board.
`photo`	File or File[]	No	The image to upload (JPG, PNG). Required if `video` is not provided. Send the field more than once (or as an array, up to 5) for a carousel Pin — see the Upload Carousel Pin section below.
`video`	File	No	The video to upload (MP4). Required if `photo` is not provided.
`title`	string	No	The title of the Pin (max 100 chars). Defaults to `"Untitled"` if omitted.
`description`	string	No	The description of the Pin (max 500 chars).
`link`	string	No	Destination URL for the Pin.
`alt_text`	string	No	Alt text for the image.

Example Request (Image)


curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "accountId=123" \
  -F "pinterest_board_id=123456789" \
  -F "photo=@/path/to/image.jpg" \
  -F "title=My Cool Pin" \
  -F "description=Check this out!" \
  -F "link=https://example.com"

Example Request (Video)


curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "accountId=123" \
  -F "pinterest_board_id=123456789" \
  -F "video=@/path/to/video.mp4" \
  -F "title=My Video Pin" \
  -F "description=Watch this video!" \
  -F "link=https://example.com"

Example Response


{
  "success": true,
  "message": "Upload queued successfully",
  "data": {
    "uploadId": 456,
    "status": "pending",
    "scheduledFor": null
  }
}

3. Upload Carousel Pin

Create a carousel Pin (up to 5 images) by sending the photo field multiple times. Viewers swipe through the images on Pinterest.

Endpoint

POST /upload

Content-Type

multipart/form-data

Body Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	The ID of the connected Pinterest account.
`pinterest_board_id`	string	Yes	The ID of the Pinterest Board.
`photo`	File[]	Yes	Two to 5 image files. Repeat the `photo` field once per image.
`title`	string	No	The title of the Pin (max 100 chars).
`description`	string	No	The description of the Pin (max 500 chars).
`link`	string	No	Destination URL for the Pin.

Example Request


curl -X POST https://api.multi-upload-tool.com/api/v1/upload \
  -H "x-api-key: YOUR_API_TOKEN" \
  -F "accountId=123" \
  -F "pinterest_board_id=123456789" \
  -F "photo=@/path/to/image1.jpg" \
  -F "photo=@/path/to/image2.jpg" \
  -F "photo=@/path/to/image3.jpg" \
  -F "title=My Carousel Pin" \
  -F "description=Swipe through!" \
  -F "link=https://example.com"

Notes

A carousel Pin accepts 2 to 5 images. A single photo is published as a normal image Pin.
Video carousels are not supported — video always creates a single video Pin.

Validation & Limits

The following constraints are enforced by our API for all Pinterest uploads:

Constraint	Limit	Notes
Title	100 characters	Required for carousels. Recommended by Pinterest; enforced by our API.
Description	500 characters	Optional. Enforced by our API.
Destination Link	2,048 characters	Optional. Enforced by our API.
Alt Text	500 characters	Optional. Enforced by our API.
Image File Size	20 MB per file	Max file size for JPG, PNG images. Enforced by our API.
Video File Size	2 GB per file	Max file size for MP4 videos. Enforced by our API.
Carousel Images	2–5 images	Single images use `photo` once; carousels send 2–5 files. Enforced by our API.
Board Privacy	`PUBLIC` or `SECRET`	Set on the Pinterest side; our API mirrors the setting.
Video Pin Cover Time	Integer (milliseconds)	Optional. If not provided, defaults to 0 (start of video). Recommended by Pinterest.

Source: Pinterest API v5 Pins Create Documentation