Quick Start - PinBridge

Overview

This guide walks you through a successful first publish flow:

Create/login user and get auth token
Connect a Pinterest account via OAuth
List connected account + boards
Create your first pin
Check status until published

PinBridge accounts can use the sandbox to test integrations before paying for live API pin creations.

Use base URL:

export API_BASE_URL="https://api.pinbridge.io"

SDK-First Development Workflow (Python)

If you are building backend jobs, scripts, or automation, use the official Python SDK instead of raw HTTP calls.

Install the SDK:

pip install pinbridge-sdk

Download complete example applications and scripts from the Python examples repository:

This example workflow covers:

authenticate
list boards and create a board
publish a pin
schedule a second pin

For SDK-specific methods and typed models, see the Python SDK guide. For downloadable examples, use Python examples.

Prerequisites

A PinBridge account
Sandbox access for integration testing
Public API access at https://api.pinbridge.io
A reachable image URL for your first pin

Quick health check:

curl "$API_BASE_URL/healthz"

1. Register or Login

curl -X POST "$API_BASE_URL/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Doe",
    "email": "you@example.com",
    "password": "your-strong-password"
  }'

curl -X POST "$API_BASE_URL/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-strong-password"
  }'

Copy access_token as ACCESS_TOKEN.

2. Start Pinterest OAuth

Request authorization URL:

curl "$API_BASE_URL/v1/pinterest/oauth/start" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response includes authorization_url.

Open that URL in your browser, approve access, and let Pinterest redirect back to PinBridge callback:

GET /v1/pinterest/oauth/callback?...

After successful callback, the account is connected.

3. List Accounts and Boards

3.1 Get connected Pinterest account ID

curl "$API_BASE_URL/v1/pinterest/accounts" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Copy one account id as ACCOUNT_ID.

3.2 List boards for that account

curl "$API_BASE_URL/v1/pinterest/boards?account_id=<ACCOUNT_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Copy a board id as BOARD_ID.

4. Publish Your First Pin

Create a unique idempotency key (any unique string works):

export IDEMPOTENCY_KEY="first-pin-$(date +%s)"

Create pin:

curl -X POST "$API_BASE_URL/v1/pins" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "account_id": "<ACCOUNT_ID>",
    "board_id": "<BOARD_ID>",
    "title": "My first PinBridge pin",
    "description": "Published from Quick Start tutorial",
    "link_url": "https://example.com",
    "image_url": "https://images.unsplash.com/photo-1545239351-1141bd82e8a6",
    "idempotency_key": "<IDEMPOTENCY_KEY>"
  }'

Response includes id (pin ID) and initial status (usually queued).

5. Track Pin Status

Poll until status becomes published or failed:

curl "$API_BASE_URL/v1/pins/<PIN_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Possible statuses:

queued
publishing
published
failed

You can also use the alias endpoint:

curl "$API_BASE_URL/v1/jobs/<PIN_ID>" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Optional: Configure Webhooks

To get async notifications instead of polling:

curl -X POST "$API_BASE_URL/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "url": "https://your-app.example/webhooks/pinbridge",
    "secret": "replace-with-strong-secret",
    "events": ["pin.published", "pin.failed"],
    "is_enabled": true
  }'

Troubleshooting

401 - invalid/missing auth token
404 Pinterest account not found - wrong account_id or account revoked
402 - billing/quota limit reached
500 - upstream/internal issue; retry with same idempotency_key

Quick Start Tutorial