Description

n8n-nodes-pinterest

A community-built Pinterest integration for n8n.

Automate Pinterest workflows, from content management to analytics.

n8n is a fair-code licensed workflow automation platform.

@sinehypernova-0718/n8n-nodes-pinterest brings Pinterest API operations into n8n workflows, letting you work with Pinterest resources through the workflow editor instead of manually constructing API requests.

✨ Features

• Pinterest API v5 integration — interact with supported Pinterest resources directly from n8n workflows.
• OAuth2 authentication — authorize API requests using Pinterest OAuth2 credentials.
• Native n8n interface — select resources, operations, and parameters through the workflow editor.
• Pin management — create, retrieve, list, update, delete, and save Pins, and manage product-tag associations.
• Board management — create, retrieve, list, update, and delete boards and board sections, and retrieve Pins associated with boards.
• Pin analytics — retrieve supported analytics metrics over specified date ranges.
• Media uploads — register, transfer, and track video uploads for video Pins, with optional processing polling.
• Pagination support — retrieve paginated results where supported by the relevant operation.

📁 Repository Structure

n8n-nodes-pinterest/
├── credentials/
│   └── PinterestOAuth2Api.credentials.ts
├── nodes/
│   └── Pinterest/
│       ├── constants.ts
│       ├── descriptions/
│       │   ├── BoardDescriptions.ts
│       │   ├── MediaDescriptions.ts
│       │   ├── PinDescriptions.ts
│       │   └── index.ts
│       ├── requests/
│       │   ├── board/
│       │   │   ├── .ts
│       │   │   └── index.ts
│       │   ├── media/
│       │   │   ├── .ts
│       │   │   ├── multipart.ts
│       │   │   ├── normalize.ts
│       │   │   ├── validateUploadUrl.ts
│       │   │   └── index.ts
│       │   ├── pin/
│       │   │   ├── .ts
│       │   │   └── index.ts
│       │   └── index.ts
│       └── Pinterest.node.ts
├── package.json
├── README.md
└── LICENSE.md

Architecture

• credentials/ — defines the Pinterest OAuth2 credentials used to authenticate requests.
• constants.ts — defines shared Pinterest API configuration, such as the API base URL.
• descriptions/ — contains resource and operation definitions displayed in the n8n editor. Its index.ts explicitly exports the descriptions consumed by the main node.
• requests/board/ — contains request builders for Pinterest Board operations.
• requests/media/ — contains the Media request builders plus the multipart encoder, upload URL validation, and response normalization used by the video upload flow.
• requests/pin/ — contains request builders for Pinterest Pin operations.
• requests//.ts — keeps individual API request builders in separate operation-specific modules, such as create.ts, get.ts, list.ts, and update.ts.
• Resource index.ts files — explicitly export the request builders belonging to each resource.
• requests/index.ts — re-exports the resource-level barrels, providing a single import entry point for request modules.
• Pinterest.node.ts — defines the n8n node and coordinates operation execution, authenticated API requests, media storage transfers, pagination, and error handling.

The architecture separates editor-facing configuration from API request construction and execution. Resource descriptions define the available operations and parameters, while request modules build operation-specific requests. The main node remains responsible for invoking authenticated HTTP requests through n8n’s credential-aware helpers, transferring media files to the storage URL returned by Pinterest, and handling execution results.

Explicit exports keep imports predictable and avoid unnecessary wildcard exports. The resource-specific modules remain independent, while the barrel files provide convenient entry points without introducing another execution layer.

Additional resources can follow the same structure, with their own descriptions and operation-specific request modules. This allows the integration to expand without requiring a redesign of the existing architecture.

📦 Installation

Install the package through your n8n instance using the community node installation interface.

1. Open your n8n instance.
2. Navigate to Settings → Community Nodes.
3. Select Install.
4. Enter the package name @sinehypernova-0718/n8n-nodes-pinterest.
5. Review and accept the installation confirmation.
6. Once installation completes, open a workflow and search for the Pinterest node.

For detailed instructions, see the n8n community nodes installation guide.

> Note: The package name entered during installation must match the name under which this project is published to npm (@sinehypernova-0718/n8n-nodes-pinterest). Community node installation availability also depends on your n8n deployment configuration and administrator policies.

