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.

Quickstart

1. 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 project (production or sandbox) and revokable from the dashboard. See the authentication guide for tokens, API keys, and password flows.

# Verify your key by listing connected accounts
curl https://api.pinbridge.io/v1/pinterest/accounts \
  -H "X-API-Key: $PINBRIDGE_API_KEY"

2. Connect a Pinterest account

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

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

3. Publish a pin

POST a pin. PinBridge publishes it asynchronously with per-account rate handling and automatic retries. account_id, board_id, title, idempotency_key, and exactly one of image_url / asset_id are required.

curl

curl -X POST https://api.pinbridge.io/v1/pins \
  -H "X-API-Key: $PINBRIDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41",
    "board_id": "987654321098765432",
    "image_url": "https://cdn.shop/img/1.jpg",
    "title": "Summer styles 2026",
    "idempotency_key": "launch-123"
  }'

Python SDK

from pinbridge_sdk import PinbridgeClient
from pinbridge_sdk.models import PinCreate

with PinbridgeClient(api_key="$PINBRIDGE_API_KEY") as client:
    pin = client.pins.create(
        PinCreate(
            account_id="6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41",
            board_id="987654321098765432",
            image_url="https://cdn.shop/img/1.jpg",
            title="Summer styles 2026",
            idempotency_key="launch-123",  # required
        )
    )
    print(pin.status)  # queued

Publishing from n8n instead? See PinBridge for n8n.

4. 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 a 2xx. The event type travels in the X-PinBridge-Event header, and the signature is in X-PinBridge-Signature.

// pin.published body
{
  "pin_id": "8a3f6c12-4d5e-4b7a-9c01-2e6f8d4b7a93",
  "pinterest_pin_id": "1234567890",
  "title": "Summer styles 2026",
  "published_at": "2026-09-11T12:00:00Z"
}

Explore the docs

• Getting started — authenticate, connect Pinterest, and publish your first pin.
• PinBridge for n8n — install the community node and build publishing flows, no code required.
• Guides — task-focused walkthroughs for publishing, scheduling, and bulk imports.
• MCP — publish from Claude, Codex, and any MCP client, plus the usage policy.
• Python SDK — a typed client with sync and async support.
• Limits & billing — plans, quota, credits, and rate limits.
• Reference — the full interactive OpenAPI reference for every endpoint.
• Troubleshooting — fixes for auth, publish, and delivery errors.

The endpoints you will use most

API keys

• POST /v1/api-keys — create a key
• GET /v1/api-keys — list keys
• DELETE /v1/api-keys/{key_id} — revoke a key

Pinterest

• GET /v1/pinterest/oauth/start — begin OAuth
• GET /v1/pinterest/accounts — list connected accounts
• GET /v1/pinterest/boards — list boards

Pins

• POST /v1/pins — publish a pin
• GET /v1/pins/{pin_id} — retrieve a pin (check its status)
• GET /v1/pins — list pins
• POST /v1/pins/{pin_id}/retry — retry a failed pin

Assets & imports

• POST /v1/assets/images — upload an image, then publish by asset_id
• POST /v1/assets/videos — upload a video
• POST /v1/pins/imports/json — bulk-import pins from JSON
• POST /v1/pins/imports/csv — bulk-import pins from CSV
• GET /v1/pins/imports/{job_id} — check an import job

Schedules

• POST /v1/schedules — schedule a pin
• POST /v1/schedules/{schedule_id}/cancel — cancel a schedule
• GET /v1/schedules — list schedules

Webhooks & usage

• POST /v1/webhooks — register a webhook
• GET /v1/webhooks — list webhooks
• GET /v1/rate-meter — live rate-limit status

Open the full interactive API reference for every endpoint.

Call it however you build

• Python SDK — an official, typed client. pip install pinbridge-sdk. See the Python SDK guide.
• n8n nodes — install the n8n-nodes-pinbridge community node and drop PinBridge into any n8n canvas next to your existing HTTP Request and IF nodes. See PinBridge for n8n.
• MCP server — let Claude, Codex, or any agentic workflow publish pins through the Model Context Protocol. See the MCP setup guide.

Grab a key. Start building.

Playground is free forever. Enough headroom to wire publishing end to end before you spend a cent. See pricing when you are ready to scale.