How do I find a board's id?

Call GET /v1/accounts/{id}/boards (or the MCP tool list_pinterest_boards). It returns each board the account can pin to as { id, name }. POST /v1/accounts/{id}/boards creates a new one. In the SkedCast console the composer shows each Pinterest account's boards by name, with a New board button.

Can I send the board's name instead of its id?

Only on a post to exactly one Pinterest account: send the board's exact name (case does not matter) as boardId and SkedCast looks up its id. Otherwise send the numeric id. A name that no board has, that several boards share, or that is used on a post to two or more Pinterest accounts is refused with 422 pinterest_board_unresolved.

Can I see which Pins perform best, including ones made outside SkedCast?

Yes. GET /v1/analytics/accounts/{id}/top-pins (or the MCP tool get_pinterest_top_pins) returns the account's best Pins as Pinterest ranks them over the last 7, 30 or 90 days, by impressions, saves, Pin clicks, outbound clicks or engagements. It reads from Pinterest, so Pins made in Pinterest itself are included. A Pin SkedCast published carries its postId.

Can I publish a multi-image Pinterest carousel?

Yes. Send 2–5 ids in the base mediaIds array (no extra override needed) and SkedCast publishes a carousel of that many images.

Create a Pin on Pinterest with the API

Browse docs

6 min read

What do you need before you publish?#

You need one connected account for the platform. Connect it in the SkedCast console. If a client owns the account, create a connect link with POST /v1/clients/{id}/connect-invites and send it to them. They authorize from that page without a SkedCast login.

GET /v1/accounts lists the connected accounts with their ids. Pass that id in targets.accountIds below.

How do you schedule a Pinterest post with the API?#

bash

curl -X POST https://api.skedcast.com/v1/posts \
  -H "Authorization: Bearer sked_live_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "<clientId>",
    "content": "Launch day is here 🚀",
    "mediaIds": ["<mediaAssetId>"],
    "targets": { "mode": "selection", "accountIds": ["<pinterestAccountId>"] },
    "schedule": { "type": "at", "scheduledAt": "2030-01-15T15:00:00Z" }
  }'

The base body. A Pinterest post also needs the boardId override shown below.

Which Pinterest fields can you set?#

Put everything platform-specific in one variants entry with "platform": "pinterest" and an overrides object. Send only pinterest keys on a pinterest variant. SkedCast reads the keys in the table below and ignores the rest.

Field	Type	Values / default	Notes
`boardId`	string — Required	The board's numeric id (digits only)	A Pin publishes onto a board. For a post to exactly one Pinterest account, the board's exact name also works and is turned into the id. Any other board value is refused at compose with `422 pinterest_board_unresolved`.
`boardSectionId`	string	—	Optional: files the Pin under one section of that board.
`accountOverrides`	object	—	Per-account values, keyed by account id. A board belongs to one Pinterest account, so a post to several Pinterest accounts gives each its own `boardId` here.
`title`	string (≤100)	—	Optional. When absent, the first line of the caption is the title and the rest is the description. A first line over 100 characters is refused.
`link`	string (url)	—	Destination URL.

How do you add Pinterest-specific settings?#

json

{
  "clientId": "<clientId>",
  "content": "Autumn lookbook, five ways to style it.",
  "mediaIds": ["<imageAssetId>"],
  "targets": { "mode": "selection", "accountIds": ["<pinterestAccountId>"] },
  "variants": [
    { "platform": "pinterest", "overrides": { "boardId": "<boardId>", "title": "Autumn Lookbook", "link": "https://example.com/lookbook" } }
  ],
  "schedule": { "type": "at", "scheduledAt": "2030-01-15T15:00:00Z" }
}

The same POST /posts body, with a variants entry added.

How do you check that the post published?#

Publishing creates one post target per account. GET /v1/post-targets/{id} (or GET /v1/posts/{id}) reports status, plus externalId (Pinterest's own post id) and permalink (its public URL) once published. To avoid polling, subscribe to the target.published and target.failed webhooks (see the webhooks guide).

pinterestapipublish

FAQ

How do I find a board's id?: Call GET /v1/accounts/{id}/boards (or the MCP tool list_pinterest_boards). It returns each board the account can pin to as { id, name }. POST /v1/accounts/{id}/boards creates a new one. In the SkedCast console the composer shows each Pinterest account's boards by name, with a New board button.
Can I send the board's name instead of its id?: Only on a post to exactly one Pinterest account: send the board's exact name (case does not matter) as boardId and SkedCast looks up its id. Otherwise send the numeric id. A name that no board has, that several boards share, or that is used on a post to two or more Pinterest accounts is refused with 422 pinterest_board_unresolved.
Can I see which Pins perform best, including ones made outside SkedCast?: Yes. GET /v1/analytics/accounts/{id}/top-pins (or the MCP tool get_pinterest_top_pins) returns the account's best Pins as Pinterest ranks them over the last 7, 30 or 90 days, by impressions, saves, Pin clicks, outbound clicks or engagements. It reads from Pinterest, so Pins made in Pinterest itself are included. A Pin SkedCast published carries its postId.
Can I publish a multi-image Pinterest carousel?: Yes. Send 2–5 ids in the base mediaIds array (no extra override needed) and SkedCast publishes a carousel of that many images.

Create a Pin with the API