⚙️ Operations

The Pinterest node exposes supported Pinterest API operations through n8n’s resource and operation selectors. The available operations and parameters depend on the installed package version.

Pins

The Pin resource supports operations for managing Pins and retrieving their associated information.

| Operation | Description |
|—|—|
| Add Product Tags | Add product Pins as tags to a hero Pin. |
| Create | Create a Pin using the supported Pinterest API parameters. |
| Get | Retrieve an individual Pin by its ID. |
| Get Multiple Pin Analytics | Retrieve analytics for multiple Pins in a batch request, using the supported analytics metrics and date range. |
| List | List Pins with supported filters and pagination. |
| List Product Tags | List the product-tag associations on a hero Pin. |
| Update | Update supported fields of an existing Pin. |
| Delete | Delete a Pin by its ID. |
| Remove Product Tags | Remove product-tag associations from a hero Pin without deleting Pins or products. |
| Save | Save a Pin to a board. |
| Get Analytics | Retrieve analytics for a Pin using supported metrics and date parameters. |

Product tags attach product Pins to a hero Pin. Add Product Tags and Remove Product Tags each accept a hero Pin ID and a comma-separated list of 1–24 product Pin IDs per request. These inputs are Pin IDs, not catalog item IDs. For Add Product Tags, Pinterest rejects duplicate pin_id values and applies eligibility checks; if any product Pin is ineligible, the entire request fails (all-or-nothing). Adding a Pin that is already tagged is a no-op success. List Product Tags returns the Pin IDs currently tagged to the hero Pin, or an empty array if there are none, and is not paginated. Remove Product Tags removes only the tag associations and returns HTTP 204 with no response body on success. Removing a tag that is not present is a no-op success. It does not delete the hero Pin, the product Pins, or any catalog products.

Pinterest documents these IneligibleProductTagReason values for Add Product Tags: PINMISSING, PINISPRIVATE, PRODUCTMETADATAMISSING, PINNOTFROMVERIFIEDDOMAIN, and PINNOTFROMSAMEUSERASHEROPIN. A failed eligibility check returns HTTP 400 with the affected pinid and its errormessage.

Board

| Operation | Description |
|—|—|
| Create | Create a new board. |
| Create Board Section | Create a new board section. |
| Delete | Delete a single board. |
| Delete Board Section | Delete a single board section. |
| Get | Get a single board. |
| List | List boards. |
| List Board Sections | List sections of a board. |
| List Pins | List Pins on a board. |
| List Pins on Board Section | List Pins on a board section. |
| Update | Update a single board. |
| Update Board Section | Update a single board section. |

Media

The Media resource supports Pinterest’s media upload endpoints for video Pins. Image uploads and Media Library operations are not implemented.

| Operation | Description |
|—|—|
| Get Upload | Retrieve the status of a media upload by its numeric media ID. |
| List Uploads | List media uploads with bookmark pagination. |
| Upload Video | Register a video upload, transfer the file to Pinterest media storage, and optionally wait for processing. |

Upload Video reads a video from an n8n binary property and supports MP4, M4V, and MOV files up to 512 MB. The node registers the upload, sends the file directly to Pinterest’s media storage, and then checks the upload status. When Wait for Processing is enabled, the node polls Pinterest until the video finishes processing, fails, or the configured timeout is reached. The upload URL and temporary upload credentials returned by Pinterest are never included in node output or error messages.

Uploading a video does not create a Pin by itself. Use the returned media_id with the Pin resource to create a video Pin. Media uploads use the existing pins:read and pins:write scopes; no additional credential scopes are required.

The List operation for Pins supports Return All and Limit. The board listing operations (List, List Pins, List Board Sections, and List Pins on Board Section) follow Pinterest’s pagination bookmarks and return all pages. List Uploads follows bookmark pagination and supports Return All and Limit. Pin, board, board section, and media IDs are numeric identifiers; operations that look up a resource by ID expect digits only.

Operation parameters, filters, pagination behavior, and available analytics metrics vary by endpoint. Refer to the operation descriptions in the n8n editor and the Pinterest API v5 documentation for endpoint-specific requirements.

