Publish your first pin with n8n

This walkthrough publishes a single pin from a public image URL. It is the fastest way to confirm your setup end to end, and it works on the Free (Playground) plan because it uses a public image, not an uploaded asset.

Prerequisites

• The PinBridge node installed and a credential saved. See Set up your PinBridge credential.
• A Pinterest account connected in PinBridge, with at least one board.
• A public image URL. Pinterest prefers tall images (a 2:3 ratio, for example 1000×1500).

Steps (n8n)

1. Add the node. In your workflow, add a PinBridge node.
2. Select the credential. Choose your PinBridge API Key credential.
3. Pick the resource and operation. Set Resource to Pin and Operation to Publish.
4. Pick the Connection. Open the Connection dropdown. The node loads your connected Pinterest accounts. Select the one to publish with. (This maps to account_id.)
5. Pick the Board. Open the Board dropdown. The node loads boards for the selected connection. Choose your target board. (This maps to board_id.)
6. Set the Media Source. Set Media Source to Public Image URL, then paste your image into the Image URL field.
7. Set the Title. Enter a Title (max 100 characters). Pinterest may re-scrape your destination page and override the title with the page’s Open Graph tags, so set good OG tags on the linked page if you use a Link URL.
8. Leave the Idempotency Key default. The Idempotency Key field is prefilled with the expression ={{$execution.id + "-" + $itemIndex}}. Keep it. It is required and it stops the same pin being created twice if the workflow re-runs. Each input item gets its own key.
9. Execute the node. Click Execute node (or run the workflow). The node calls POST /v1/pins and returns the created pin.

Optional fields you can add on Publish: Description (max 800), Link URL (max 2048), Alt Text (max 500), Related Terms (comma-separated), and Dominant Color (hex).

Steps (curl)

The same request from the command line:

curl -sS -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",
    "title": "My first PinBridge pin",
    "image_url": "https://placehold.co/1000x1500.png",
    "idempotency_key": "first-pin-001"
  }'

Expected response (trimmed):

{
  "id": "…",
  "status": "queued",
  "account_id": "6f1c2e4a-3b7d-4c9e-8a21-5d0f9b3e7c41",
  "board_id": "987654321098765432",
  "title": "My first PinBridge pin"
}

Steps (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",
            title="My first PinBridge pin",
            image_url="https://placehold.co/1000x1500.png",
            idempotency_key="first-pin-001",
        )
    )
    print(pin.id, pin.status)

Verify it worked

A new pin starts as queued, then moves to publishing, then published. To check status in n8n, add a second PinBridge node set to Pin → Get (or Pin → Get Status), and set Pin ID to ={{$json["id"]}} so it reads the id from the Publish node’s output. When status is published, the pinterest_pin_id field is filled and the pin is live. If status is failed, read error_code and see Troubleshooting.

Importable sample workflow

An importable example lives at samples/n8n/publish-first-pin.json. Import it in n8n via Workflows → Import from File. It contains:

1. A Manual Trigger node to run the flow on demand.
2. A Set node that defines imageUrl, title, and linkUrl so you can edit inputs in one place.
3. A PinBridge node set to Pin → Publish: Connection and Board selected from the dropdowns, Media Source = Public Image URL, Image URL and Title bound to the Set node’s fields, and the default Idempotency Key expression left in place.
4. A PinBridge node set to Pin → Get with Pin ID = ={{$json["id"]}} to read back the published status.

After import, open the PinBridge nodes, attach your credential, and pick your Connection and Board.

Next steps

• Upload images and video — publish from uploaded assets instead of a URL.
• Schedule pins — publish at a future time.
• Node reference — every parameter for Pin → Publish.