Description

n8n-nodes-petals

An n8n community node for the whole Petals
API: ingest content into your assistant memory, read your metrics back out, and
chat with your assistant.

Installation

In n8n: Settings → Community Nodes → Install, then enter n8n-nodes-petals.

Credentials

Create a Petals API credential with an API key from your Petals account
(Settings → API Keys). The key authenticates as you; the proxy derives your user
from it. Self-hosters can override the Base URL.

Operations

The node maps each operation to one Petals proxy endpoint:

| Resource | Operation | Endpoint |
|—|—|—|
| Assistant | Get Many | GET /api/assistants |
| Model | Get Many | GET /api/models |
| Chat | Create | POST /api/create-chat |
| Chat | Get Status | GET /api/chat/status |
| Chat | Completion | POST /api/chat/completions |
| Document | Ingest | POST /api/memory/ingest/document |
| File | Ingest | POST /api/memory/ingest/file |
| Transcript | Ingest | POST /api/memory/ingest/transcript |
| Metric | Record Observation | POST /api/memory/metrics/observations |
| Metric | Record Observations (Bulk) | POST /api/memory/metrics/observations/bulk |
| Metric | List Definitions | POST /api/memory/metrics/list |
| Metric | Get Series | POST /api/memory/metrics/series |
| Metric | Get Summary | POST /api/memory/metrics/summary |

Picking a chat operation

Two operations send a message to your assistant, and they behave very
differently:

| | Chat → Create | Chat → Completion |
|—|—|—|
| Returns | Immediately, at status: "queued" | When the answer is ready |
| The answer | Arrives later, via Chat → Get Status | Is in the response |
| Shape | Petals chat (chatId, messageId) | OpenAI chat-completion |
| Good for | Long turns, fire-and-forget automations, anything you want to see in the Petals UI | Getting an answer inside the same run, and OpenAI-shaped tooling |

Completion is synchronous but never streams: the endpoint rejects
stream: true with a 400, so the node always asks for the whole answer at once
and there is no streaming toggle to find.

Chatting with your assistant

Chat → Create posts your message and returns as soon as it is queued:

{ "success": true, "userId": "…", "chatId": "…", "messageId": "…", "status": "queued" }

The assistant’s turn runs in a background queue, so the reply is not in that
response. To pick it up, poll Chat → Get Status with the chatId:

• status is queued or running — still working, poll again
• status is completed — the assistant’s answer is the last messages entry

with role: "assistant" (messages come oldest first, capped at the last 200)

• status is failed — error says why
• status is unknown — the run record aged out (they are kept for 24 hours);

judge from messages

The node deliberately does not wait for the reply itself: compose the wait in the
workflow with a Wait node between Create and Get Status, and loop back with an
If node while the status is still queued or running. That keeps the poll
interval yours, and keeps a long assistant turn from occupying a node execution.

Set Hidden on Create to keep your message out of the Petals chat UI while
still sending it to the model — handy for automation prompts you don’t want
cluttering the conversation.

Chat → Completion takes the OpenAI shape instead: an assistant in
Assistant, a Messages list built from fields, and the usual optional knobs
(temperature, tools, response_format, …) under Additional Fields.
Switch Messages Input to JSON to pass a raw OpenAI messages array when you
need content parts, tool calls, or tool results. To pin a specific model, set the
assistant field by expression to assistantId@modelId.

Assistants and models

Assistant → Get Many and Model → Get Many list what you can chat with,
one n8n item per row. The same two endpoints back the Assistant and Model
dropdowns on Chat → Create and Chat → Completion, so you pick a name in the
editor instead of hunting for a UUID. Both fields still accept an expression when
the ID is computed upstream.

Reading metrics back

Metrics are readable as well as writable, which is what makes
“read the trend → decide → act” workflows possible:

• Metric → List Definitions returns every definition with its stats

(observationCount, latestValue, …). Its id (mdef_…) is what the other
two read operations take — and it also backs their Metric dropdowns, so you
pick definitions by label there too. Filter by active, needs-review, or a
search string.

• Metric → Get Series returns points for one or more definitions over a

range. Bucket rolls them up by hour/day/week/month; None returns the raw
observations. Aggregation overrides the metric’s own aggregation hint.

• Metric → Get Summary returns one metric’s latest value, its 7d/30d/90d

windows, and a trend of up, down, or flat.

Keeping this node in tandem with the API

The table above is the source of truth for the proxy-endpoint ↔ node-operation
pairing, and it currently covers the documented Petals API surface end to end.
When the proxy gains a new end-user-relevant capability — ingestion, metrics,
chat, or discovery — add the matching Resource/Operation here in the same change.
The capability chain is Memory SDK/MCP → Petals proxy → this node.

License

MIT