Pins

Create Pin

Create and publish a pin.

The pin is queued for publishing and processed asynchronously. Use idempotency_key to prevent duplicate pins.

Before the pin is accepted PinBridge checks that the connected account can publish to the board. Failures return 422 with a stable error.code (board_not_found, board_not_owned, board_deleted, scope_missing, token_expired, token_revoked, board_access_denied, ...) and a remediation hint.

Every response carries X-PinBridge-Quota-* and X-Pinterest-RateLimit-* headers describing the remaining headroom. To check a request without publishing, use POST /v1/pins/validate.

post/v1/pins

Request

  • Base URL: https://api.pinbridge.io (the document declares no server; this is the origin it was published from)
  • URL: https://api.pinbridge.io/v1/pins
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Headers

x-api-keystring nullable
authorizationstring nullable

Request body

account_idstring uuid required

Pinterest account ID to publish with

board_idstring required

Pinterest board ID

titlestring required

Pin title

descriptionstring nullable

Pin description

related_termsstring[] nullable

Optional related terms for Pinterest

alt_textstring nullable

Alternative text used for accessibility

dominant_colorstring nullable

Dominant hex color of the pin media (for example #6E7874)

cover_image_urlstring uri nullable

Optional public cover image URL for video pins

cover_image_asset_idstring uuid nullable

Optional uploaded image asset ID used as a video cover image

link_urlstring uri nullable

Destination URL for the pin

image_urlstring uri nullable

Public URL of the image to pin

asset_idstring uuid nullable

Uploaded PinBridge asset ID to use for the pin image or video

idempotency_keystring required

Idempotency key to prevent duplicate pins

Response

Successful Response

idstring uuid required
workspace_idstring uuid required
pinterest_account_idstring uuid required
status'queued' | 'deferred' | 'publishing' | 'published' | 'failed' required

Pin status enum.

media_type'image' | 'video' required

Pin media type enum.

titlestring required
descriptionstring nullable
related_termsstring[] nullable
alt_textstring nullable
dominant_colorstring nullable
cover_image_urlstring nullable
link_urlstring nullable
media_urlstring required
image_urlstring required
asset_idstring uuid nullable
board_idstring required
pinterest_pin_idstring nullable
error_codestring nullable
error_messagestring nullable
idempotency_keystring required
created_atstring date-time required
updated_atstring date-time required
published_atstring date-time nullable
failed_atstring date-time nullable

When the pin failed; set only while status is failed and cleared by a retry, like error_code

removed_from_pinterest_atstring date-time nullable

When PinBridge found that this published pin no longer exists on Pinterest (deleted there by hand or with its board). The pin keeps status published; null means it is live or has not been checked.

Changes

No recorded changes to this operation across all 1 revision of this API.