Documentation

Ship your first Pin in five minutes.

Authenticate, connect Pinterest, publish. Retries and webhooks are handled for you.

Base URL
https://api.pinbridge.io/v1

Authentication
Send your key in the X-API-Key header on every request.

Idempotency
Pass an idempotency_key so a retried publish is safe by default.

Authenticate

Create an API key in your dashboard, then send it as X-API-Key on every call. Each key is scoped to a single workspace and revokable from the dashboard.

verify.sh

# Verify your key against the rate-meter
curl https://api.pinbridge.io/v1/rate-meter \
  -H "X-API-Key: $PINBRIDGE_KEY"

Connect a Pinterest account

Send the user through managed OAuth. PinBridge stores and rotates their tokens. You never touch Pinterest credentials.

oauth.sh

# Returns a Pinterest consent URL to redirect the user to
curl https://api.pinbridge.io/v1/pinterest/oauth/start \
  -H "X-API-Key: $PINBRIDGE_KEY"

Publish a Pin

POST a Pin. PinBridge publishes it asynchronously with per-account rate handling and automatic retries.

cURL

curl -X POST https://api.pinbridge.io/v1/pins \
  -H "X-API-Key: $PINBRIDGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "board_id": "b_78f2a9",
    "image_url": "https://cdn.shop/img/1.jpg",
    "title": "Summer styles 2026",
    "idempotency_key": "launch-123"
  }'

Python SDK

from pinbridge import PinBridge

pb = PinBridge(api_key=PINBRIDGE_KEY)

pin = pb.pins.create(
    board_id='b_78f2a9',
    image_url='https://cdn.shop/img/1.jpg',
    title='Summer styles 2026',
)
print(pin.status)  # queued

Get notified with webhooks

Register a webhook once. PinBridge sends signed pin.published and pin.failed events. Delivery retries with exponential backoff until your endpoint returns 200.

webhook payload

{
  "event": "pin.published",
  "pin_id": "pin_8fa2",
  "board_id": "b_78f2a9",
  "status": "published"
}

API reference

The endpoints you will use.

API keys

POST/v1/api-keysCreate a key

GET/v1/api-keysList keys

DEL/v1/api-keys/{id}Revoke a key

GET/v1/pinterest/oauth/startBegin OAuth

GET/v1/pinterest/accountsList connected accounts

GET/v1/pinterest/boardsList boards

Pins

POST/v1/pinsPublish a Pin

GET/v1/pins/{id}Retrieve a Pin

GET/v1/pinsList Pins

Schedules

POST/v1/schedulesSchedule a Pin

POST/v1/schedules/{id}/cancelCancel a schedule

GET/v1/schedulesList schedules

Webhooks & usage

POST/v1/webhooksRegister a webhook

GET/v1/webhooksList webhooks

GET/v1/rate-meterLive rate-limit status

SDKs & integrations

Call it however you build.

Python SDK

An official, typed client. pip install pinbridge

n8n nodes

Drop PinBridge into any n8n canvas next to your existing HTTP Request and IF nodes.

MCP server

Let a Claude or agentic workflow publish Pins directly through the Model Context Protocol.

Grab a key. Start building.

Playground is free forever. Enough headroom to wire publishing end to end before you spend a cent.

Get your API key See pricing