Pinterest

Publish image and video pins to a board, schedule them and delete them.

Quick ReferenceCopy Anchor Link

Every pin is 1 image or video, saved to the board in pinterest.boardId. text is the description, and its first line is the default title.

ConnectCopy Anchor Link

Connect in Dashboard → Connections, or with a connect session. The account needs a board. You can create one through the API.

PermissionsCopy Anchor Link

Staying ConnectedCopy Anchor Link

Access renews itself, so canAutoRenew is true.

Reconnect if status leaves active, or on TOKEN_INVALID. Use the same Pinterest account, and its id stays the same.

PublishCopy Anchor Link

import { Configuration, PostsApi } from "@onepostly/sdk";

const postsApi = new PostsApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

const response = await postsApi.createPost({
  createPostBody: {
    "text": "Ten ways to style open shelves in a small kitchen.",
    "mediaKind": "image",
    "media": [
      {
        "url": "https://cdn.onepostly.com/media/kitchen-shelves.jpg"
      }
    ],
    "accounts": [
      {
        "accountId": "acc_YOUR_PINTEREST_ACCOUNT_ID",
        "pinterest": {
          "boardId": "1035968376946032411",
          "title": "Open Shelf Styling Ideas",
          "link": "https://example.com/blog/open-shelves"
        }
      }
    ]
  },
});
console.log(response);

{
  "groupId": "grp_7d2e5b1a9c4f4a68b3e07f1c2d9a6e45",
  "data": [
    {
      "id": "pst_3c8a2d6e91b44f7a8e250d6b4c1f9a73",
      "groupId": "grp_7d2e5b1a9c4f4a68b3e07f1c2d9a6e45",
      "accountId": "acc_YOUR_PINTEREST_ACCOUNT_ID",
      "platform": "pinterest",
      "source": "onepostly",
      "status": "publishing",
      "text": "Ten ways to style open shelves in a small kitchen.",
      "mediaKind": "image",
      "media": [
        {
          "url": "https://cdn.onepostly.com/media/kitchen-shelves.jpg"
        }
      ],
      "thread": [],
      "scheduledFor": null,
      "timezone": null,
      "options": {
        "pinterest": {
          "boardId": "1035968376946032411",
          "title": "Open Shelf Styling Ideas",
          "link": "https://example.com/blog/open-shelves"
        }
      },
      "platformPostId": null,
      "url": null,
      "error": null,
      "publishedAt": null,
      "metrics": null,
      "createdAt": "2027-03-15T09:00:00.000Z",
      "updatedAt": "2027-03-15T09:00:00.000Z"
    }
  ]
}

Once published, platformPostId is the pin id and url its pin link.

Post TypesCopy Anchor Link

Other kinds, or more than 1 file, return 400 VALIDATION_ERROR.

A video pin is published once Pinterest processes it, so it takes longer. coverImageUrl sets its cover, and without it the first frame is the cover.

BoardsCopy Anchor Link

List Pinterest Boards returns up to 2,500 boards.

import { Configuration, AccountsApi } from "@onepostly/sdk";

const accountsApi = new AccountsApi(
  new Configuration({ accessToken: process.env.ONEPOSTLY_API_KEY })
);

const response = await accountsApi.listAccountBoards({
  id: "acc_YOUR_PINTEREST_ACCOUNT_ID",
});
console.log(response);

{
  "data": [
    {
      "id": "1035968376946032411",
      "name": "Recipes",
      "isDefault": true
    },
    {
      "id": "1035968376946032398",
      "name": "Kitchen Ideas",
      "isDefault": false
    },
    {
      "id": "1035968376946032405",
      "name": "Meal Prep",
      "isDefault": false
    }
  ]
}

isDefault marks a suggested board. Pins only go there if you pass its id.

Create Pinterest Board takes a name up to 180 characters and a description up to 500. The new id works as boardId right away.

OptionsCopy Anchor Link

Options go under pinterest. Another platform's options there return 400.

text and description each stop at 800, so one cannot extend the other.

Destination LinkCopy Anchor Link

link must be a full https:// URL. http:// and short links return 400. Short links include bit.ly, t.co and tinyurl.com. Use the final URL.

Media RequirementsCopy Anchor Link

These are Pinterest's limits, on top of the Media URL Requirements.

A file outside these formats and sizes is refused. See Platform Limits.

ImagesCopy Anchor Link

VideosCopy Anchor Link

A video URL must send a Content-Length header. Uploaded files always do.

Scheduling, Editing and DeletingCopy Anchor Link

Scheduling and editing work as usual. Published pins return NOT_EDITABLE. Deleting removes the pin. One already gone counts as deleted.

EngagementCopy Anchor Link

Comments, likes, reposts and bookmarks return UNSUPPORTED_PLATFORM.

InboxCopy Anchor Link

Pinterest has no inbox through Onepostly.

AnalyticsCopy Anchor Link

Pinterest reports no metrics here. A pin reads pending first, then unsupported for good. Account stats, insights, pin lists and sync return UNSUPPORTED_PLATFORM, so skip those calls for Pinterest.

LimitationsCopy Anchor Link

Not available for Pinterest through Onepostly.

• Carousel pins
• Text-only pins
• Editing a published pin
• Analytics and account stats
• Listing or syncing outside pins
• Comments, likes and messages

ErrorsCopy Anchor Link

Breaking a rule above returns 400 VALIDATION_ERROR and creates nothing.

Every code is in Errors.

Publish ErrorsCopy Anchor Link

Board ErrorsCopy Anchor Link