This list describes the resources currently implemented in the integration. Additional resources and operations can be introduced in future releases.

🔐 Credentials

The Pinterest node uses OAuth2 authentication to make authorized requests to the Pinterest API v5.

Prerequisites

Before configuring the credentials, you need:

• A Pinterest account.
• A developer application registered through the Pinterest Developers Portal.
• The client ID and client secret issued for your application.
• Appropriate API access and permissions for the operations you intend to use.

Pinterest controls application access and approval. Registering a developer application does not automatically grant unrestricted access to every API endpoint.

Configure OAuth2 credentials

Create a Pinterest OAuth2 API credential in n8n and supply the values required by the credential configuration.

| Setting | Value |
|—|—|
| Grant type | Authorization Code |
| Authorization URL | https://www.pinterest.com/oauth/ |
| Access token URL | https://api.pinterest.com/v5/oauth/token |
| Client ID | The client ID issued for your Pinterest application |
| Client secret | The client secret issued for your Pinterest application |
| Scopes | user_accounts:read, boards:read, boards:write, pins:read, pins:write |

Configure the OAuth redirect URL using the callback URL supplied by n8n. Register that URL with your Pinterest application wherever required by Pinterest’s developer configuration.

Save the credential and use n8n’s authorization flow to connect your Pinterest account. Once authorization succeeds, select the credential in the Pinterest node.

Permissions and access

The configured scopes cover the board, Pin, media upload, and product-tag operations used by the current implementation. The useraccounts:read scope supports the credential check against the GET /v5/useraccount endpoint. Individual operations may still require specific permissions, resource access, or additional API eligibility.

Pin analytics availability and supported metrics are subject to Pinterest’s API requirements. Application approval status, access restrictions, and Pinterest-side changes can affect whether an operation succeeds.

Keep your client secret and access tokens private. Never commit credentials to the repository or include tokens in issue reports, screenshots, or logs.

🧩 Compatibility

This package is designed for n8n’s community node ecosystem and uses the n8n node API.

• Integration type: n8n community node.
• Implementation language: TypeScript.
• API: Pinterest API v5.
• Authentication: OAuth2.
• Package distribution: npm — published by GitHub Actions with npm provenance.
• Development package manager: pnpm — pinned through the packageManager field in package.json and pnpm-lock.yaml.

The package declares its n8n node metadata and entry points in package.json. Compatibility depends on the n8n version, the available n8n-workflow APIs, and the package’s dependencies.

Refer to the repository’s package metadata and release notes when evaluating compatibility with a particular n8n version.

The 0.1.x releases are pre-1.0 releases. Operation coverage and compatibility may evolve as the integration develops.

🛠️ Development

Requirements

• Node.js (v22 or higher) and pnpm
• git
• Corepack (optional) — pnpm 12.4.2 is pinned in package.json via the packageManager field

corepack enable
pnpm install

Available scripts

| Script | Description |
| — | — |
| pnpm run dev | Start n8n with the Pinterest node and watch for changes. |
| pnpm run build | Compile TypeScript to JavaScript for production. |
| pnpm run build:watch | Build in watch mode. |
| pnpm run lint | Check code for errors and style issues. |
| pnpm run lint:fix | Automatically fix lint issues where possible. |
| pnpm run release:local | Create a local release: bump the version, update the changelog, commit, tag (vX.Y.Z), and push. |
| pnpm run release | The GitHub Actions publish entry point; builds and publishes to npm with provenance. |

> Note: Use pnpm run release:local to create and push a release tag. The repository’s .release-it.json configures the master branch, the vX.Y.Z tag format, and changelog generation.

Release process

Releases are published by GitHub Actions, never from a local machine, so every published version carries an npm provenance attestation (required by n8n for verified community nodes).

1. Make sure master is up to date and the working tree is clean.
2. Run pnpm run release:local. It lints, builds, prompts for a version bump, updates CHANGELOG.md, commits, creates a vX.Y.Z tag, and pushes it.
3. The tag push triggers .github/workflows/publish.yml, which checks out the tag, verifies it matches package.json, checks whether the version is already on npm, and publishes it with provenance.

> Note: release-it also creates a GitHub release and needs a GITHUBTOKEN with repo scope (for example, export GITHUBTOKEN=$(gh auth token)). Without it, release-it opens the GitHub release page in a browser.

