Skip to content
postpeg
Start trial

Pinterest API

Create and schedule Pinterest pins through one API

postpeg creates pins through Pinterest’s official API, from the same endpoint that publishes to nine other networks. Send one image or video with the pin’s text, and put the board, title and destination link in platform_options.pinterest.

Start 7-day trialRead the docs
  • Publish
  • Schedule
  • Analytics
  • Pinterest66/500
    image

    Five-minute cold brew at home: coarse grind, cold water, patience.

    Ready

The example below, checked against Pinterest’s rules

It suits products with a steady stream of visual content, like shops, recipe sites and portfolios, that want pins to go out on a schedule next to their other channels.

What you can do on Pinterest

  • Publish. Publish to Pinterest now with POST /v1/posts, alone or in the same request as any of the other networks. More on the Posting API.
  • Schedule. Schedule up to a year ahead with scheduled_at, and cancel with DELETE /v1/posts/{id} any time before it goes out. More on the Scheduling API.
  • Analytics. Read impressions, likes, shares and more per post with GET /v1/posts/{id}/analytics, and follower growth with GET /v1/accounts/{id}/analytics. More on the Analytics API.

Not available on Pinterest: comments and direct messages. The coverage table shows what each network supports.

Pinterest’s rules, checked before sending

A Pinterest post can have up to 500 characters, counted as people see them (an emoji is one). Media is required: 1 image or 1 video. It also needs platform_options.pinterest.board_id. postpeg runs these checks on every request, so a post that won’t fit Pinterest is refused with a 400 before anything is published, on any network.

Pinterest limits as postpeg checks them
Max text500 characters
MediaRequired
Images1
Videos1
Images and video togetherNone
Required optionspinterest.board_id
Connects withHosted OAuth

Connecting Pinterest accounts

Call POST /v1/accounts/connect with a profile and "platform": "pinterest", and send the account’s owner to the URL you get back. It’s valid for 15 minutes. They approve access on Pinterest’s own screen and land on your redirect_url with status=success and the new account_id.

The account owner connects Pinterest through the hosted OAuth screen. Every pin needs a board_id for one of that account’s boards.

If Pinterest ever expires a login, the account turns reconnect_required so you can ask its owner to connect again. More in Profiles and accounts.

Example: a scheduled Pinterest post

One request, with an Idempotency-Key so a retry on your side never posts twice. To post to Pinterest and other networks together, add more ids to account_ids.

curl https://api.postpeg.com/v1/posts \
  -H "Authorization: Bearer $POSTPEG_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pinterest-example-2026-10-01" \
  -d '{
    "account_ids": [
      "acc_mfz26h3k6m9p2s5v8y1b4e7h0j"
    ],
    "content": "Five-minute cold brew at home: coarse grind, cold water, patience.",
    "media": [
      {
        "url": "https://example.com/cold-brew.jpg",
        "type": "image",
        "alt_text": "Cold brew"
      }
    ],
    "scheduled_at": "2026-10-01T09:00:00Z",
    "platform_options": {
      "pinterest": {
        "board_id": "987654321012345678",
        "title": "Cold brew at home",
        "link": "https://example.com/recipes/cold-brew"
      }
    }
  }'
Response · 201 Created
{
  "id": "post_mfz2k3v8q1w5e9r4t7y0u2i6o3",
  "content": "Five-minute cold brew at home: coarse grind, cold water, patience.",
  "media": [
    {
      "url": "https://example.com/cold-brew.jpg",
      "type": "image",
      "alt_text": "Cold brew"
    }
  ],
  "platform_options": {
    "pinterest": {
      "board_id": "987654321012345678",
      "title": "Cold brew at home",
      "link": "https://example.com/recipes/cold-brew"
    }
  },
  "status": "scheduled",
  "scheduled_at": "2026-10-01T09:00:00.000Z",
  "targets": [
    {
      "account_id": "acc_mfz26h3k6m9p2s5v8y1b4e7h0j",
      "platform": "pinterest",
      "status": "pending",
      "platform_post_id": null,
      "url": null,
      "error": null,
      "attempts": 0,
      "published_at": null
    }
  ],
  "created_at": "2026-09-24T14:02:11.418Z"
}

From 09:00 the target moves through queued and publishing to published with the live url, or to failed with the reason in error. Temporary failures are retried, up to 5 attempts with growing waits. See Publishing for every status.

Questions

How do I schedule a Pinterest post?
Add scheduled_at (ISO 8601, up to a year ahead) to POST /v1/posts. The post waits as scheduled and goes out within a minute of that time. DELETE /v1/posts/{id} cancels it any time before.
What happens if a post breaks Pinterest’s rules?
postpeg checks the text (up to 500 characters), the media, and platform_options.pinterest.board_id before anything is sent. A post that doesn’t fit comes back as a 400 with every problem listed in issues, and nothing is published on any network.
Which Pinterest features does postpeg support?
Publishing, scheduling, analytics. Comments and direct messages are not available on Pinterest; asking for them returns a 400 naming the feature.
Is a board required for Pinterest?
Yes. platform_options.pinterest.board_id is required. Without it the request is refused with a 400 pointing at that field, before anything is sent.
Can a pin have several images?
No. A pin through postpeg takes exactly one image or one video, and media is required.

Also on the line

The same request publishes to all ten networks. Often paired with Pinterest:

Or see all 10: X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Threads, Bluesky and Google Business, in the platform reference.

Send your first post in a few minutes

The 7-day trial has every feature and 3 connected accounts, with no card. The quickstart takes you from a key to a published post.

Start 7-day trialRead the quickstartSee pricing