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:

Picking a chat operation

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

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