Skip to main content
perplexity-upgrade-migration Analyze, plan, and execute Perplexity SDK upgrades with breaking change detection.
Use when upgrading Perplexity SDK versions, detecting deprecations,
or migrating to new API versions.
Trigger with phrases like "upgrade perplexity", "perplexity migration",
"perplexity breaking changes", "update perplexity SDK", "analyze perplexity version".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill perplexity-upgrade-migration ai automation claude-code devops mcp ai-agents
Perplexity Upgrade & Migration
Current State
!npm list openai 2>/dev/null | grep openai || echo 'openai not installed'
!pip show openai 2>/dev/null | grep Version || echo 'N/A'
Overview
Guide for migrating between Perplexity model generations and API changes. Perplexity has evolved from pplx-api with third-party models to the Sonar family with built-in web search.
Model Evolution
Era Models Status Legacy (pre-2025) pplx-7b-online, pplx-70b-online, llama-3.1-sonar-*Deprecated Current (2025) sonar,
sonar-pro
Extended (2025+) sonar-reasoning-pro, sonar-deep-researchActive
Instructions
Step 1: Identify Legacy Patterns to Update set -euo pipefail
# Find deprecated model names in your codebase
grep -rn "pplx-7b\|pplx-70b\|llama.*sonar\|sonar-small\|sonar-medium\|sonar-huge" \
--include="*.ts" --include="*.py" --include="*.js" --include="*.json" \
. 2>/dev/null || echo "No legacy models found"
# Find old base URLs
grep -rn "api.perplexity.com\|pplx.readme.io" \
--include="*.ts" --include="*.py" --include="*.js" \
. 2>/dev/null || echo "No legacy URLs found"
Step 2: Model Name Migration Map // Migration map: old model name -> new model name
const MODEL_MIGRATION: Record<string, string> = {
// Legacy pplx-api models (fully deprecated)
"pplx-7b-online": "sonar",
"pplx-70b-online": "sonar-pro",
"pplx-7b-chat": "sonar",
"pplx-70b-chat": "sonar",
// Llama-era Sonar models (deprecated)
"llama-3.1-sonar-small-128k-online": "sonar",
"llama-3.1-sonar-large-128k-online": "sonar-pro",
"llama-3.1-sonar-huge-128k-online": "sonar-pro",
"sonar-small-online": "sonar",
"sonar-medium-online": "sonar-pro",
// Current models (no migration needed)
"sonar": "sonar",
"sonar-pro": "sonar-pro",
"sonar-reasoning-pro": "sonar-reasoning-pro",
"sonar-deep-research": "sonar-deep-research",
};
function migrateModel(model: string): string {
const migrated = MODEL_MIGRATION[model];
if (!migrated) {
console.warn(`Unknown Perplexity model: ${model}. Defaulting to sonar.`);
return "sonar";
}
if (migrated !== model) {
console.warn(`Perplexity model ${model} is deprecated. Using ${migrated}.`);
}
return migrated;
}
Step 3: URL Migration // Old URLs -> New URL
const BASE_URL_MIGRATION: Record<string, string> = {
"https://api.perplexity.com": "https://api.perplexity.ai",
"https://pplx-api.perplexity.ai": "https://api.perplexity.ai",
};
// Current canonical base URL
const PERPLEXITY_BASE_URL = "https://api.perplexity.ai";
Step 4: Parameter Changes // Parameters that changed between API versions
// OLD: return_citations: true
// NEW: Citations are always returned in the response object
// OLD: No search_recency_filter
// NEW: search_recency_filter: "hour" | "day" | "week" | "month"
// OLD: No search_domain_filter
// NEW: search_domain_filter: string[] (max 20, prefix with - to exclude)
// OLD: No return_related_questions
// NEW: return_related_questions: true (closed beta)
// OLD: No return_images
// NEW: return_images: true (Tier-2+ only)
// OLD: No search_after_date_filter / search_before_date_filter
// NEW: search_after_date_filter: "3/1/2025" (mm/dd/yyyy format)
Step 5: Upgrade OpenAI SDK set -euo pipefail
# Create upgrade branch
git checkout -b upgrade/perplexity-sonar-migration
# Upgrade OpenAI SDK to latest
npm install openai@latest
# or
pip install --upgrade openai
# Run tests
npm test
# Verify connection with new models
node -e "
const OpenAI = require('openai');
const c = new OpenAI({apiKey: process.env.PERPLEXITY_API_KEY, baseURL: 'https://api.perplexity.ai'});
c.chat.completions.create({model:'sonar', messages:[{role:'user',content:'test'}], max_tokens:5})
.then(r => console.log('OK:', r.model))
.catch(e => console.error('FAIL:', e.message));
"
Rollback set -euo pipefail
# If the upgrade breaks things, revert
git checkout main -- package.json package-lock.json
npm install
Error Handling Issue Cause Solution Invalid model errorUsing deprecated model name Apply model migration map Connection refusedWrong base URL Use https://api.perplexity.ai Missing citations Expecting old response format Citations are in response.citations array Parameter rejected Using old parameter names Check current parameter list
Output
Updated model names to current Sonar family
Corrected base URL to api.perplexity.ai
Updated parameters to current API spec
Passing test suite
Resources
Next Steps For CI integration during upgrades, see perplexity-ci-integration.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
