# PinBridge

> PinBridge is a hosted Pinterest publishing API: managed OAuth, queueing, retries, status tracking, and signed webhooks. Use it through the REST API, the n8n community node, the MCP server, or the Python SDK.

## Getting started
- [PinBridge docs & quickstart](https://www.pinbridge.io/docs/): Ship your first Pinterest pin in five minutes: authenticate, connect Pinterest, publish, and get webhooks. Plus a map of every PinBridge docs section.
- [Core concepts](https://www.pinbridge.io/docs/core-concepts/): The PinBridge object model: organization, project, Pinterest account, board, asset, pin, schedule, and job, plus the pin state machine and idempotency.
- [Authentication](https://www.pinbridge.io/docs/authentication/): Authenticate with PinBridge using a JWT for user sessions or an API key for server-to-server calls. Register, log in, create keys, and handle auth errors.
- [Connect Pinterest](https://www.pinbridge.io/docs/connect-pinterest/): Connect a Pinterest account to PinBridge with OAuth, list connected accounts, reconnect an expired account, and revoke access. Plus why shared IPs are fine.
- [Sandbox](https://www.pinbridge.io/docs/sandbox/): Use the PinBridge sandbox to simulate publishing with fake pin IDs and no real Pinterest calls. Create a sandbox project, switch into it, reset it, and go live.

## n8n
- [PinBridge for n8n](https://www.pinbridge.io/docs/n8n/): Publish and schedule Pinterest pins from n8n with the PinBridge community node. Install on self-hosted n8n or n8n Cloud, connect your API key, and build flows.
- [Bulk import pins in n8n](https://www.pinbridge.io/docs/n8n/bulk-import/): Import many pins into PinBridge from Google Sheets or Airtable in n8n: Import JSON or Import CSV, check the job status, and re-run failed rows safely.
- [Set up your PinBridge credential in n8n](https://www.pinbridge.io/docs/n8n/credentials/): Create the PinBridge API Key credential in n8n: base URL, API key, the X-API-Key header, the built-in credential test, and self-hosted base URLs.
- [PinBridge n8n node reference](https://www.pinbridge.io/docs/n8n/node-reference/): Complete reference for the PinBridge n8n node: every resource, operation, parameter, and API endpoint, plus the client-side Limit quirk for list operations.
- [Publish your first pin with n8n](https://www.pinbridge.io/docs/n8n/publish-your-first-pin/): Step-by-step: add the PinBridge node in n8n, pick a connection and board, publish a pin from a public image URL, and verify it went live on Pinterest.
- [Schedule pins in n8n](https://www.pinbridge.io/docs/n8n/schedules/): Schedule a Pinterest pin for a future time from n8n with Schedule Create. Covers the ISO 8601 Run At field, timezone offsets, and unsupported fields.
- [Troubleshooting the PinBridge n8n node](https://www.pinbridge.io/docs/n8n/troubleshooting/): Fixes for common PinBridge n8n node problems: credential test failures, 401 invalid key, 422 missing account_id, binary property not found, and missing events.
- [Upload images and video in n8n](https://www.pinbridge.io/docs/n8n/upload-images-and-video/): Upload images and videos to PinBridge from n8n using a binary property, then publish a pin from the uploaded asset ID. Covers formats and video pins.
- [Receive pin events with a webhook in n8n](https://www.pinbridge.io/docs/n8n/webhook-results/): React to pin.published and pin.failed events in n8n. Use the generic Webhook node to receive events, register its URL with PinBridge, and verify the signature.

## Guides
- [Guides](https://www.pinbridge.io/docs/guides/): Task-based PinBridge guides: upload media, publish pins, schedule, bulk imports, webhooks, retries and failures, multiple accounts, team and roles, and.
- [Activity logs](https://www.pinbridge.io/docs/guides/activity-logs/): Audit your PinBridge project with the activity log API. Learn categories, per-plan retention (7 to 365 days), filters, and cursor pagination with examples.
- [Bulk imports (CSV and JSON)](https://www.pinbridge.io/docs/guides/bulk-imports/): Import up to 500 pins at once with PinBridge CSV and JSON imports. Learn the endpoints, required columns, per-row results, job statuses, dedupe, and retries.
- [Managing multiple Pinterest accounts](https://www.pinbridge.io/docs/guides/multiple-accounts/): Run many Pinterest accounts from one PinBridge project. See per-plan account limits, why agencies should consolidate on one plan, and shared-IP safety.
- [Publish pins](https://www.pinbridge.io/docs/guides/publish-pins/): Publish Pinterest pins with the PinBridge API: every PinCreate field, image and video media options, idempotency keys, and how to keep your title.
- [Retries and failures](https://www.pinbridge.io/docs/guides/retries-and-failures/): Understand the PinBridge pin state machine, automatic vs manual retries, deferrals, bulk retry, and the full failure error_code table with causes and fixes.
- [Schedule pins](https://www.pinbridge.io/docs/guides/schedule-pins/): Schedule Pinterest pins for a future time with the PinBridge API: run_at timestamps, schedule statuses, and cancel, retry, and delete (single or bulk).
- [Team and roles](https://www.pinbridge.io/docs/guides/team-and-roles/): Invite teammates to your PinBridge project and control access with owner, admin, operator, and client roles. Includes the full permission matrix and invite.
- [Upload media (images and videos)](https://www.pinbridge.io/docs/guides/upload-media/): Upload images and videos to PinBridge, reference them by asset_id when you publish, and learn the per-plan file-size limits and storage quotas.
- [Webhooks](https://www.pinbridge.io/docs/guides/webhooks/): Receive PinBridge pin.published and pin.failed webhooks: exact payloads, HMAC-SHA256 signature verification, retry behavior, and idempotent consumers.

## MCP
- [MCP](https://www.pinbridge.io/docs/mcp/): Use PinBridge from Claude, Codex, and other MCP clients. Connect the hosted MCP server, see the available tools, and follow the AI-publishing usage policy.
- [MCP setup — connect PinBridge to your AI assistant](https://www.pinbridge.io/docs/mcp/setup/): Add PinBridge to Claude in one click from the connector directory, or connect Claude Code, Codex, Cursor or any MCP client to the hosted server with an API key.
- [MCP usage policy — AI-assisted Pinterest publishing](https://www.pinbridge.io/docs/mcp/usage-policy/): How Pinterest's per-pin intent rule applies to AI-assisted publishing with PinBridge, which workflows are compliant, and how PinBridge stays in the rules.

## Python SDK
- [Python SDK](https://www.pinbridge.io/docs/python-sdk/): Install and use the PinBridge Python SDK: PinbridgeClient and AsyncPinbridgeClient setup, error classes, and recipes for publishing, uploads, and webhooks.

## Limits & billing
- [Rate limits & quotas](https://www.pinbridge.io/docs/rate-limits/): How PinBridge paces requests with token buckets, the monthly pin-creation quota by plan, and the 402 and 403 billing errors that enforce them.
- [Billing & credits](https://www.pinbridge.io/docs/billing/): How PinBridge billing works: plans and the monthly pin quota, what counts against it, credit packs and consumption order, upgrading, and cancel or resume.

## Reference
- [Error reference](https://www.pinbridge.io/docs/errors/): Every user-facing PinBridge API error, grouped by HTTP status (400, 401, 402, 403, 404, 409, 422, 429, 500, 503), with the cause and how to fix each one.
- [API reference](https://www.pinbridge.io/docs/api/): Complete PinBridge REST API reference, generated from the OpenAPI spec: endpoints, parameters, request and response schemas, and curl examples.

## Troubleshooting
- [Troubleshooting](https://www.pinbridge.io/docs/troubleshooting/): Fixes for common PinBridge problems: pins stuck or failed, disconnected accounts, 401/402/403 errors, video uploads, webhooks, shared IPs, and Pinterest.
- [My Pinterest account got disconnected](https://www.pinbridge.io/docs/troubleshooting/account-disconnected/): A token_expired or token_revoked error means PinBridge lost access to your Pinterest account. Reconnect the account to restore publishing, then retry pins.
- [401 Invalid API key](https://www.pinbridge.io/docs/troubleshooting/invalid-api-key-401/): A 401 Invalid API key means your key is missing, wrong, or in the wrong header. Send it in X-API-Key, use a project API key (not a session token), and test it.
- [My pin failed](https://www.pinbridge.io/docs/troubleshooting/my-pin-failed/): A failed pin carries an error_code and error_message that tell you why. Read them, fix the cause, and retry the pin with the PinBridge retry endpoint.
- [I'm not receiving webhooks](https://www.pinbridge.io/docs/troubleshooting/not-receiving-webhooks/): If webhook deliveries never arrive, check the webhook is enabled, your endpoint returns 2xx within 30s, you subscribed to a real event, and the signature.
- [My pin is stuck in queued](https://www.pinbridge.io/docs/troubleshooting/pin-stuck-in-queued/): A pin in queued or deferred is waiting for a worker or an automatic retry. Learn how PinBridge retries, when a stuck pin is auto-recovered, and when to act.
- [Pinterest changed my pin title](https://www.pinbridge.io/docs/troubleshooting/pinterest-changed-my-title/): PinBridge sent your title, but Pinterest re-scraped the destination page and replaced it with the page's OG or meta tags. Fix it with good OG tags.
- [403 plan_limit](https://www.pinbridge.io/docs/troubleshooting/plan-limit-403/): A 403 plan_limit or feature_unavailable means your plan caps a resource: Pinterest accounts, API keys, or a gated feature. See the per-plan limits and how.
- [402 quota_exceeded](https://www.pinbridge.io/docs/troubleshooting/quota-exceeded-402/): A 402 quota_exceeded means your monthly pin quota is used up. Wait for the reset, buy credits, or upgrade your plan. Learn how quota and credits work together.
- [Is it safe that PinBridge uses shared IPs?](https://www.pinbridge.io/docs/troubleshooting/shared-ips-safe/): Yes. Pinterest identifies your account by its OAuth token, not by IP address. Shared server IPs are expected for a registered API app and are not a risk.
- [My video upload failed](https://www.pinbridge.io/docs/troubleshooting/video-upload-failed/): A video upload can fail from an unsupported format, a plan-based size limit, the Free plan blocking uploads, or a full disk quota. Here is how to fix each.

## Other
- [Activity Logs API](https://www.pinbridge.io/docs/api/activity-logs/): PinBridge Activity Logs API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [API Keys API](https://www.pinbridge.io/docs/api/api-keys/): PinBridge API Keys API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Assets API](https://www.pinbridge.io/docs/api/assets/): PinBridge Assets API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Auth API](https://www.pinbridge.io/docs/api/auth/): PinBridge Auth API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Email Preferences API](https://www.pinbridge.io/docs/api/email-preferences/): PinBridge Email Preferences API reference: every endpoint with parameters, request and response schemas, required fields, and a runnable curl example.
- [Jobs API](https://www.pinbridge.io/docs/api/jobs/): PinBridge Jobs API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Pins API](https://www.pinbridge.io/docs/api/pins/): PinBridge Pins API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Pinterest API](https://www.pinbridge.io/docs/api/pinterest/): PinBridge Pinterest API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Projects API](https://www.pinbridge.io/docs/api/projects/): PinBridge Projects API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Rate Limiting API](https://www.pinbridge.io/docs/api/rate-limiting/): PinBridge Rate Limiting API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Schedules API](https://www.pinbridge.io/docs/api/schedules/): PinBridge Schedules API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Team API](https://www.pinbridge.io/docs/api/team/): PinBridge Team API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.
- [Webhooks API](https://www.pinbridge.io/docs/api/webhooks/): PinBridge Webhooks API reference: every endpoint with its parameters, request body and response schemas, required fields, and a ready-to-run curl example.