PinBridge

API Reference

Pins

Create, list, import, fetch, and delete pin publishing resources.

Overview

Use pins APIs for direct publishing and asynchronous bulk imports. Pin payloads support Pinterest metadata and video cover image options.

What You Will Learn

  • Validation limits: title <= 100, description <= 800, alt_text <= 500, link_url <= 2048.
  • Media rules: provide exactly one of image_url or asset_id.
  • Video cover rules: provide at most one of cover_image_url or cover_image_asset_id; otherwise first frame is used.

Implementation Checklist

  • Validate account and board IDs before publishing.
  • Use idempotency_key per intended publish action.
  • Use asset_id for local uploads and video pins.
  • Optionally pass cover_image_url or cover_image_asset_id for video pins.
  • Poll pin or import-job status endpoints until terminal states.

Relevant Endpoints

POST
/v1/pins

Create and queue a new pin publish job.

GET
/v1/pins

List pins for the active workspace.

GET
/v1/pins/{pin_id}

Fetch one pin resource and status.

DELETE
/v1/pins/{pin_id}

Delete or soft-delete a pin.

POST
/v1/pins/imports/json

Create an async import job from JSON rows.

POST
/v1/pins/imports/csv

Create an async import job from CSV upload.

GET
/v1/pins/imports

List import jobs with filters/pagination.

GET
/v1/pins/imports/{job_id}

Fetch one import job and row-level results.

Example

curl -X POST "$API_BASE_URL/v1/pins" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "<ACCOUNT_ID>",
    "board_id": "<BOARD_ID>",
    "title": "Spring Launch",
    "description": "Seasonal launch pin",
    "alt_text": "Lifestyle scene featuring the Spring collection",
    "related_terms": ["spring", "lifestyle"],
    "dominant_color": "#6E7874",
    "link_url": "https://example.com/product",
    "image_url": "https://example.com/image.jpg",
    "idempotency_key": "spring-launch-2026-03-06"
  }'

Related Guides

Assets and UploadsJob Status