Pinterest

Publish image and video pins to Pinterest with POST /v1/posts and platform: "pinterest". The same account serves board management, description edits and analytics.

Quick reference

Before you start

Pinterest requires a board to pin to; create one in Pinterest or with Create a board. Every pin needs 1 image or 1 video, so there are no text-only pins and no carousels or multi-image posts. Pinterest is a search engine rather than a social feed: people find pins through search and browse, not through followers, so the title, description and board name matter more than the posting time, and a pin keeps surfacing for 3 to 6 months instead of hours. link is where a click on the pin sends people, so it is the field that drives traffic.

Connect

Call GET /v1/connect/pinterest with profileId on Get OAuth connect URL. After OAuth the user picks a default board: List boards then Select board, in standard or headless mode like the other selection platforms; see platforms requiring secondary selection. Change the default board later with Update Pinterest board, with no second OAuth. The connecting accounts guide covers the flow and scopes in general; Account health reports what a connected account can do with the scopes the user granted.

OAuth scopes

Publish

A plain post becomes an image pin when the media is an image and a video pin when it is a video. boardId, title and link go in platformSpecificData on the Pinterest entry; content is the pin description.

Image pin

A single image pinned to a board. Use a 2:3 aspect ratio (1000 x 1500 px) for the best display in the Pinterest feed.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: published } = await zernio.posts.createPost({
  body: {
    content: 'Modern kitchen renovation ideas for small spaces',
    mediaItems: [
      { type: 'image', url: 'https://cdn.example.com/kitchen-ideas.jpg' }
    ],
    platforms: [{
      platform: 'pinterest',
      accountId: '66b2e19d8c3f5a7e9d0b1c2d',
      platformSpecificData: {
        title: 'Modern Kitchen Renovation Ideas',
        boardId: '1022106146582011234',
        link: 'https://myblog.com/kitchen-renovation'
      }
    }],
    publishNow: true
  }
});

console.log(published.post.platforms[0].platformPostUrl);

Response (201):

{
  "post": {
    "_id": "65f1c0a9e2b5af0012ab34cd",
    "status": "published",
    "platforms": [
      {
        "platform": "pinterest",
        "status": "published",
        "platformPostUrl": "https://www.pinterest.com/pin/..."
      }
    ]
  }
}

Every sample below changes only the mediaItems or the platforms entry of this request.

Video pin

A single video pinned to a board. coverImageUrl sets a custom cover; coverImageKeyFrameTime extracts a frame at that second instead.

"mediaItems": [
  { "type": "video", "url": "https://cdn.example.com/recipe.mp4" }
],
"platforms": [{
  "platform": "pinterest",
  "accountId": "66b2e19d8c3f5a7e9d0b1c2d",
  "platformSpecificData": {
    "title": "5-Minute Breakfast Recipe",
    "boardId": "1022106146582011234",
    "link": "https://myrecipes.com/quick-breakfast",
    "coverImageUrl": "https://cdn.example.com/recipe-cover.jpg"
  }
}]

Boards

Every pin belongs to a board. List the boards on a connected account, or create one through the API; the boards:write scope is part of every Pinterest connection, so no reconnect is needed.

List boards

const { data: boards } = await zernio.connect.getPinterestBoards({
  path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d' }
});

console.log(boards.boards);

Response (200):

{
  "boards": [
    {
      "id": "1022106146582011234",
      "name": "Kitchen Ideas",
      "description": "Renovations and layouts",
      "privacy": "PUBLIC",
      "url": "https://www.pinterest.com/yourhandle/kitchen-ideas/"
    }
  ]
}

Create a board

The response carries the new board's id, which works at once as platformSpecificData.boardId. privacy is PUBLIC (default), PROTECTED or SECRET.

const { data: created } = await zernio.connect.createPinterestBoard({
  path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d' },
  body: {
    name: 'Summer Recipes',
    description: 'My favorite summer recipes',
    privacy: 'PUBLIC'
  }
});

