Description

n8n-nodes-plutio-mates


> 0.3.0+ note: This fork’s node is now called Plutio (MATES) with credential Plutio (MATES) API (was Plutio / Plutio API in 0.2.0). The rename allows side-by-side install with the original n8n-nodes-plutio. See CHANGELOG.md for migration.

An n8n community node for Plutio — full coverage of the Plutio public API v1.11.

This is a hard fork of Chykalophia/n8n-nodes-plutio, extended by MATES Incorporated to cover every documented Plutio v1.11 resource. The original repo covered Tasks, Projects, Comments, Invoices, Companies and People; this fork brings it up to ~40 resources.

Features

• Bumped to API v1.11 (was v1.10)
• Per-execution OAuth2 token caching — avoids burning rate limit on duplicate /oauth/token calls
• Pagination helper — Return All toggle on every list operation, automatic skip/limit paging
• MongoDB-style filtering — pass q JSON to use Plutio’s $regex, $or, $and, $elemMatch, $gte, $lte, $in, $size operators
• Full coverage of every documented Plutio v1.11 resource

Resources

| Group | Resources |
|—|—|
| Workspace | Workspace, Custom Field, Profile, Role |
| People & Companies | Person, Company |
| Projects & Tasks | Project, Task Board, Task Group, Task, Status |
| Tracking | Time Entry, Category |
| Scheduling | Scheduler, Event |
| Finance | Invoice, Invoice Subscription, Transaction, Proposal |
| Documents | Contract, Form, Form Response, Template, Section, Block |
| Content | Snippet, Note, Item, Wiki, Wiki Page |
| Files | Folder, File |
| Messaging | Conversation, Messenger, Comment |
| Dashboards | Dashboard, Dashboard Page, Dashboard Data |
| System | Archive, Trash |

Operations

For each resource, the node exposes the verbs supported by that resource’s endpoint:

Get Many, Get, Create, Update, Delete, Archive, Move, Copy, Bulk Update, Bulk Delete, Bulk Archive

Plus an “Additional Fields (JSON)” escape hatch on Create/Update so you can send any field the Plutio API accepts that’s not already exposed in the form UI.

Install

n8n Cloud / Desktop UI

Settings → Community Nodes → Install → enter:

n8n-nodes-plutio-mates

Self-hosted (Docker)

FROM n8nio/n8n
USER root
RUN npm install -g n8n-nodes-plutio-mates
USER node

Or set N8NNODESINCLUDE to ["n8n-nodes-plutio-mates"].

Self-hosted (npm)

cd ~/.n8n
npm install n8n-nodes-plutio-mates

Then restart n8n.

Self-hosted (direct from GitHub — no npm account needed)

cd ~/.n8n
npm install github:jackmates/n8n-nodes-plutio

Then restart n8n. Use this if you haven’t published to npm yet.

Credentials

In Plutio: Settings → API → Create Application. You’ll get a Client ID and Client Secret.

In n8n, create a new “Plutio API” credential with:

• Business (Subdomain) — e.g. matesincorporated for matesincorporated.plutio.com
• Client ID
• Client Secret

The node uses the OAuth 2 client_credentials grant. Tokens are cached per-execution and refreshed automatically.

Filtering with q

Plutio’s GET endpoints accept a MongoDB-style query in the q param. This node exposes that as the Filter (q, JSON) field on every Get Many operation.

Examples:

// All incomplete tasks assigned to a person
{"$and":[{"status":"incomplete"},{"assignedTo":"PERSON_ID"}]}
// Tasks containing "website" in the title (case-insensitive)
{"title":{"$regex":"website","$options":"i"}}
// Records matching a custom field value
{"customFields":{"$elemMatch":{"id":"FIELDID","value":"your value"}}}
// Date range
{"dueDate":{"$gte":"2026-01-01T00:00:00.000Z","$lte":"2026-12-31T23:59:59.000Z"}}

Custom fields

Custom field values live in a customFields array on each record. Pass them as JSON when creating/updating:

[
  { "_id": "EN5secC9M8FNcGF2f", "type": "text", "value": "PT123456789" }
]

The custom field _ids are visible in the Plutio admin UI, and you can list them via the Custom Field → Get Many operation in this node.

Rate limits

Plutio limits each API key to 1000 requests/hour. This node:

• caches the access token per execution (one /oauth/token per workflow run, not per call)
• exposes a Return All toggle so you only page when you need to
• bubbles up 429 errors as NodeApiError so n8n’s retry/backoff settings apply

Development

git clone https://github.com/jackmates/n8n-nodes-plutio.git
cd n8n-nodes-plutio
npm install
npm run build       # tsc + gulp build:icons
npm run dev         # tsc --watch
npm run lint

To test inside a local n8n install:

In this repo
npm run build
npm link
In your n8n install (e.g. ~/.n8n)
npm link n8n-nodes-plutio-mates

Then restart n8n. The Plutio node will appear in the node palette.

Releasing

Tag a commit with vX.Y.Z and push to GitHub. The release workflow publishes to npm:

npm version patch -m "Release v%s"
git push --follow-tags

The NPM_TOKEN secret must be set in the GitHub repo settings.

Architecture

The node uses a runtime resource registry instead of per-resource description files:

• nodes/Plutio/resources.ts — single source of truth for every resource (path, capabilities, fields)
• nodes/Plutio/resourceFactory.ts — generates n8n INodeProperties[] from the registry at module-load
• nodes/Plutio/executeOperation.ts — generic CRUD dispatcher that maps capability → HTTP call
• nodes/Plutio/Plutio.node.ts — thin shell that wires it all together
• nodes/Plutio/GenericFunctions.ts — auth + pagination helpers

To add a resource, edit resources.ts. Adding a new endpoint to an existing resource means adding a capability there too — usually nothing else.

License

MIT — same as the original. See LICENSE.md.

Credits

• Original repo: Chykalophia/n8n-nodes-plutio by Peter Krzyzek and Joel Sanguenza
• This fork: MATES Incorporated
• Plutio API docs: https://docs.plutio.com