Pinterest publishing

1. Overview

A Pin needs a destination board and one image. Pinterest has no text-only or link-only post, and no default board: every Pinterest target sets board_id.

Field	Value
Platform slug	`pinterest`
Auth type	OAuth 2.0
API	Pinterest API v5
Create post	Yes (a Pin)
Update post	No (`409 post.state_invalid` on a published post)
Delete post	Yes
Schedule	Yes (deferred publish via `scheduled_at`)
First comment	No (`first_comment` is ignored)
Posting caps	1,000 posts per 24 hours for each board, with no hourly cap: see Posting velocity caps

2. Supported media

Content type	How to trigger	Notes
Image Pin	One image in `media`	The only Pin type SocialAPI publishes

SocialAPI sends the first media item to Pinterest as the Pin’s image and ignores the rest. A Pin with no image fails validation on the field media. SocialAPI does not check the image’s type or size in advance: Pinterest rejects a file it does not accept, and the target fails. A video is not supported. Field limits: title 100 characters, description 800 characters, alt text 500 characters, and link 2,048 characters. A longer value in platform_data.pinterest fails validation with 400 publishing.validation_failed, and the issue names the field. SocialAPI checks the 800-character limit only on platform_data.pinterest.description: a longer text is sent as is and Pinterest refuses it.

Attach the image through the media array. Each item sets a source_type: media_id for a file you uploaded to SocialAPI, or url for a public http(s) URL Pinterest can fetch. A platform_attachment_id item returns 422 publishing.media.unsupported_source. To upload first, see Media.

3. Create post

Use POST /v1/posts with a target that sets account_id and board_id, and publish_now: true. Get board_id from Pinterest boards.

curl -X POST https://api.social-api.ai/v1/posts \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "One pan, forty minutes, no marinade.",
    "media": [{ "source_type": "media_id", "source": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }],
    "publish_now": true,
    "targets": [{
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "board_id": "8828"
    }],
    "platform_data": {
      "pinterest": {
        "title": "Weeknight roast chicken",
        "link": "https://example.com/recipes/chicken",
        "alt_text": "A roast chicken on a sheet pan with lemons"
      }
    }
  }'

Response (HTTP 201):

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "text": "One pan, forty minutes, no marinade.",
  "status": "publishing",
  "hidden": false,
  "retry_count": 0,
  "created_at": "2026-10-13T09:00:00Z",
  "updated_at": "2026-10-13T09:00:00Z",
  "targets": [
    {
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "page_id": "sapi_board_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "platform": "pinterest",
      "status": "publishing"
    }
  ]
}

Target field

Field	Type	Required	Description
`board_id`	string	Yes	The board to Pin to. Use the `id` or the `board_id` that List boards returns. `page_id` is accepted as an alias, but sending both fails with `400 validation.duplicate_board_id`

A target with neither board_id nor page_id fails with 400 validation.board_id_required. A board_id inside platform_data fails with 400 validation.use_board_id: set it on the target.

Pin text

The post’s text is the Pin’s description. Set the Pin’s title in platform_data.pinterest.title: the post’s top-level title field is not used for a Pin.

Platform data fields

Send these keys in platform_data.pinterest on the post, which applies them to every Pinterest target. To set them for one target, send them flat in that target’s platform_data (targets[].platform_data, with no pinterest key). When both set the same key, the target’s value wins.

Key	Type	Required	Notes
`title`	string, up to 100 characters	No	The Pin title
`description`	string, up to 800 characters	No	Replaces `text` as the Pin description
`link`	string, up to 2,048 characters	No	The destination URL. An absolute `http` or `https` URL
`alt_text`	string, up to 500 characters	No	Alt text for the image

SocialAPI forwards any additional keys in platform_data.pinterest that the table above lists, and no others. Pinterest has no other publish options that SocialAPI passes through: an unlisted key is ignored without a warning.

Scheduling

Set scheduled_at to an ISO 8601 timestamp (UTC) instead of publish_now. SocialAPI holds the post and publishes it at that time.

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

4. Update post

SocialAPI offers no edit of a published Pin. Pinterest’s edit call is in beta and not open to every app, and a Pin’s image never changes. PATCH /v1/posts/{pid} edits only a post in draft, scheduled, or failed status, and returns 409 post.state_invalid for a published post. To change a Pin, delete it and publish a new one: the new Pin has a new ID.

5. Delete post

DELETE /v1/posts/{pid} deletes the Pin from Pinterest when its Pinterest target is published. See Delete a post. Deleting a board deletes every Pin on it: see Pinterest boards.

curl -X DELETE https://api.social-api.ai/v1/posts/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer $SOCAPI_KEY"

