Pinterest API Reference

Create Pins with images, video, and links on selected boards.

Quick reference

auth	OAuth 2.0
text Limit	100 (title) / 500 (description)
max Media	20 items
media Rule	At least one image or video is typical
max Video Duration	15 min
entity Selection	Pinterest Boards
first Comment	Not supported (Pinterest has no comment-creation API)

Content types

—Text-only

Not supported — media is typically required

✓Images

JPEG, PNG, WebP. Max 32 MB.

✓Video

MP4 only. Max 2 GB. Up to 15 minutes.

—GIF

Not supported

Media requirements

Constraints enforced by Pinterest's API. Requests that violate these limits will be rejected.

Constraint	Value
Max image size	`32 MB`
Max video size	`2 GB`
Image formats	`JPEG, PNG, WEBP`
Video formats	`MP4`
Max video duration	`15 min`
Image aspect ratio	`0.48:1 to 0.67:1`
Min image dimensions	`100x100 px`
Max media items	`20`
GIF support	`No`

Platform settings

Pass these fields inside platformSettings.pinterest in the request body.

Name	Type	Required	Description
`boardId`	`string`	Required	ID of the Pinterest Board to pin to. Get available boards via GET /api/v1/connect/pinterest/entities.
`title`	`string`	Optional	Pin title. Max 100 characters.
`link`	`string`	Optional	URL to associate with the Pin. Drives traffic to your site.

boardId

stringRequired

ID of the Pinterest Board to pin to. Get available boards via GET /api/v1/connect/pinterest/entities.

title

stringOptional

Pin title. Max 100 characters.

link

stringOptional

URL to associate with the Pin. Drives traffic to your site.

Code examples

Basic post

curl -X POST https://schedulala.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Beautiful home decor inspiration",
    "platforms": [
      { "platform": "pinterest", "accountId": "acc_pin" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://example.com/decor.jpg" }
    ],
    "platformSettings": {
      "pinterest": {
        "boardId": "board_abc123",
        "title": "Modern Living Room Ideas",
        "link": "https://example.com/blog/decor"
      }
    },
    "publishNow": true
  }'

Post with media

# Pin with a video
curl -X POST https://schedulala.com/api/v1/posts \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How to style your bookshelf",
    "platforms": [
      { "platform": "pinterest", "accountId": "acc_pin" }
    ],
    "mediaItems": [
      { "type": "video", "url": "https://example.com/tutorial.mp4" }
    ],
    "platformSettings": {
      "pinterest": {
        "boardId": "board_abc123",
        "title": "Bookshelf Styling Tutorial",
        "link": "https://example.com/tutorials"
      }
    },
    "publishNow": true
  }'

Quirks & gotchas

You must select a Board to pin to after connecting — boardId is required.

Image aspect ratio: 1:2.1 to 2:3 — tall/portrait images strongly preferred.

Image max: 32 MB. Video max: 2 GB.

Minimum image dimensions: 100x100 px.

GIFs are not supported.

The link field drives traffic — always include it for marketing pins.

Posts API — Create and schedule posts across all platforms Media API — Platform-specific media constraints and upload limits Connecting Accounts — OAuth, App Password, and Bot Token flows All Platforms — Compatibility matrix and overview of all 12 platforms