Skip to Content
API ReferenceUpload MediaPinterest

Pinterest Upload API

This section details how to upload 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

ParameterTypeRequiredDescription
accountIdstringYesThe 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

ParameterTypeRequiredDescription
asyncbooleanNoDefault true.

Body Parameters

ParameterTypeRequiredDescription
accountIdstringYesThe ID of the connected Pinterest account.
pinterest_board_idstringYesThe ID of the Pinterest Board.
photoFileNoThe image to upload (JPG, PNG). Required if video is not provided.
videoFileNoThe video to upload (MP4). Required if photo is not provided.
titlestringYesThe title of the Pin (max 100 chars).
descriptionstringNoThe description of the Pin (max 500 chars).
linkstringNoDestination URL for the Pin.
alt_textstringNoAlt text for the image.
scheduledDatestringNoISO 8601 date string to schedule the post (e.g., 2025-12-25T10:00:00Z).

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
  }
}

Scheduled post: If scheduledDate is provided, status will be "scheduled" and scheduledFor will contain the ISO date.

InstagramBluesky