How do I find a board's id?

The Agency Console's composer shows your boards by name when you're picking a Pinterest destination — pick it there. The board picker resolves the name to the `boardId` the API needs; you don't have to look up Pinterest's own board id by hand.

Can I publish a multi-image Pinterest carousel?

Yes — send 2–5 ids in the base `mediaIds` array (no extra override needed); the adapter publishes a carousel of that many images.

Create a Pin on Pinterest via API

Browse docs

6 min read

Before you publish#

You need one already-connected account for the platform. Connect it yourself in the Agency Console, or — if a client owns the account — mint a self-serve connect link with POST /clients/:id/connect-invites and send it to them; they authorize from that page without ever getting a SkedCast login.

GET /v1/accounts lists what's connected, with each account's id — that id is what you pass in targets.accountIds below.

Compose and schedule#

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": "2026-07-01T15:00:00Z" }
  }'

A minimal pinterest post, scheduled for a specific time.

The Pinterest API fields to create a Pin#

Everything platform-specific goes in one variants entry with "platform": "pinterest" and an overrides object. The adapter reads only the keys it declares (below) and ignores the rest — send pinterest keys on a pinterest variant, nothing more.

Field	Type	Values / default	Notes
`boardId`	string — Required	—	A Pin publishes onto a board — the target fails at publish time without one.
`title`	string (≤100)	—	Optional headline, distinct from the description (`content`).
`link`	string (url)	—	Destination URL.

Verbatim from the REST API reference's Pinterest table.

With the platform-specific overrides#

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": "2026-07-01T15:00:00Z" }
}

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

Checking the result#

Publishing fans out into one post target per account. GET /post-targets/:id (or GET /posts/:id) reports status, plus externalId (pinterest's own post id) and permalink (its public URL) once published. Subscribe to the target.published / target.failed webhooks instead of polling if you can accept inbound HTTP — see the webhooks guide.

pinterestapipublish

FAQ

How do I find a board's id?: The Agency Console's composer shows your boards by name when you're picking a Pinterest destination — pick it there. The board picker resolves the name to the `boardId` the API needs; you don't have to look up Pinterest's own board id by hand.
Can I publish a multi-image Pinterest carousel?: Yes — send 2–5 ids in the base `mediaIds` array (no extra override needed); the adapter publishes a carousel of that many images.

How to create a Pin on Pinterest through the SkedCast API