Skip to content
PinBridge
Start free
Home / Docs / Docs

Pinterest API

GET /v1/pinterest/accounts

List Pinterest Accounts

List connected Pinterest accounts (limited to the API key’s allow-list, if any).

Auth: ApiKeyAuth, BearerAuth

Response 200

curl -X GET "https://api.pinbridge.io/v1/pinterest/accounts" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

DELETE /v1/pinterest/accounts/{account_id}

Revoke Pinterest Account

Revoke a Pinterest account connection.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
account_id path yes string

Response 204

curl -X DELETE "https://api.pinbridge.io/v1/pinterest/accounts/$ACCOUNT_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

GET /v1/pinterest/accounts/{account_id}/analytics

Get Account Analytics

Account-level analytics (impressions, engagement, saves, clicks) over a date range.

PinBridge copies every connected account’s analytics nightly, so most reads are
answered from that stored history (source: stored in the response, with
data_as_of) without calling Pinterest. Live ranges are capped at 90 days,
stored ranges at 366. Sandbox-simulated workspaces return zeroed metrics.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
account_id path yes string
start_date query no string? Inclusive start (YYYY-MM-DD); default 30 days ago
end_date query no string? Inclusive end (YYYY-MM-DD); default today
metrics query no string? Comma-separated Pinterest metric types, e.g. IMPRESSION,ENGAGEMENT,SAVE,PIN_CLICK,OUTBOUND_CLICK. Defaults to the organic engagement set.
source query no enum(auto, stored, live) auto (default): PinBridge’s stored history when it covers the range, else Pinterest. stored: stored history only (up to 366 days, beyond Pinterest’s 90). live: always ask Pinterest (counts against the read limit).
include_daily query no boolean false: return only the range totals, with an empty daily list. Use it when the totals are all you need, e.g. over 90 days.

Response 200 (AccountAnalyticsResponse)

curl -X GET "https://api.pinbridge.io/v1/pinterest/accounts/$ACCOUNT_ID/analytics" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

GET /v1/pinterest/boards

List Boards

List boards for a Pinterest account.

Returns a synthetic local board in sandbox simulation mode, otherwise proxies Pinterest.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
account_id query yes string Pinterest account ID

Response 200

curl -X GET "https://api.pinbridge.io/v1/pinterest/boards?account_id=$ACCOUNT_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

POST /v1/pinterest/boards

Create Board

Create a board for a connected Pinterest account.

SECRET needs Pinterest’s boards:write_secret scope. Connections made before
API 1.37 lack it and get 409 scope_missing until they reconnect.

Auth: ApiKeyAuth, BearerAuth

Request body (BoardCreateRequest)

Field Type Required Description
account_id string yes Pinterest account ID
name string yes Board name (max 180, min 1)
description string? no Board description
privacy string? no Board privacy (for example PUBLIC, PROTECTED, SECRET)

Response 201 (BoardResponse)

curl -X POST "https://api.pinbridge.io/v1/pinterest/boards" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Home decor ideas"}'

DELETE /v1/pinterest/boards/{board_id}

Delete Board

Delete a board on Pinterest, with every pin on it. Irreversible.

PinBridge’s published pins on the board keep their records and stored analytics
and are marked removed_from_pinterest_at. Deleting a secret board needs the
boards:write_secret scope (connections made before API 1.37 lack it).

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
board_id path yes string
account_id query yes string Pinterest account ID

Response 204

curl -X DELETE "https://api.pinbridge.io/v1/pinterest/boards/$BOARD_ID?account_id=$ACCOUNT_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

PATCH /v1/pinterest/boards/{board_id}

Update Board

Rename a board or change its description or privacy.

The change is made on Pinterest; fields left out are unchanged. Pins on the
board are unaffected.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
board_id path yes string

Request body (BoardUpdateRequest)

Field Type Required Description
account_id string yes Pinterest account that owns the board
name string? no New board name
description string? no New board description
privacy string? no New privacy (for example PUBLIC, SECRET)

Response 200 (BoardResponse)

curl -X PATCH "https://api.pinbridge.io/v1/pinterest/boards/$BOARD_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Autumn decor"}'

GET /v1/pinterest/boards/{board_id}/access

Get Board Access

Check whether an account can publish to a board right now.

Runs the same preflight POST /v1/pins uses and reports the outcome
instead of failing: publishable plus a stable code (board_not_found,
board_not_owned, board_deleted, scope_missing, token_expired,
board_access_denied, sandbox_board_not_allowed, …) and a remediation
hint. status: skipped means Pinterest was unavailable and only local
checks ran.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
board_id path yes string
account_id query yes string Pinterest account ID
fresh query no boolean Bypass the cached verdict and ask Pinterest again

Response 200 (BoardAccessResponse)

curl -X GET "https://api.pinbridge.io/v1/pinterest/boards/$BOARD_ID/access?account_id=$ACCOUNT_ID" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

GET /v1/pinterest/oauth/callback

Oauth Callback

Handle Pinterest OAuth callback.

Exchanges code for access token and stores account.

Parameters

Name In Required Type Description
code query no string? Authorization code from Pinterest
state query yes string State parameter for CSRF protection
error query no string? Set by Pinterest when access was refused

Response 200

curl -X GET "https://api.pinbridge.io/v1/pinterest/oauth/callback?state=$STATE"

GET /v1/pinterest/oauth/start

Start Oauth

Start Pinterest OAuth flow.

Returns authorization URL to redirect user to. Pass account_id when
reconnecting an account, so a workspace at its plan’s account limit can still
reconnect it.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
account_id query no string? When reconnecting, the connected account being reconnected. It does not count against the plan’s Pinterest account limit.

Response 200 (OAuthStartResponse)

curl -X GET "https://api.pinbridge.io/v1/pinterest/oauth/start" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

GET /v1/pinterest/terms/related

List Related Terms

List Pinterest related terms for a connected account.

Auth: ApiKeyAuth, BearerAuth

Parameters

Name In Required Type Description
account_id query yes string Pinterest account ID
terms query yes array Requested term(s). Supports repeated query params or a comma-separated value.
exact_match query no boolean When true, keep only related-term groups whose term exactly matches one of the requested terms values after trim/casefold normalization.

Response 200 (RelatedTermsResponse)

curl -X GET "https://api.pinbridge.io/v1/pinterest/terms/related?account_id=$ACCOUNT_ID&terms=$TERMS" \
  -H "X-API-Key: $PINBRIDGE_API_KEY"
Last updated October 29, 2026 Was this page helpful? Tell us →

Powered by
►
Necessary cookies enable essential site features like secure log-ins and consent preference adjustments. They do not store personal data.
None
►
Functional cookies support features like content sharing on social media, collecting feedback, and enabling third-party tools.
None
►
Analytical cookies track visitor interactions, providing insights on metrics like visitor count, bounce rate, and traffic sources.
None
►
Advertisement cookies deliver personalized ads based on your previous visits and analyze the effectiveness of ad campaigns.
None
Powered by