Pinterest Posting API Documentation | Kavenio Docs

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 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:

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

{
  "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
}

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

{
  "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:

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.

​Quick Reference

​Connect And Select A Board

​Create An Image Pin

​Create A Video Pin

​Required Fields

​Platform-Specific Fields

​Media Requirements

​Scheduling

​Analytics

​Unsupported Cases

​Common Errors

​Official Pinterest API References