6. Retrieve posts

GET /v1/platforms/pinterest/accounts/{id}/pins returns the account’s Pins, read from Pinterest on every call. The response and its fields are in List Pins. Each published target of a post you created carries platform_post_id and permalink. Pinterest reports no engagement counts on the Pin list, so a Pin has no metrics. GET /v1/posts/{pid}/metrics returns HTTP 200, and the Pinterest target carries error.code: resource.not_supported. Account-level counts are in Analytics.

7. Quirks, errors, and recovery

A Pin needs a board

There is no default board, and a target without board_id is refused. When the connected account does not own the board, Pinterest refuses the Pin and the target fails with 403 platform.pinterest.403.

Boards and Pins are read live

SocialAPI stores no board or Pin. A board you just created appears on the next call. If Pinterest is unavailable, a call fails.

Errors on a failed target

A publish that fails after the request returned puts a structured error on the target, in targets[].error, with its code. Every code is in Errors.

401 platform.pinterest.auth: Pinterest reported that authentication failed. The account is marked token_expired, and every later call that acts on the account returns 403 account.reconnection_required until you reconnect it.
401 platform.pinterest.unauthorized: Pinterest answered 401 without naming the token. The account keeps working. Reconnect if it persists.
403 platform.pinterest.403: Pinterest refused the action for this account or board. Read message.
404 platform.pinterest.404: Pinterest reports that the board or Pin does not exist.
429 platform.pinterest.rate_limit: Pinterest’s own limit. Wait, then retry.

Recovery

Rate limit. Wait for the seconds in Retry-After, or at least 60 seconds when it is absent, then send POST /v1/posts/{pid}/retry. See Delivery.
Auth error. Reconnect the Pinterest account through the OAuth flow.
Wrong board. Delete the Pin, then publish it to the right board.

8. Full worked example

This example finds a board, publishes a Pin to it, and reads the result. Step 1: List boards

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

Response (HTTP 200):

{
  "data": [
    {
      "id": "sapi_board_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "board_id": "8828",
      "name": "Recipes",
      "privacy": "PUBLIC"
    }
  ]
}

Step 2: Upload media Upload the image and verify it as described in Media. The result is a media_id, here f47ac10b-58cc-4372-a567-0e02b2c3d479. Step 3: Publish the Pin

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" }],
    "publish_now": true,
    "targets": [{
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "board_id": "8828"
    }],
    "platform_data": {
      "pinterest": {
        "title": "Sheet-pan salmon",
        "link": "https://example.com/recipes/salmon"
      }
    }
  }'

Response (HTTP 201): the post with status: "publishing", as in Create post. Step 4: Check the status

curl https://api.social-api.ai/v1/posts/7c9e6679-7425-40de-944b-e07fc1f90ae7 \
  -H "Authorization: Bearer $SOCAPI_KEY"

Response (HTTP 200) once published:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "text": "Weeknight dinner idea: sheet-pan salmon.",
  "status": "published",
  "hidden": false,
  "retry_count": 0,
  "published_at": "2026-10-13T09:00:04Z",
  "created_at": "2026-10-13T09:00:00Z",
  "updated_at": "2026-10-13T09:00:04Z",
  "targets": [
    {
      "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "page_id": "sapi_board_01HZ9X3Q4R5M6N7P8V2K0W1J",
      "platform": "pinterest",
      "status": "published",
      "platform_post_id": "813744",
      "permalink": "https://www.pinterest.com/pin/813744/",
      "published_at": "2026-10-13T09:00:04Z"
    }
  ]
}

9. Required OAuth scopes

SocialAPI’s Pinterest app requests these scopes during the OAuth flow. You configure nothing. The full list is in Pinterest scopes.

Scope	Purpose
`boards:read`	List boards to choose `board_id`
`boards:write`	Required by Pinterest to create and delete Pins
`pins:write`	Create and delete Pins

The scopes a scoped API key needs, the credit cost of a post, and the MCP tools that publish are on Publishing.

​1. Overview

​2. Supported media

​3. Create post

​Target field

​Pin text

​Platform data fields

​Scheduling

​4. Update post

​5. Delete post

​6. Retrieve posts

​7. Quirks, errors, and recovery

​A Pin needs a board

​Boards and Pins are read live

​Errors on a failed target

​Recovery

​8. Full worked example

​9. Required OAuth scopes

1. Overview

2. Supported media

3. Create post

Target field

Pin text

Platform data fields

Scheduling

4. Update post

5. Delete post

6. Retrieve posts

7. Quirks, errors, and recovery

A Pin needs a board

Boards and Pins are read live

Errors on a failed target

Recovery

8. Full worked example

9. Required OAuth scopes