console.log(created.board.id);

Response (201):

{
  "board": {
    "id": "1022106146582019876",
    "name": "Summer Recipes",
    "description": "My favorite summer recipes",
    "privacy": "PUBLIC",
    "url": "https://www.pinterest.com/yourhandle/summer-recipes/"
  }
}

Pinterest rejects a duplicate board name on the same account, and you cannot pin to a secret board you do not own. A board-creation error from Pinterest comes back with its original message and a 502.

Edit a published pin

Edit post replaces the description of a pin that is already live, up to the same 800 characters a create takes. The title, media, destination link and board cannot be changed, a title derived from the first line of the original content at publish time stays as it was, and there is no time window, no edit limit and the pin id is unchanged.

const { data: edited } = await zernio.posts.editPost({
  path: { postId: '65f1c0a9e2b5af0012ab34cd' },
  body: {
    platform: 'pinterest',
    content: 'Updated pin description with the new recipe link details'
  }
});

console.log(edited.id, edited.url);

Response (200):

{
  "success": true,
  "id": "1022106146582013456",
  "url": "https://www.pinterest.com/pin/1022106146582013456/",
  "message": "Post edited successfully"
}

If the post was published to several Pinterest accounts, pass accountId to pick which copy to edit; without it, the first pinterest entry on the post is edited.

Platform fields

All fields go in platformSpecificData on the Pinterest entry.

Media requirements

Images

Animated GIFs auto-play in the feed and are treated as images, not video. The limit is 32 MB, and under 10 MB loads fast.

Videos

Media URLs

A media URL must be publicly accessible with no authentication, return the media bytes with the correct Content-Type header, not redirect to an HTML page, and sit on a fast host. Google Drive, Dropbox, OneDrive and iCloud sharing links return a webpage and fail. To host files instead, use the media endpoint.

Analytics

Call GET /v1/analytics?platform=pinterest (Analytics API).

const { data: analytics } = await zernio.analytics.getAnalytics({
  query: { platform: 'pinterest', fromDate: '2026-08-01', toDate: '2026-08-31' }
});

console.log(analytics.posts);

Response (200), one entry per post:

{
  "posts": [
    {
      "_id": "65f1c0a9e2b5af0012ab34cd",
      "platform": "pinterest",
      "status": "published",
      "publishedAt": "2026-08-14T10:00:05Z",
      "platformPostUrl": "https://www.pinterest.com/pin/1022106146582013456/",
      "analytics": {
        "impressions": 4380,
        "saves": 96,
        "clicks": 141
      }
    }
  ]
}

Inbox

Pinterest has no inbox API: no DMs, no comments and no reviews.

What you cannot do

Pinterest's API does not expose:

• Idea Pins (multi-page stories)
• Claiming a website
• Rich Pins (they need meta tags on your website)
• Shopping catalogs
• Changing a published pin's media, destination link or board (only the description; see Edit a published pin)
• Multi-image posts or carousels

Common errors

A publishNow: true post that Pinterest rejects returns 207 with post.status: "failed" and the message in platforms[].errorMessage:

{
  "message": "Post created but publishing failed",
  "error": "All platforms failed",
  "post": {
    "_id": "65f1c0a9e2b5af0012ab34cd",
    "status": "failed",
    "platforms": [
      {
        "platform": "pinterest",
        "status": "failed",
        "errorMessage": "Unable to reach the URL. Please check the URL is correct and try again."
      }
    ]
  }
}

207 is a 2xx status, so fetch(...).ok is true; branch on the status code and on post.status. Error handling covers the envelope.

Related

• Connecting accounts: the OAuth flow and board selection.
• Create post: every field of the request.
• Edit post: update the description of a published pin.
• Media uploads: upload images and videos instead of hosting them.
• Pinterest boards and Create Pinterest board: the boards endpoints.