How to Migrate the n8n Perplexity Node to v3: Chat to Agent API Mapping
Introduction
If your n8n workflows call Perplexity through the old Chat resource, they are standing on an endpoint that no longer exists. Perplexity retired the Sonar Chat Completions endpoint on September 27, 2026, and n8n answered with a new node version: v3, whose default resource is Agent, backed by Perplexity’s Agent API. This guide walks you through migrating each Perplexity node in your workflows from v2 Chat to v3 Agent, with a field-by-field mapping, the preset equivalents for your old Sonar models, and a plan that keeps production running while you switch.
Quick answer
Update each Perplexity node to version 3 and switch the resource from Chat to Agent (Create Response). Map the Sonar model to its preset equivalent, move the system prompt into Instructions, and rewrite downstream parsing for the new response shape.
Evidence
The retirement is official and dated. Perplexity announced in August 2026 that “on September 27, 2026, the Agent API becomes the main surface for this work, and Sonar tiers retire on the same date,” adding that Sonar calls would stop working if nothing changed. The company’s own developer docs now describe the Agent API as the primary API and label /chat/completions deprecated, and its official migration guide for moving off Sonar lives under the Agent API docs. Perplexity’s companion step-by-step how-to for the migration covers the raw request and response changes that the field mapping in this article is based on. This guide is the canonical reference for the change, and it is the one you should trust over any third-party summary, including this article.
n8n’s side of the migration is visible in the node’s own source code on n8n’s master branch. The Perplexity node on n8n’s master branch sets defaultVersion: 3, so any node you add from the node palette today starts as v3. The v3 resource list is exactly three options: Agent (the default), Embedding, and Search. The Agent resource’s own description in the node says: “Recommended. Create responses using the Agent API with third-party models, presets, tools, and structured outputs.” The old Chat resource carries this deprecation text right in the node panel: “Send messages using Sonar models with built-in web search. Perplexity ends Sonar support on September 27, 2026; switch to the Agent resource.”
The money side also changes shape, and this is the part that bites teams who migrate without reading the pricing. Sonar billed per token. The Agent API bills tokens plus per-tool-invocation fees that Perplexity publishes openly: web search costs $2.50 per 1,000 invocations, URL fetching costs $0.50 per 1,000, and finance and people search each cost $5 per 1,000. Each preset also caps agentic steps: 1 step on fast, 5 on low, 15 on medium and high, and 100 on xhigh. A workflow that ran cheaply on sonar with one token meter can get noticeably more expensive on the equivalent preset once tool calls accumulate, so budget alerts calibrated on Sonar token prices need recalibrating.
Prerequisites
- A self-hosted or cloud n8n instance new enough to ship the Perplexity node v3. If your node panel shows only a Chat resource with no version selector, update n8n first; our guide to updating a self-hosted n8n instance covers the safe path.
- A Perplexity API key with credits. The same key works against the Agent API; no new credential is needed.
- A list of every workflow that uses the Perplexity node. Export workflow JSONs or search by node type
n8n-nodes-base.perplexityso none are missed.
Step-by-step guide
Step 1: Inventory your Perplexity nodes and their versions
Do not start editing. First, know what you have. In n8n, search your workflows for Perplexity nodes, or run this against exported JSON files:
grep -l '"type": "n8n-nodes-base.perplexity"' *.json | while read f; do
echo "== $f"
grep -o '"typeVersion": [0-9]*' "$f" | sort -u
done
A typeVersion of 1 or 2 means the node is on v2, which routes its Chat operation to POST /chat/completions, the retired endpoint. A typeVersion of 3 means it is already v3, but double check that the resource is Agent and not Chat, because v3 still lists Chat as a (deprecated) option. Record, per workflow: node version, resource in use, and the Sonar model name configured. This inventory is your migration checklist.
Step 2: Duplicate the workflow before touching anything
In the n8n editor, duplicate each affected workflow and name the copy “MIGRATION -
Step 3: Update the node to version 3
Open the Perplexity node in the duplicate workflow, open the node settings menu (the “…” in the node’s panel), and look for the option to move the node to its latest version. Confirm the update. The Resource dropdown now offers Agent (default), Embedding, and Search. This is the moment the node’s fields change shape, which is why step 2 exists.
If you are running a version of n8n where the settings menu offers no update, your n8n predates the v3 node. Update n8n itself, then retry. The node versioning lives in the node package, not in your workflow JSON, so an old n8n simply cannot render v3.
Step 4: Switch the resource from Chat to Agent and map the fields
With the node on v3, set Resource to Agent and Operation to Create Response. Then map the old Chat fields to their Agent equivalents:
| v2 Chat field | v3 Agent equivalent | Notes |
|---|---|---|
Model (e.g. sonar, sonar-pro) | Preset (fast, low, medium, high, xhigh) | One-to-one mapping: sonar to fast, sonar-pro to low, sonar-reasoning-pro to medium, sonar-deep-research to high. Or pick Model by list/ID instead, but use preset OR model, never both. |
| System Prompt | Options > Instructions | System-level instructions for the agent; same role, new location. |
| User message | Input | The input text prompt sent to the agent. |
| Max tokens / temperature (if used) | Options > Max Output Tokens (default 1024) | The Agent API uses different sampling controls; start with defaults. |
| Citations in response | Simplify Output | Enable it to get only the essential fields: response ID, model, output text, and citations. |
Two fields deserve extra attention. Preset vs Model is exclusive: the field help text says “Preset name to use. Use preset OR model, not both.” If you set both, the request is ambiguous, so clear one of them. Max Steps (default 5, range 1 to 10) caps how many agentic steps one execution may take; it directly bounds tool-invocation cost, so set it deliberately rather than leaving the default on high-volume workflows.
Step 5: Rewrite downstream parsing for the new response shape
This is the silent breaker. Sonar returned a chat-completions-shaped JSON with the answer at choices[0].message.content and citations in a flat structure. The Agent API response nests the evidence inside the agent output. If a downstream Code node does this:
const answer = $json.choices[0].message.content;
return [{ json: { answer } }];
it will throw or return undefined after the migration. With Simplify Output enabled, the v3 node returns the essentials only, so the rewrite is usually small: read the output text field and the citations array from the new structure, then test with Execute Node and inspect the actual JSON before editing the Code node. Do not guess the field paths from memory; one real execution shows you the exact shape, and it takes thirty seconds.
Step 6: Test on the duplicate, compare outputs, then cut over
Run the duplicated workflow end to end. Compare three things against a known-good v2 run (from before the retirement, or from your logs): the answer text, the citations, and the cost. Watch the Perplexity usage dashboard during the test: the Agent API bills tool invocations separately, and a workflow that searched aggressively on Sonar can surprise you. If the numbers look right, swap the production workflow’s schedule or webhook to the migrated copy, or copy the migrated node configuration back into the original. Keep the old v2 copy archived for a week, then delete it.
Step 7: Update templates and shared credentials documentation
If your team shares workflow templates, exported JSONs, or a runbook that says “add a Perplexity node, pick Chat, set model to sonar,” update them now. Stale templates are how retired integrations come back from the dead three months later. The same applies to any internal wiki page that documents the old field mapping.
Troubleshooting
Executions fail with HTTP errors from the Perplexity node after September 27, 2026. This is the retirement itself. The v2 Chat operation routes to POST /chat/completions, which Perplexity retired. Open the failing node, confirm it is on node version 1 or 2 with the Chat resource, and work through steps 3 to 5 above. There is no credential fix and no retry strategy that revives a retired endpoint.
The workflow runs but downstream nodes receive empty or undefined values. The response shape changed between Sonar and the Agent API. Enable Simplify Output on the Create Response operation to get a predictable minimal payload (ID, model, output text, citations), execute the node once, and rewrite the parsing in your Code or Set nodes against the real JSON you see. This is the highest-risk silent break in the migration: the node succeeds, so nothing turns red, but the data your workflow acts on is wrong or missing.
Costs jump after migration with no change in volume. The Agent API adds per-tool-invocation billing on top of tokens. Open your Perplexity usage dashboard and look at tool invocations per request. Reduce Max Steps on the node, pick the cheapest preset that still answers well (fast instead of low, for example), and consider the Search resource instead of Agent for workflows that only need raw ranked results without agentic reasoning. Recalibrate any budget alerts that were tuned to Sonar token pricing.
The node panel shows only the Chat resource and no version 3. Your n8n version predates the v3 node. The node definition ships with n8n, not with your workflow, so no amount of workflow editing will reveal v3. Update n8n to a release that includes the new Perplexity node, then repeat step 3. Our n8n 3.0 upgrade guide is worth reading before any major version jump, since 3.0 carries its own breaking changes.
Preset and model are both set and requests behave erratically. The v3 node requires preset OR model, not both; the Preset field’s own help text says so. Clear the Model resource locator when you use a preset, or clear the Preset field when you pick a model by list or ID. Ambiguous requests may be rejected or routed unpredictably, so treat this as a configuration error, not an API bug.
FAQ
Do I have to migrate if my v2 Perplexity workflows still run?
Yes. The v2 Chat resource calls POST /chat/completions, the Sonar Chat Completions endpoint that Perplexity retired on September 27, 2026. Executions will fail against the retired endpoint. The v3 node defaults to the Agent resource, which calls POST /v1/agent, the supported replacement.
Which Agent API preset replaces my old Sonar model?
Perplexity publishes a one-to-one mapping: sonar maps to the fast preset, sonar-pro to low, sonar-reasoning-pro to medium, and sonar-deep-research to high. The xhigh preset sits above all four for open-ended agentic work. Enter the preset name in the v3 node’s Preset field, or pick a model directly, but never both.
Can I keep the old node version on some workflows?
You can, but it buys nothing. n8n keeps the node version each workflow was built with, so an old workflow keeps using v2 unless you update it. The v2 Chat operation still points at the retired /chat/completions endpoint, so it fails regardless of what n8n does. Migrate every Perplexity node to v3.
Will my costs change after migrating to the Agent API?
Probably. Sonar billed per token; the Agent API bills tokens plus per-tool-invocation fees, such as web search at $2.50 per 1,000 invocations and URL fetching at $0.50 per 1,000, with a per-preset cap on agent steps (1 step on fast, 5 on low, 15 on medium and high, 100 on xhigh). Review a week of usage before and after the migration.
Where did my citations go in the v3 output?
The Agent API nests citation data inside the agent output instead of the flat fields Sonar returned. Enable Simplify Output in the v3 Create Response operation to get just the essential fields (response ID, model, output text, and citations), then update any downstream Code or Set nodes that parsed the old shape.
Conclusion
The migration is mechanical once you see the mapping: node version 3, Agent resource, Create Response operation, preset in place of the old model name, Instructions in place of the system prompt, and a rewritten parser for the new response shape. The two things that actually hurt teams are the silent response-shape change and the new per-tool-invocation billing, and both are cheap to handle if you test on a duplicated workflow first. For the bigger picture on keeping an n8n instance current through breaking changes, read our complete n8n guide next, and keep the n8n 3.0 upgrade checklist bookmarked for the next major version.
Frequently asked questions
Do I have to migrate if my v2 Perplexity workflows still run?
Yes. The v2 Chat resource calls POST /chat/completions, the Sonar Chat Completions endpoint that Perplexity retired on September 27, 2026. Executions will fail against the retired endpoint. The v3 node defaults to the Agent resource, which calls POST /v1/agent, the supported replacement.
Which Agent API preset replaces my old Sonar model?
Perplexity publishes a one-to-one mapping: sonar maps to the fast preset, sonar-pro to low, sonar-reasoning-pro to medium, and sonar-deep-research to high. The xhigh preset sits above all four for open-ended agentic work. Enter the preset name in the v3 node's Preset field, or pick a model directly, but never both.
Can I keep the old node version on some workflows?
You can, but it buys nothing. n8n keeps the node version each workflow was built with, so an old workflow keeps using v2 unless you update it. The v2 Chat operation still points at the retired /chat/completions endpoint, so it fails regardless of what n8n does. Migrate every Perplexity node to v3.
Will my costs change after migrating to the Agent API?
Probably. Sonar billed per token; the Agent API bills tokens plus per-tool-invocation fees, such as web search at $2.50 per 1,000 invocations and URL fetching at $0.50 per 1,000, with a per-preset cap on agent steps (1 step on fast, 5 on low, 15 on medium and high, 100 on xhigh). Review a week of usage before and after the migration.
Where did my citations go in the v3 output?
The Agent API nests citation data inside the agent output instead of the flat fields Sonar returned. Enable Simplify Output in the v3 Create Response operation to get just the essential fields (response ID, model, output text, and citations), then update any downstream Code or Set nodes that parsed the old shape.