Pinterest Scheduling API
The Pinterest Scheduling API lets you queue an image or video Pin for a future publishing time, targeted at a specific board, without building and maintaining your own publishing queue.
POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
{
"content": "A short example update.",
"platforms": [
{
"platform": "pinterest",
"accountId": "pin_111",
"platformSpecificData": {
"boardId": "1143210755351402924",
"title": "10 Workspace Design Ideas",
"link": "https://example.com/workspace-ideas"
}
}
],
"mediaItems": [
{
"type": "image",
"url": "https://cdn.example.com/workspace.jpg"
}
],
"scheduledFor": "2026-09-15T09:00:00",
"timezone": "America/Los_Angeles"
}POST {{API_BASE_URL}}/v1/posts
x-access-key: YOUR_API_KEY
Content-Type: application/json
You send one request with the Pin content, media, destination board, scheduledFor timestamp, and timezone, and the response confirms the scheduled post with a postId and the resolved UTC publishing time.
What the Pinterest Scheduling API does
The Pinterest Scheduling API is built for products, agency workflows, automations, and AI systems that need to publish Pins at a precise future time rather than immediately. Instead of maintaining your own queue, you create each Pin with its own scheduledFor value and let the scheduling service hold it until the specified publishing time. This makes it practical to queue weeks of Pins across different boards and then build a calendar view from the scheduled posts you have created.
Contract at a glance: POST {{API_BASE_URL}}/v1/posts
Scheduling uses a single endpoint: POST {{API_BASE_URL}}/v1/posts. Include the Pin description in content, a platforms entry for Pinterest with the connected accountId, and the Pinterest-specific details inside platformSpecificData. Add exactly one item to mediaItems for an image or video Pin, plus scheduledFor and, when you are scheduling against local time, timezone. A successful scheduling request returns HTTP 202 with success set to true, status set to scheduled, a postId you can store for later lifecycle operations, scheduledFor resolved in UTC, and a per-platform success entry. See the worked example titled Image Pin scheduling request and the response titled Image Pin scheduling response (202) for the exact request and response shapes.
Field map: content, platforms, accountId, platformSpecificData, boardId, mediaItems, scheduledFor, timezone
The field map titled Request and response fields separates required from optional fields and shows the Pinterest-specific constraints for each one. The most important checks before you send a request are that boardId is present, that mediaItems contains exactly one image or one video, and that the media URL is publicly accessible. If any of those checks fail, fix the payload before retrying rather than creating a duplicate scheduled Pin.
Worked image Pin example
The worked example titled Image Pin scheduling request shows a complete image Pin scheduled for 09:00 in America/Los_Angeles. The response titled Image Pin scheduling response (202) shows the same Pin confirmed as scheduled, with scheduledFor returned as 2026-09-15T16:00:00.000Z in UTC and a postId of post_xyz789. Use that postId as the reference for the queued Pin in your own calendar or queue view. To schedule a video Pin, keep the same endpoint and scheduling fields and change the single mediaItems entry to a video item that meets the video format and size limits described below.
Timezone handling: IANA timezone vs omitted/UTC
Timezone handling is the part of scheduling that most often causes a Pin to publish at the wrong hour. When you pass an IANA timezone such as America/Los_Angeles alongside scheduledFor, the service resolves that local time and returns the corresponding UTC publishing time in the response. When you omit timezone, scheduledFor is treated as UTC, so a value such as 2026-09-15T09:00:00 means 09:00 UTC, not 09:00 in your user's local zone. The decision table titled Timezone handling shows both cases. Always compare the UTC scheduledFor in the response against the local time you intended before you show the Pin as confirmed in your product.
Media and content limits
A scheduled Pinterest Pin must carry a single media item, either a still image or a moving image. Media-free Pins, carousels, and Pins bundling several images fall outside the supported set, so a payload with multiple mediaItems entries will not produce a carousel. Still images are accepted as JPG, PNG, or WebP up to 32 MB; moving images as MP4 or MOV up to 2 GB; and the URL supplied must be publicly reachable in both cases. Beyond the core description, a Pin may carry a title, an HTTPS destination link, alt text, a dominant colour, and a cover image URL when the media is video. The matrix titled Media and content limits lists the supported and unsupported cases so you can validate a payload before sending it.
Queue lifecycle: edit, reschedule, and cancel
Once a Pin is queued, you can edit it, change its publishing time, or cancel it before publication without recreating the Pin. The source describes a reschedule endpoint for changing the publishing time of a queued Pin and a cancel operation for removing it before publication, and it also describes listing scheduled posts to build a calendar view. However, the supplied source does not provide the endpoint paths, methods, parameters, or status contracts for reschedule, cancel, edit, or list operations, so this page does not invent them. Treat those operations as lifecycle capabilities whose exact contracts must be confirmed from their own documentation before implementation, and keep the postId from the scheduling response as the identifier you will need for them.
Cross-platform queuing and related capabilities
The same request can schedule compatible media for Pinterest and other supported platforms in one request, with every target sharing the same scheduledFor and timezone. That shared timing is useful when one campaign asset should go out across several networks at the same moment, but it also means a timezone mistake affects every target in the request. Pinterest posting and Pinterest analytics are adjacent capabilities for creating Pins and bringing performance data into a product or reporting workflow, but they are separate from scheduling and have their own contracts. Other platform scheduling pages cover Twitter / X, Instagram, Facebook, LinkedIn, TikTok, YouTube, Threads, Bluesky, and Google Business as scope boundaries, not as substitutes for the Pinterest-specific boardId and media rules on this page.
| Field | Required / optional | Type | Pinterest-specific notes |
|---|---|---|---|
| content | Required in example | string | Pin description; the main description field for the Pin. |
| platforms[].platform | Required in example | string | Use "pinterest" for a Pinterest target. |
| platforms[].accountId | Required in example | string | Identifies the connected Pinterest account, e.g. "pin_111". |
| platforms[].platformSpecificData.boardId | Required for every Pinterest Pin | string | Destination Pinterest board, e.g. "1143210755351402924". Every Pinterest Pin needs a board. |
| platforms[].platformSpecificData.title | Optional in example | string | Pin title, e.g. "10 Workspace Design Ideas". |
| platforms[].platformSpecificData.link | Optional in example | string | HTTPS destination link for the Pin. |
| mediaItems | Required in example | array | Exactly one image or one video item; text-only, carousel, and multi-image Pins are not supported. |
| mediaItems[].type | Required in example | string | "image" in the worked example; video Pins use a video item. |
| mediaItems[].url | Required in example | string | Publicly accessible media URL. |
| scheduledFor | Required for scheduling | string (ISO 8601) | Future publishing time, e.g. "2026-09-15T09:00:00". |
| timezone | Optional | string (IANA) | e.g. "America/Los_Angeles". If omitted, scheduledFor is treated as UTC. |
| Response: success | Returned on 202 | boolean | true for a scheduled Pin. |
| Response: status | Returned on 202 | string | "scheduled". |
| Response: postId | Returned on 202 | string | Identifier for the scheduled post, e.g. "post_xyz789". |
| Response: scheduledFor | Returned on 202 | string (UTC) | Resolved publishing time in UTC, e.g. "2026-09-15T16:00:00.000Z". |
| Response: platforms[].success | Returned on 202 | boolean | Per-platform success entry for Pinterest. |
Requiredness for boardId and the one-media rule is stated in the source FAQ; other requiredness follows the worked request/response example. Types are inferred from the example values.
| timezone value | How scheduledFor is interpreted | What the response returns | Example |
|---|---|---|---|
| IANA timezone provided, e.g. America/Los_Angeles | scheduledFor is a local time in that timezone | scheduledFor resolved to the corresponding UTC publishing time | scheduledFor "2026-09-15T09:00:00" with timezone "America/Los_Angeles" returns "2026-09-15T16:00:00.000Z" |
| timezone omitted | scheduledFor is treated as UTC | scheduledFor in UTC | scheduledFor "2026-09-15T09:00:00" means 09:00 UTC |
Based on source FAQ and worked example.
| Content type | Supported? | Formats | Size limit | Other constraints |
|---|---|---|---|---|
| Single image Pin | Yes | JPG, PNG, WebP | Up to 32 MB | Media URL must be publicly accessible |
| Single video Pin | Yes | MP4, MOV | Up to 2 GB | Media URL must be publicly accessible; cover image URL can be included for video Pins |
| Text-only Pin | No | — | — | Not supported |
| Carousel | No | — | — | Not supported |
| Multi-image Pin | No | — | — | Not supported; send exactly one mediaItems entry |
Based on source FAQ.
Frequently asked questions
How do I schedule a Pinterest Pin?
Create the Pin through POST {{API_BASE_URL}}/v1/posts. Supply the Pinterest accountId, the destination boardId, a single media item, and a future scheduledFor timestamp in ISO 8601 format. Include timezone when the intended moment is expressed in local time.
Does every Pinterest Pin need a board?
A board is mandatory. Every Pinterest Pin must carry platformSpecificData.boardId. Fetch the boards available to the connected account first, then use a valid identifier in the scheduling request.
How does timezone handling work?
Provide an IANA zone name, for example America/Los_Angeles, and the service converts that local moment into UTC for the response. Leaving timezone out means the scheduledFor value is read as UTC.
What Pinterest content can I schedule?
Only a lone image or a lone video qualifies. A Pin with no media, a carousel, or several images falls outside what this scheduling flow accepts.
What are the Pinterest media limits?
Still images may be JPG, PNG, or WebP and must stay within 32 MB. Moving images may be MP4 or MOV and must stay within 2 GB. In either case, the supplied URL needs to be reachable publicly.
What Pin details can I include?
Optional Pin-level details include a title, an HTTPS destination link, alt text, a dominant colour, and, for moving images, a cover image URL. Descriptive copy for the Pin is taken from the top-level content field.
Can I edit, reschedule, or cancel a scheduled Pin?
Queued Pins support later changes: revise the Pin, shift its scheduled time, or withdraw it ahead of publication. The source material does not disclose the paths, methods, parameters, or status codes for those operations, so confirm them from dedicated documentation before building against them.
Who is the Pinterest Scheduling API for?
The intended users are software developers, SaaS builders, agencies, automation creators, and AI-driven products that need to arrange social publishing programmatically, particularly teams wanting Pinterest delivery planned by board, date, and timezone without running their own queue.
{
"success": true,
"status": "scheduled",
"postId": "post_xyz789",
"scheduledFor": "2026-09-15T16:00:00.000Z",
"platforms": [
{
"platform": "pinterest",
"success": true
}
]
}