> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer <your API key>.
> Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs.
> A 429 response carries a Retry-After header, in seconds, when the limit has a known wait.
> Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page.
> Treat every ID as an opaque string: do not parse it or assume a format.
> Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported.

# Pinterest API

> Connect Pinterest accounts to publish Pins to boards, manage boards, list Pins, and read profile counts through one API.

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](/guides/platform-credentials).

## 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](/platforms/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](#list-pins) |
| Boards: list, create, rename, delete | Yes | See [Pinterest boards](/platforms/pinterest/boards) |
| Account summary | Yes | See [Account summary](#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](/guides/analytics) |
| Webhook events | Partial | `account.connected` and the `post.*` events. Pinterest sends no events of its own |

The cross-platform matrix is on [Platforms](/platforms/overview).

## Connect an account

Connect with `POST /v1/accounts/connect` and `"platform": "pinterest"`. The shared flow, request fields, and result are in [Connect accounts](/guides/connect-accounts), and the redirect parameters are in [Redirect parameters](/guides/connect-accounts#redirect-parameters).

```bash theme={null}
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):

```json theme={null}
{
  "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](/guides/connect-accounts#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.

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

Response (HTTP 200):

```json theme={null}
{
  "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`.

```bash theme={null}
curl https://api.social-api.ai/v1/platforms/pinterest/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/summary \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

Response (HTTP 200):

```json theme={null}
{
  "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](/guides/permissions) you did not remove yourself (`change` is `permissions_reduced`) |
| `post.published`, `post.partial`, `post.failed` | A post to this account finished: see [Delivery](/guides/delivery) |

Every event is described in [Webhook events](/guides/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](/guides/rate-limits#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](/guides/plans#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](/guides/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 |

## Related

* [Pinterest publishing](/platforms/pinterest/publishing): fields, media rules, and quirks for publishing Pins
* [Pinterest boards](/platforms/pinterest/boards): list, create, rename, and delete boards
* [Connect accounts](/guides/connect-accounts): the shared connect flow
* [Platforms](/platforms/overview): the capability matrix
* [Errors](/guides/errors): every error code


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.