Pinterest publishing - SocialAPI.AI

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.

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 or 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

{
  "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.

curl -X DELETE https://api.social-api.ai/v1/posts/p_01HZ9X3Q4R5M6N7P8V2K0W1J \
  -H "Authorization: Bearer $SOCAPI_KEY"

4. List boards

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

Response:

{
  "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

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

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

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

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

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

Response:

{
  "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.

​1. Overview

​2. Create a Pin

​Target field

​Platform data fields

​Limits

​Scheduling

​3. Update and delete a Pin

​4. List boards

​5. Create board

​6. Update board

​7. Delete board

​8. Get account summary

​9. List pins

​10. Required OAuth scopes