Pinterest API - SocialAPI

The Pinterest API in SocialAPI connects a Pinterest account through Pinterest’s authorization screen. It publishes Pins to boards, creates, renames, and deletes boards, lists Pins, and reads profile counts. Pinterest is a publishing surface: it exposes no comments, DMs, mentions, or reviews to apps. SocialAPI’s own Pinterest app connects the account, so you register nothing: see Platform apps.

At a glance

Field	Value
Platform slug	`pinterest`
Auth	OAuth 2.0
Platform API	Pinterest API v5
Status	Available

Capabilities

An unsupported call returns 501 resource.not_supported.

Feature	Status	Condition
Publish a Pin	Yes	One image and a `board_id` on the target. See Pinterest publishing
Schedule a Pin	Yes	`scheduled_at` on the post
First comment on a Pin	No	`first_comment` is ignored
Update a published Pin	No	`PATCH /v1/posts/{pid}` returns `409 post.state_invalid` for a published post. Pinterest’s edit call is in beta and Pin media never changes
Delete a Pin	Yes
List Pins	Yes	Read from Pinterest on every call. See List Pins
Boards: list, create, rename, delete	Yes	See Pinterest boards
Account summary	Yes	See Account summary
Post metrics	No	Pinterest reports no engagement counts on the Pin list. `GET /v1/posts/{pid}/metrics` returns HTTP 200, and the Pinterest target carries `error.code: resource.not_supported`
Comments, DMs, mentions	No	Pinterest has no public API for them. `501 resource.not_supported`
Reviews	No	Pinterest has no reviews. `GET /v1/inbox/reviews/{account_id}` returns `422 account.platform_unsupported`
Automations	No	`422 automation.platform_unsupported`
Analytics	Partial	Live account summary only; SocialAPI stores no account history, and Pins have no post metrics. See Analytics
Webhook events	Partial	`account.connected` and the `post.*` events. Pinterest sends no events of its own

The cross-platform matrix is on Platforms.

Connect an account

Connect with POST /v1/accounts/connect and "platform": "pinterest". The shared flow, request fields, and result are in Connect accounts, and the redirect parameters are in Redirect parameters.

curl -X POST https://api.social-api.ai/v1/accounts/connect \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "pinterest",
    "redirect_uri": "https://app.example.com/oauth/callback",
    "state": "session_abc123"
  }'

Response (HTTP 202):

{
  "auth_url": "https://www.pinterest.com/oauth/?client_id=1234567&response_type=code&state=4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2",
  "state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2",
  "message": "Open this link to connect your pinterest account. Once you've authorized, the account will be connected automatically."
}

Pinterest-specific rules:

Token lifetime. Pinterest access tokens last 30 days and refresh tokens last 60 days, and each use of a refresh token extends it. SocialAPI renews the access token before it expires, so a connected account keeps working without a reconnect.
Reconnect. When Pinterest reports that authentication failed, the first call that fails returns 401 platform.pinterest.auth and the account is marked token_expired. Every later call that acts on the account returns 403 account.reconnection_required until you reconnect it. Any other 401 from Pinterest returns 401 platform.pinterest.unauthorized and leaves the account working: reconnect only if it persists. See Reconnect an account.
Disconnect. Pinterest offers apps no way to end an authorization. Disconnecting an account removes it from SocialAPI, and the person removes SocialAPI’s app in their Pinterest settings.

Boards and Pins are read live

SocialAPI reads boards and Pins from Pinterest on every request and stores neither, because Pinterest’s developer terms forbid storing information read through its API. A board created in the Pinterest app a moment ago appears on the next call, and a call fails when Pinterest is unavailable instead of returning an older list.

List Pins

GET /v1/platforms/pinterest/accounts/{id}/pins returns the account’s Pins in the order Pinterest returns them. limit is optional, defaults to 50, and is at most 50. The response holds only the first 50 Pins at most, with no cursor: you cannot page to older Pins. It needs the accounts:read scope.

curl "https://api.social-api.ai/v1/platforms/pinterest/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/pins?limit=20" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "data": [
    {
      "id": "813744",
      "title": "One pan, forty minutes, no marinade.",
      "board_id": "8828",
      "permalink": "https://www.pinterest.com/pin/813744/",
      "media_url": "https://i.pinimg.com/600x/ab/cd/ef.jpg",
      "created_at": "2026-08-01T12:00:00Z"
    }
  ]
}

title carries the Pin’s description, not its separate Pinterest title.

Account summary

GET /v1/platforms/pinterest/accounts/{id}/summary reads the account’s public profile counts from Pinterest at the time of the call. It needs the accounts:read scope. A count Pinterest does not report is 0.

curl https://api.social-api.ai/v1/platforms/pinterest/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/summary \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200):

{
  "username": "boardandco",
  "profile_image": "https://i.pinimg.com/280x280_RS/ab/cd/ef.jpg",
  "follower_count": 12400,
  "pin_count": 847,
  "board_count": 23,
  "monthly_views": 1200000
}

Webhook events

Pinterest sends SocialAPI no events. These SocialAPI events still fire for a Pinterest account:

Event	When it fires
`account.connected`	The account was connected
`account.updated`	The account lost permissions you did not remove yourself (`change` is `permissions_reduced`)
`post.published`, `post.partial`, `post.failed`	A post to this account finished: see Delivery

Every event is described in Webhook events.

Limits

Limit	Value
Image per Pin	1
Pin title	100 characters
Pin description	800 characters
Alt text	500 characters
Destination link	2,048 characters
Posts	1,000 per 24 hours for each board, with no hourly cap: see Posting velocity caps
Pins per list call	50
Pinterest’s own rate limit	`429 platform.pinterest.rate_limit`. Credit rules: see when a credit comes back

Scopes

SocialAPI’s Pinterest app requests these scopes at connect. You apply for no app review. SocialAPI does not request boards:read_secret or pins:read_secret. Each scope belongs to the account permissions in the last column, and the consent screen asks for the scopes of the permissions you selected.

Scope	Used for	Permissions
`boards:read`	List boards	`posts.read`, `posts.write`
`boards:write`	Create, rename, and delete boards. Pinterest also requires it to create and delete Pins	`posts.write`
`pins:read`	List Pins	`posts.read`, `posts.write`
`pins:write`	Create and delete Pins	`posts.write`
`user_accounts:read`	Account summary and the account’s identity	Every account

Pinterest publishing: fields, media rules, and quirks for publishing Pins
Pinterest boards: list, create, rename, and delete boards
Connect accounts: the shared connect flow
Platforms: the capability matrix
Errors: every error code

​At a glance

​Capabilities

​Connect an account

​Boards and Pins are read live

​List Pins

​Account summary

​Webhook events

​Limits

​Scopes

​Related