Required repository configuration

• A repository secret named NPM_TOKEN holding an npm granular access token with read and write publish permission for @sinehypernova-0718/n8n-nodes-pinterest.
• The default branch must be master; CI and the publish workflow are configured for it.
• @n8n/node-cli version 0.23.0 or later is required for npm provenance support.

🚀 Usage

After installing the node and configuring OAuth2 credentials, you can incorporate Pinterest API operations into your n8n workflows.

Basic workflow setup

1. Create a workflow in n8n.
2. Add the Pinterest node.
3. Select your Pinterest OAuth2 credential.
4. Choose the resource you want to work with, such as Pin, Board, or Media.
5. Select the required operation.
6. Configure its parameters, IDs, filters, and other required fields.
7. Connect the node to the other nodes in your workflow.
8. Execute the workflow and inspect the returned data.

Creating a video Pin

Video Pins require a video upload before the Pin itself is created.

1. Add a node that provides the video as binary data, such as an HTTP Request or file storage node.
2. Add the Pinterest node and choose Media → Upload Video.
3. Set Binary Property to the property that contains the video, and configure Wait for Processing if needed.
4. Execute the node. The output includes the mediaid, mediatype, and processing status.
5. Add another Pinterest node and choose Pin → Create.
6. Set Media Source Type to Video ID, then set Media ID to the uploaded mediaid, for example {{ $json.mediaid }}.
7. Provide a Cover Image URL (Pinterest requires a valid cover image for video Pins), then execute the Pin creation.

Troubleshooting

If an operation fails:

• Verify that the Pinterest credential is authorized.
• Confirm that your application has the required API access and scopes.
• Check that the supplied resource IDs exist and are accessible to the connected account.
• Verify required fields and supported parameter values.
• Review the error returned by n8n and consult the relevant Pinterest API documentation.

For general workflow guidance, see the n8n Try it out documentation.

🔗 Resources

• Pinterest Developers Portal — manage developer applications and API access.
• Pinterest API v5 documentation — API endpoints, request parameters, responses, and permissions.
• n8n community nodes documentation — community node discovery and installation.
• n8n community nodes installation guide — installation instructions.
• n8n documentation — workflow creation and node configuration.
• GitHub repository — source code, issues, and contributions.

📝 Version history

0.1.2

Adds video media uploads and product-tag management to the Pinterest integration for n8n.

• Adds the Media resource with Upload Video, Get Upload, and List Uploads operations.
• Supports MP4, M4V, and MOV video uploads up to 512 MB, with optional processing polling and sanitized upload responses.
• Adds Add Product Tags, List Product Tags, and Remove Product Tags operations to the Pin resource.
• Validates hero and product Pin IDs locally, rejects empty product Pin IDs, and enforces the 1–24 limit and duplicate rejection for Add Product Tags.
• Documents product-tag eligibility rejection codes and association-only removal semantics.
• Adds bookmark pagination for media upload listings.
• Updates release automation, publish workflow handling, node metadata, and brand assets.
• Expands README documentation for media uploads, product tags, permissions, and release details.

This release extends the integration with video media handling and Pin product-tag management while preserving the existing resources and operations.

0.1.1

Adds board section management to the Pinterest integration for n8n.

• Adds Create Board Section, Delete Board Section, Update Board Section, and List Board Sections operations.
• Adds List Pins on Board Section to retrieve Pins associated with a board section.
• Includes pagination for the new board section listing operations where implemented.

This release extends the Board resource with board section management while preserving the existing integration structure.

0.1.0

Initial pre-1.0 release of the Pinterest integration for n8n.

• Introduces Pin and Board resources.
• Adds OAuth2 authentication for Pinterest API requests.
• Includes Pin creation, retrieval, listing, updating, deletion, saving, and analytics operations.
• Includes Board creation, retrieval, listing, updating, deletion, and listing Pins associated with a board.
• Includes pagination and operation-specific request handling where implemented.

This release establishes the initial integration structure, with further Pinterest resources and operations available for future development.

📄 License

This project is licensed under the MIT License.

—

This is an independent community project and is not an official Pinterest or n8n product.