> ## Documentation Index > Fetch the complete documentation index at: https://kavenio.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Pinterest Posting API Documentation | Kavenio Docs > Connect Pinterest accounts, select boards, and publish image, video, and multi-image Pins. Review OAuth scopes, media limits, payloads, analytics, and errors. Kavenio publishes Pinterest Pins through connected Pinterest accounts. Use `pinterest` as the platform value and put Pin-specific fields in `platformSpecificData`. Pinterest Pins require media. Kavenio supports one image, one video, or a multi-image Pin containing two to five images. For a product-level overview, see the [Pinterest posting API](https://kavenio.com/platforms/pinterest) page. ## Quick Reference | Capability | Support | | --------------------- | ------------------------------------------------------------------------------ | | Platform key | `pinterest` | | Media | One image, one video, or two to five images | | Board | `platformSpecificData.boardId` or the connected account's default board | | Board section | Optional `platformSpecificData.boardSectionId` | | AI disclosure | Optional `platformSpecificData.aiDisclosures` | | Destination link | `platformSpecificData.link` | | Video upload | Kavenio uploads video to Pinterest, waits for processing, then creates the Pin | | Pre-uploaded video | `platformSpecificData.mediaId` | | Post analytics | `GET /v1/analytics` for impressions, saves, clicks | | Native edit/unpublish | Not supported | ## Connect And Select A Board Connect Pinterest through OAuth. Kavenio requests `user_accounts:read`, `boards:read`, `boards:write`, `pins:read`, and `pins:write` so the connected account can list boards and publish Pins. After connecting, list the account's boards and optionally store a default: ```bash theme={null} kavenio connect pinterest-boards --account-id acc_123 kavenio connect pinterest-select-board \ --account-id acc_123 \ --profile-id customer_user_123 \ --board-id 123456789 ``` Publishing can override the selected default with `platformSpecificData.boardId`. Use `boardSectionId` when a Pin should be added to a specific section within that board. ## Create An Image Pin ```json theme={null} { "content": "Ideas for a compact studio workspace.", "mediaItems": [ { "type": "image", "url": "https://cdn.example.com/workspace-pin.jpg", "mimeType": "image/jpeg", "altText": "Compact desk setup with storage shelves" } ], "platforms": [ { "platform": "pinterest", "accountId": "acc_123", "platformSpecificData": { "boardId": "123456789", "title": "Small Workspace Ideas", "link": "https://example.com/workspace-guide" } } ], "publishNow": true } ``` ```bash theme={null} kavenio posts create \ --content "Ideas for a compact studio workspace." \ --publish-now \ --media-url https://cdn.example.com/workspace-pin.jpg \ --platform pinterest:acc_123 \ --board-id 123456789 \ --title "Small Workspace Ideas" \ --link https://example.com/workspace-guide ``` The top-level `content` becomes the Pin description. `mediaItems[0].altText` or `platformSpecificData.altText` becomes Pinterest `alt_text`. ## Create A Video Pin ```json theme={null} { "content": "A short walkthrough of the setup.", "mediaItems": [ { "type": "video", "url": "https://cdn.example.com/workspace-tour.mp4", "mimeType": "video/mp4", "thumbnail": "https://cdn.example.com/workspace-cover.jpg" } ], "platforms": [ { "platform": "pinterest", "accountId": "acc_123", "platformSpecificData": { "boardId": "123456789", "title": "Workspace Tour", "link": "https://example.com/workspace-guide", "coverImageKeyFrameTime": 4 } } ], "publishNow": true } ``` For video Pins, Kavenio registers a Pinterest media upload, uploads the video, polls Pinterest processing status, and then creates the Pin with the returned media ID. ## Required Fields Pinterest targets require: * a connected Pinterest `accountId` * one image, one video, or two to five image media items * `platformSpecificData.boardId` or a selected default board on the connected account The media item title can be used as the Pin title when `platformSpecificData.title` is omitted. ## Platform-Specific Fields | Field | Type | Behavior | | ------------------------ | --------------- | --------------------------------------------------------------------------------- | | `boardId` | numeric string | Pinterest board ID. Usually provide this explicitly. | | `boardSectionId` | numeric string | Optional section within the selected board. | | `title` | string | Pin title, up to 100 characters. | | `link` | HTTPS URL | Destination URL, up to 2048 characters. URL shorteners are rejected. | | `coverImageUrl` | URL string | Custom cover image for video Pins. | | `coverImageKeyFrameTime` | integer seconds | Pinterest frame time used as the video cover when no cover image URL is supplied. | | `altText` | string | Pin alt text, up to 500 characters. | | `mediaId` | numeric string | Existing Pinterest video media ID. Skips Kavenio video upload. | | `aiDisclosures` | object | `values` may contain `AI_MODIFIED` and/or `SYNTHETIC_PERFORMER`. | Kavenio also accepts common compatibility aliases: `board_id`, `board`, `board_section_id`, `media_id`, `url`, `cover_image_url`, `thumbnailUrl`, `thumbnail_url`, `cover_image_key_frame_time`, `alt_text`, and `ai_disclosures`. ## Media Requirements Image Pins: * one `image`, or two to five `image` media items for a multi-image Pin * public URLs returning raw image bytes * BMP, JPEG, PNG, TIFF, or WebP * maximum file size 20 MB per image Video Pins: * exactly one `video` media item * MP4, MOV, or Pinterest-compatible M4V content type * maximum file size 2 GB * duration from 4 seconds to 5 minutes when duration metadata is supplied * aspect ratio from 1:2 through 1.91:1 when dimensions are supplied Media URLs must be public and must return the file bytes, not an HTML preview page. Kavenio rejects private, loopback, and localhost URLs before provider upload. ## Scheduling Use Kavenio's normal `scheduledFor` field. Kavenio fetches and uploads media when the scheduled job runs, so keep media URLs valid until publish time. ## Analytics Use the shared analytics endpoint for published Pinterest Pins: ```http theme={null} GET /v1/analytics?postId={postId} ``` Kavenio maps Pinterest impressions, saves, Pin clicks, and outbound clicks into the shared analytics response. ## Unsupported Cases Kavenio does not support these Pinterest actions through post publishing: * text-only Pins * GIF Pins * document Pins * Idea Pins * secret-board discovery and publishing (the connection requests only the public board and Pin scopes) * creating or deleting boards * native edit or unpublish after publication ## Common Errors | Error | Meaning | Fix | | -------------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- | | `Pinterest pin publishing requires one media item.` | No media was supplied. | Send one image/video or two to five images. | | `Pinterest multi-image pins require two to five images.` | A carousel mixes types or exceeds limits. | Send only two to five image items. | | `Pinterest boardId must be a numeric Pinterest ID.` | A display label or fake ID was supplied. | Use the numeric ID returned by Pinterest board discovery. | | `Pinterest publishing requires ... boardId ...` | No board was selected. | Set `platformSpecificData.boardId` or configure a default board. | | `Pinterest video pins must use MP4, MOV, or M4V media.` | The video MIME type is unsupported. | Host an MP4, MOV, or M4V file. | | `Pinterest destination link must be a valid HTTPS URL.` | The destination URL is invalid or not TLS. | Use a public HTTPS URL. | ## Official Pinterest API References * [OAuth authentication and scopes](https://developers.pinterest.com/docs/getting-started/set-up-authentication-and-authorization/) * [Creating boards, image Pins, and video Pins](https://developers.pinterest.com/docs/work-with-organic-content-and-users/create-boards-and-pins/) * [Pinterest analytics metrics](https://developers.pinterest.com/docs/analytics-and-reports/metrics-glossary/)