# Pinterest (/docs/platforms/pinterest)



Connecting an account [#connecting-an-account]

Pinterest connects with Pinterest sign-in (OAuth). Open **Connections** in the dashboard, or send a connect link (`POST /api/v1/platform-invites` with `"platform": "pinterest"`, see [Connect links](/docs/guides/connect-links)). Personal and business accounts both work.

FeedHorizon asks Pinterest for `boards:read`, `pins:read`, `pins:write` and `user_accounts:read`.

Pinterest tokens last 30 days. FeedHorizon renews them automatically ahead of time, so the connection keeps working until the user removes FeedHorizon in their Pinterest settings. When that happens the account turns `needs_reauth` and the `account.needs_reauth` webhook is sent.

The platform id in the API is `pinterest`.

What you can post [#what-you-can-post]

|                | Limit                  |
| -------------- | ---------------------- |
| Text           | 500 characters         |
| Files per post | 1 to 5 files, required |
| Images         | JPEG, PNG or WebP      |
| Videos         | not supported          |
| File size      | 20 MB per file         |

The post text becomes the Pin description. A Pin can also have a title (up to 100 characters, default: the first line of the text) and a link where it leads when clicked, both in `options.pinterest`. One image makes a standard Pin, 2 to 5 a carousel Pin.

Choosing the board [#choosing-the-board]

Every Pin goes to a board. List the account's boards and pass the board id on the post target:

```bash title="cURL"
curl https://feedhorizon.com/api/v1/accounts/acc_…/boards \
  -H "Authorization: Bearer fh_YOUR_API_KEY"
```

```json
{ "data": [{ "boardId": "1234567890", "name": "Recipes", "privacy": "PUBLIC" }] }
```

Without a `boardId` the Pin goes to the first board in this list. Posts from the dashboard use that default too. In the MCP server the same list comes from `list_pinterest_boards`.

Example [#example]

```bash title="cURL"
curl -X POST https://feedhorizon.com/api/v1/posts \
  -H "Authorization: Bearer fh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "profileId": "prof_…",
    "content": "Five-minute tomato soup\nOur quickest weeknight dinner.",
    "mediaIds": ["med_…"],
    "targets": [{
      "accountId": "acc_…",
      "options": { "pinterest": { "boardId": "1234567890", "link": "https://example.com/soup" } }
    }],
    "scheduledFor": "2026-11-10T09:00:00+01:00"
  }'
```

After publishing [#after-publishing]

The Pinterest target carries the Pin id in `platformPostId` and the link in `platformUrl` (`https://www.pinterest.com/pin/<id>/`).

Errors [#errors]

Checked before the post is stored (`400`, see [Errors](/docs/api/errors)):

| Code                     | Cause                                                                                             | Fix                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `content_too_long`       | More than 500 characters                                                                          | Shorten the text, or give Pinterest its own text in `targets` |
| `media_required`         | The post has no image                                                                             | Add at least one image                                        |
| `too_many_media`         | More than 5 images                                                                                | Remove images or split the post                               |
| `media_too_large`        | An image is larger than 20 MB                                                                     | Compress or resize it                                         |
| `media_type_unsupported` | A video, GIF or other non-image file                                                              | Use JPEG, PNG or WebP                                         |
| `validation_failed`      | `options.pinterest` is wrong, for example a title over 100 characters or a link that is not a URL | Fix the field named in `param`                                |

While publishing (in `targets[].error`, see [Publishing errors](/docs/api/errors#publishing-errors)). Rate limits and outages are retried automatically:

| Code                   | Cause                                                                                                                        | Fix                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `account_needs_reauth` | The user removed FeedHorizon on Pinterest                                                                                    | Reconnect the account, then retry                                    |
| `platform_auth_failed` | Pinterest refused the token or a permission is missing                                                                       | Reconnect the account, then retry                                    |
| `platform_rejected`    | Pinterest refused the Pin, for example an unknown `boardId`, or the account has no board yet. `error.message` has the reason | Fix it (create a board on Pinterest, pick another board), then retry |