Pinterest supports Pins with one photo, 2 to 5 photos as a carousel, or one video, each on one of the account's boards. Every Pin needs a board and a photo or a video: there are no text-only Pins. The caption is the Pin's description, up to 800 characters, and an optional title and link go with it. Pinterest is rolling out, so not every Quegly account can connect it yet.
Media Constraints
| Constraint | Images | Videos |
|---|---|---|
| Formats | JPEG, PNG | MP4, MOV (MP4 with H.264 recommended) |
| Max file size | 20 MB | 500 MB |
| Max count per post | 5 | 1 |
| Duration | n/a | 4 seconds to 15 minutes |
| Aspect ratio | 2:3 recommended (1000 x 1500) | 9:16, 2:3 or 1:1 recommended |
| Text-only | Not supported | Not supported |
| Mix images + video | Not allowed | Not allowed |
Pinterest itself takes videos up to 2 GB; 500 MB is Quegly's upload limit. Formats, file sizes and the number of photos are checked before the post is saved, and a video's length by Pinterest when the post publishes.
Posting Behavior
One Photo
Posted as a standard Pin.
2-5 Photos
Posted as one carousel Pin, which people swipe through, in the order of media_ids.
One Video
Uploaded to Pinterest, which processes it first. Quegly makes the Pin once the video is ready, so a Pin never goes out without it; a video Pinterest is still processing after 6 minutes fails the post on Pinterest. Its cover is the video's thumbnail (see Uploads), or the video's first frame when it has none or Pinterest cannot use it.
Title and Link
The caption becomes the Pin's description. A title shows on the Pin above it, and a link is where the Pin takes people when they tap it. Quegly sends neither unless it is set.
Platform Settings
Under platform_settings.pinterest, and required on every post with a Pinterest account in account_ids: a Pin needs a board_id, the board it goes on. Without one, the post is refused with 400 VALIDATION_ERROR, drafts included. title and link are optional, and like every platform Pinterest also takes its own caption. Any other field there is ignored, without an error.
| Parameter | Type | Description |
|---|---|---|
board_id | string | The id of the board the Pin goes on, one of the connected account's boards: digits only, sent as a string, such as "549755885175". |
title | string | The Pin's title, shown above its description. Up to 100 characters; runs of spaces and line breaks become one space. |
link | string | Where the Pin takes people when they tap it: a web address (http or https), up to 2,048 characters. One written without https://, such as example.com/recipes, gets it in front. |
caption | string | Pinterest's own description, in place of the post's caption. Up to 800 characters. |
Finding a Board ID
GET /v1/pinterest/boards lists the connected account's boards, read live from Pinterest: { "boards": [{ "id": "549755885175", "name": "Summer recipes", "privacy": "PUBLIC" }] }.POST /v1/pinterest/boards with { "name": "..." } (up to 50 characters) makes a public board and returns it as { "board": { ... } }. Both answer 404 NOT_FOUND when the workspace has no Pinterest account connected. A board's web address shows its name, not its id, so use these. Quegly checks that board_id is digits before the post is saved. A board that is not the account's, or was deleted since, fails when the post publishes, with Pinterest's reason in that platform's error.
Updating a Post
On PUT /v1/posts/{id}, platform_settings replaces the post's settings as a whole, so send board_id again with any change to them.
Examples
{
"type": "schedule",
"scheduled_at": "2026-11-02T14:00:00.000Z",
"caption": "Four small living rooms, each styled on a weekend budget with paint, new lighting and a few thrifted pieces. Swipe for the before and after, and save the one you would copy first. #smallspaces #livingroomdecor #homedecor",
"media_ids": ["image-id-1", "image-id-2", "image-id-3", "image-id-4"],
"account_ids": ["pinterest-account-id"],
"platform_settings": {
"pinterest": {
"board_id": "549755885175",
"title": "Four small living rooms, styled on a weekend budget",
"link": "https://example.com/small-living-rooms"
}
}
}{
"type": "now",
"caption": "One weekend, one rental kitchen, no renovation. We swapped the cabinet handles, painted the backsplash tiles, added peel-and-stick shelving and changed every bulb to warm white. Every product is linked in our bio. Which change would you make first? #kitchenmakeover #rentalfriendly #homedecor",
"media_ids": ["video-id"],
"account_ids": ["instagram-account-id", "pinterest-account-id"],
"platform_settings": {
"pinterest": {
"board_id": "549755885175",
"caption": "A rental kitchen refreshed in one weekend, with no renovation: new cabinet handles, painted backsplash tiles, peel-and-stick shelving and warm white bulbs.",
"link": "https://example.com/rental-kitchen"
}
}
}Caption Rules
| Max length | 800 characters, the most a Pin's description holds. Longer captions are rejected before the post is saved. |
| Description | The caption is sent as written, as the Pin's description. It can be left out: a Pin needs a photo or a video, not text. |
| Title | Never taken from the caption: Quegly sends one only when title is set. |
Connection
| Rolling out | For now Pinterest is open to a first group of Quegly accounts. Until it reaches an account, the Manage page shows Pinterest as coming soon. As for every platform, the API posts only to a Pinterest account connected there. |
| Accounts | Personal and business Pinterest accounts connect on the Manage page, through Pinterest's own sign-in page. Quegly asks to see and make the account's boards and Pins, and to see its profile. It does not ask for secret boards, so it cannot post to them. |
| Name | The account's account_username is its Pinterest username, and its display_name is null. Reconnecting the same account keeps its account ID. |
| Renewal | The connection renews itself: Pinterest's access lasts 30 days, and Quegly renews it before it ends. If Pinterest refuses a renewal, for example after the access was removed in Pinterest's settings, the account switches off: it leaves GET /v1/accounts, and Pinterest posts fail until it is reconnected on the Manage page. |
Analytics
Pinterest gives a Pin's numbers to business accounts only: a personal account's Pins read 0 on every key. Quegly reads them from Pinterest's Pin analytics (GET /v5/pins/{id}/analytics). A Pinterest post's metrics carry views (impressions), likes (reactions), comments, saved (saves), post_clicks (clicks on the Pin) and url_link_clicks (clicks through to its link). Pinterest's numbers come in a day or two late, so Pinterest posts refresh at most every 6 hours on their first two days, then daily. Its post_url links to the Pin: https://www.pinterest.com/pin/123456789012345678/.