Pinterest API Reference

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

Quick reference

authOAuth 2.0
text Limit100 (title) / 500 (description)
max Media20 items
media RuleAt least one image or video is typical
max Video Duration15 min
entity SelectionPinterest Boards
first CommentNot 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.

ConstraintValue
Max image size32 MB
Max video size2 GB
Image formatsJPEG, PNG, WEBP
Video formatsMP4
Max video duration15 min
Image aspect ratio0.48:1 to 0.67:1
Min image dimensions100x100 px
Max media items20
GIF supportNo

Platform settings

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

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 (longer is rejected with 400). Defaults to the content.

description
stringOptional

Pin description. Max 500 characters (longer is rejected with 400). Defaults to the content.

link
stringOptional

Absolute http(s) URL to associate with the Pin. Drives traffic to your site. Anything else is rejected with 400.

title, description and link are validated when the post is created and echoed back under platformSettings.pinterest on GET /api/v1/posts/:id.

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.

Related

Posts API — Create and schedule posts across all platformsMedia API — Platform-specific media constraints and upload limitsConnecting Accounts — OAuth, App Password, and Bot Token flowsAll Platforms — Compatibility matrix and overview of all 12 platforms