> ## 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.

# Pinterest publishing

> Full reference for publishing Pins via SocialAPI, plus board management (create, update, delete).

## 1. Overview

Pinterest publishing uses the Pinterest API v5 against your connected Pinterest account. Every Pin needs a destination board and an image, there is no text-only or link-only post type. SocialAPI also exposes board management endpoints so you can create, rename, or remove boards without leaving the API.

Pinterest's Developer Terms of Service prohibit storing information accessed through the API. Boards and Pins are never persisted: every read hits Pinterest live, on every request, with no cache and no TTL.

| Field            | Value                                      |
| ---------------- | ------------------------------------------ |
| Platform slug    | `pinterest`                                |
| Auth type        | OAuth 2.0                                  |
| API              | Pinterest API v5                           |
| Create post      | Yes (Pin)                                  |
| Update post      | No (Pinterest's PATCH /pins is still beta) |
| Delete post      | Yes                                        |
| Schedule         | Yes (deferred publish via `scheduled_at`)  |
| Board management | Yes (create, update, delete)               |

***

## 2. Create a Pin

Use `POST /v1/posts` with a target pointing at a Pinterest account. `media` must contain exactly one image, Pinterest has no text-only Pin type.

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Weeknight dinner idea: sheet-pan salmon.",
    "media": [{ "source_type": "media_id", "source": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }],
    "targets": [{
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "board_id": "8828",
      "platform_data": {
        "title": "Sheet-pan salmon",
        "link": "https://example.com/recipes/salmon"
      }
    }]
  }'
```

### Target field

| Field      | Type   | Required | Description                                                                                                                                                                                                            |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `board_id` | string | Yes      | The board to Pin to, as a top-level field on the target. Use a board id returned by [List boards](#4-list-boards) or [Create board](#5-create-board). `page_id` is accepted as an alias, but sending both is an error. |

`board_id` must be a top-level field on the target, not inside `platform_data`: Pinterest has no default board, so a target with neither `board_id` nor `page_id` set returns `400 validation.board_id_required`, and setting `board_id` inside `platform_data` returns `400 validation.use_board_id`.

### Platform data fields

| Field         | Type   | Required | Description                                                    |
| ------------- | ------ | -------- | -------------------------------------------------------------- |
| `title`       | string | No       | Pin title, up to 100 characters.                               |
| `description` | string | No       | Overrides `text` as the Pin description, up to 800 characters. |
| `link`        | string | No       | Destination URL the Pin links to, up to 2,048 characters.      |
| `alt_text`    | string | No       | Accessibility alt text for the image, up to 500 characters.    |

### Limits

* Exactly one image in `media`. Pinterest Pins are image-only through this endpoint.
* Title: 100 characters. Description: 800 characters. Alt text: 500 characters. Link: 2,048 characters, and must be a valid `http` or `https` URL.

### Scheduling

```json theme={null}
{
  "media": [{ "source_type": "media_id", "source": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }],
  "targets": [{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "board_id": "8828"
  }],
  "scheduled_at": "2026-04-15T10:00:00Z"
}
```

***

## 3. Update and delete a Pin

**Update is not supported.** Pinterest's `PATCH /pins` endpoint is still in beta and not available to every app, so `PATCH /v1/posts/:pid` returns a `not_supported` error for Pinterest targets. Pin media is also immutable once created: even with beta access, only title, description, link, and board placement could change. To change the image, delete the Pin and create a new one.

```bash theme={null}
curl -X DELETE https://api.social-api.ai/v1/posts/p_01HZ9X3Q4R5M6N7P8V2K0W1J \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

***

## 4. List boards

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

Response:

```json theme={null}
{
  "data": [
    {
      "id": "sapi_board_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "board_id": "8828",
      "name": "Recipes",
      "privacy": "PUBLIC"
    }
  ]
}
```

Boards are fetched live from Pinterest on every call. SocialAPI stores neither the board name nor its privacy setting, so there is no cache and no lag: a name change on Pinterest shows up on the next request.

***

## 5. Create board

```bash theme={null}
curl -X POST https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/boards \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Recipes",
    "description": "Weeknight dinners",
    "privacy": "PUBLIC"
  }'
```

| Field         | Type   | Required | Description                                                          |
| ------------- | ------ | -------- | -------------------------------------------------------------------- |
| `name`        | string | Yes      | Board name.                                                          |
| `description` | string | No       | Board description.                                                   |
| `privacy`     | string | No       | `PUBLIC`, `PROTECTED`, or `SECRET`. Defaults to `PUBLIC` if omitted. |

Returns `201` with the created board. There is no default board: every publish target must set `board_id` explicitly.

***

## 6. Update board

```bash theme={null}
curl -X PATCH https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/boards/8828 \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weeknight Recipes",
    "privacy": "SECRET"
  }'
```

`name`, `description`, and `privacy` are pushed to Pinterest. `boardId` accepts either the internal board handle or the raw Pinterest board id.

**Privacy cannot be set to PROTECTED via update.** Pinterest's update schema only accepts `PUBLIC` or `SECRET` on `PATCH /boards/{id}`, unlike create, which also accepts `PROTECTED`. If a board is already `PROTECTED`, its privacy cannot be changed at all through this endpoint: recreate the board instead.

***

## 7. Delete board

```bash theme={null}
curl -X DELETE https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/boards/8828 \
  -H "Authorization: Bearer $SOCAPI_KEY"
```

**Deleting a board permanently deletes every Pin saved to it, and this cannot be undone.** There is no soft-delete or recovery path on Pinterest's side.

Returns `204` on success.

***

## 8. Get account summary

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

Returns the connected account's public profile counts (username, profile image, followers, pins, boards, monthly views), fetched live from Pinterest on every call.

***

## 9. List pins

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

Response:

```json theme={null}
{
  "data": [
    {
      "id": "813744",
      "title": "Roast chicken",
      "board_id": "8828",
      "permalink": "https://www.pinterest.com/pin/813744/",
      "media_url": "https://i.pinimg.com/x.jpg",
      "created_at": "2026-08-01T12:00:00Z"
    }
  ]
}
```

Pins are fetched live from Pinterest on every request and are never stored by SocialAPI. `limit` is optional, defaults to 50, and caps at 50. If Pinterest cannot be reached, the request fails rather than returning a stale or empty list.

***

## 10. Required OAuth scopes

| Scope                | Purpose                          |
| -------------------- | -------------------------------- |
| `boards:read`        | List boards                      |
| `boards:write`       | Create, rename, or delete boards |
| `pins:read`          | List Pins                        |
| `pins:write`         | Create and delete Pins           |
| `user_accounts:read` | Read account profile summary     |

Add `boards:read_secret` and `pins:read_secret` if the user's secret boards and Pins should be accessible. To verify which scopes your connected account has granted, call `GET /v1/accounts/:id/limits`.