Pinterest publishing API
Pinterest Publishing API for Content Teams
Pinterest publishing in Wahdx Connection connects an account through OAuth and publishes photo Pins and video Pins to a board the user chooses. Every Pin goes to a board, so the board is selected as part of the publish request. This page covers what the API can do, the account connection and scopes, the Pin text limits, the publish sequence, and the analytics you can read back.
What the Pinterest API can do
The API publishes photo Pins and video Pins to a Pinterest board through the Pinterest API v5. Every Pin is published to a board the user chooses, and the Pin carries a title, a description, and alt text. Posts can be sent immediately or scheduled through the same workflow as the other platforms, and status tracking reports queued, processing, published, or failed per Pin. After publishing, analytics return a profile snapshot and period metrics tied to the connected account.
- Photo Pins and video Pins.
- Every Pin publishes to a Pinterest board the user chooses.
- Title, description, and alt text set per Pin.
- Scheduling through the same workflow as the other platforms.
- Profile snapshot and period analytics after publishing.
Account connection and Pinterest scopes
A Pinterest account connects through OAuth, and the user approves the scopes the integration requests. Publishing needs boards:read to list the boards a Pin can target and pins:write to create the Pin. Reading account and profile data uses user_accounts:read, while pins:read and boards:write cover reading Pins and board changes. The connected account then appears in the account listing endpoint with an accountId used for publishing.
Pin text limits: title, description, and alt text
A Pin has three text fields, and each has its own ceiling. The title is capped at 100 characters. The description, which carries the post caption, is capped at 500 characters. Alt text is capped at 500 characters. The API validates each field before the Pin is submitted, so an over-length title or description is rejected before it reaches Pinterest.
| Field | Limit |
|---|---|
| Title | 100 characters |
| Description (caption) | 500 characters |
| Alt text | 500 characters |
Publishing limits and scheduling
Pins can be published immediately or scheduled through the same scheduling workflow as the other platforms, and scheduled Pins are queued server-side. Every Pin must target a board, and the board is resolved from the connected account before the Pin is submitted. When one post targets several Pinterest accounts, each account publishes to its own board, so a board that belongs to one account is never reused for another. Only successful publishes count toward the monthly upload quota, and a failed Pin stays visible in status tracking so it can be fixed and resubmitted.
Publish sequence: endpoint to endpoint
A Pinterest Pin is three calls. List connected accounts to find the accountId. Read the board ids for that account with GET /api/content/pinterest/boards?accountId=... and pick the board the Pin targets; its id is sent as pinterestSettings.board_id, which is required. The dashboard board picker uses the same board data. Then send the Pin to POST /api/content/post with the platform set to pinterest, the board id in pinterestSettings, and the photo or video URL in mediaItems. A video Pin also needs pinterestSettings.cover_image_url. Poll GET /api/content/status/:accountId/:publishId until the Pin is published or failed.
POST /api/content/post
X-API-Key: <server-side key>
Content-Type: application/json
{
"platform": "pinterest",
"accountId": "CONNECTED_ACCOUNT_ID",
"content": "Pin description up to 500 characters",
"mediaItems": [{ "url": "https://your-domain.com/photo.jpg" }],
"pinterestSettings": {
"board_id": "PINTEREST_BOARD_ID",
"title": "Pin title up to 100 characters",
"link": "https://your-domain.com/landing-page",
"alt_text": "Describe the image for accessibility"
}
}Reading metrics back
Pinterest analytics cover a profile snapshot of followers, following, Pins, and monthly views, plus period metrics for impressions, saves, Pin clicks, outbound clicks, and video views. The numbers come from Pinterest for the connected account, so a metric the platform does not expose stays null rather than becoming an estimate. Pinterest data can lag about 48 hours, so a recent change may take time to appear.
FAQ
Common questions about the Pinterest API
Can I publish to Pinterest from an API?
Yes. The API publishes photo Pins and video Pins through the Pinterest API v5 with status monitoring.
Does every Pin need a board?
Yes. Every Pin is published to a Pinterest board the user chooses, so the board is selected before the Pin is submitted.
How long can a Pin title and description be?
A Pin title carries up to 100 characters. The description, which is the post caption, carries up to 500 characters, and alt text carries up to 500.
Which permissions does Pinterest publishing need?
Publishing needs boards:read to list target boards and pins:write to create the Pin. Profile reading uses user_accounts:read, with pins:read and boards:write for reading Pins and board changes.
How current is Pinterest analytics data?
Pinterest analytics can lag about 48 hours. The API returns the values Pinterest reports and leaves a missing metric null rather than estimating it.
Related reading
Go deeper on this workflow.
Related API docs
TikTok Content Publishing API: Video, Photos & Carousels
Publish video and photo carousels to TikTok through an official API. Media specs, posting limits, QR login, scheduling, and status tracking in one workflow.
Instagram Graph API Content Publishing for Business Accounts
Publish photos, reels, and carousels to Instagram with the Content Publishing API. Business account requirements, media limits, and metrics.
YouTube API: Upload Videos and Read Channel Analytics
Upload videos to YouTube with per-video settings, then read subscribers, views, and video metrics through one API workflow.
Threads API: Text Posts, Thread Sequences & Metrics
Publish text posts and thread sequences to Threads via API. Character limits, scopes, reply settings, rate limits, and metrics read-back.