perplexityai · andrewmadson-pplx · Aug 28, 2026 · Aug 28, 2026 · Aug 28, 2026
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -3,7 +3,6 @@ Brief description of your contribution
 
 ## Type of Contribution
 - [ ] Example Tutorial
-- [ ] Showcase Project
 - [ ] Article/Integration Guide
 - [ ] Documentation Update
 - [ ] Bug Fix
@@ -22,7 +21,7 @@ Brief description of your contribution
 <!-- Describe the problem or use case your contribution addresses -->
 
 **What makes this contribution valuable to other developers?**
-<!-- Explain why this would be helpful to others using the Perplexity Sonar API -->
+<!-- Explain why this would be helpful to others using the Perplexity API Platform -->
 
 **External Links (if applicable):**
 - GitHub Repository: 
@@ -36,4 +35,4 @@ Brief description of your contribution
 <!-- Add screenshots to help explain your contribution -->
 
 ## Additional Notes
-<!-- Any additional information that might be helpful for reviewers --> 
+<!-- Any additional information that might be helpful for reviewers -->
diff --git a/.github/workflows/pr-validation.yml b/.github/workflows/pr-validation.yml
@@ -12,30 +12,29 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v6
-        
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
       - name: Setup Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: '18'
+          node-version: '20'
           cache: 'npm'
-          
+
       - name: MDX validation dependencies
-        run: npm install --save-dev @mdx-js/mdx @mdx-js/loader glob
-        
+        run: npm ci
+
       - name: Validate MDX files
         run: node scripts/validate-mdx.js
-          
+
       - name: Check for broken links
         run: |
-          # Simple check for common broken link patterns
-          echo "Checking for potential broken links..."
-          if grep -r "http://localhost\|http://127.0.0.1" docs/ --exclude-dir=showcase; then
-            echo "❌ Found localhost links that should be removed"
+          echo "Checking for localhost Markdown links..."
+          if grep -rE '\]\(http://(localhost|127\.0\.0\.1)' docs/; then
+            echo "❌ Found localhost Markdown links that should be removed"
             exit 1
           fi
-          echo "✅ No obvious broken links found"
-          
+          echo "✅ No localhost Markdown links found"
+
       - name: Validate frontmatter
         run: |
           # Check that all MDX files have required frontmatter
@@ -45,4 +44,4 @@ jobs:
               exit 1
             fi
             echo "✅ $file - Has frontmatter"
-          done 
+          done
diff --git a/.github/workflows/sync-to-docs.yml b/.github/workflows/sync-to-docs.yml
@@ -10,80 +10,91 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout cookbook repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           path: cookbook-repo
 
       - name: Checkout docs repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           repository: ${{ secrets.DOCS_REPO_NAME || 'ppl-ai/api-docs' }}
           token: ${{ secrets.DOCS_REPO_TOKEN }}
           path: docs-repo
 
       - name: Setup Node.js
-        uses: actions/setup-node@v6
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: '18'
-          cache: 'npm'
-          cache-dependency-path: docs-repo/package.json
+          node-version: '20'
 
       - name: Install docs dependencies
         run: |
+          corepack enable
           cd docs-repo
-          npm install
+          pnpm install --frozen-lockfile
 
       - name: Clear existing cookbook content
         run: |
-          rm -rf docs-repo/cookbook/* || true
+          rm -rf docs-repo/docs/cookbook
 
       - name: Copy cookbook content to docs repository
         run: |
-          # Create cookbook directory if it doesn't exist
-          mkdir -p docs-repo/cookbook
-
-          # Copy docs content from cookbook to docs repo (already in MDX format)
-          cp -r cookbook-repo/docs/* docs-repo/cookbook/
-
-          # Copy static assets if they exist
+          mkdir -p docs-repo/docs/cookbook
+
+          cp -a cookbook-repo/docs/. docs-repo/docs/cookbook/
+
           if [ -d "cookbook-repo/static" ]; then
-            mkdir -p docs-repo/cookbook/static
-            cp -r cookbook-repo/static/* docs-repo/cookbook/static/
+            mkdir -p docs-repo/docs/cookbook/static
+            cp -a cookbook-repo/static/. docs-repo/docs/cookbook/static/
           fi
 
-      - name: Generate cookbook navigation
-        run: |
-          cd docs-repo  
-          # Run the navigation generation script
-          node scripts/generate-cookbook-nav.js
-
       - name: Configure git
         run: |
           cd docs-repo
           git config --local user.email "cookbook-sync@perplexity.ai"
           git config --local user.name "Cookbook Sync Bot"
-
-      - name: Commit and push changes
+
+      - name: Commit cookbook content
+        id: cookbook-content
         run: |
           cd docs-repo
-          git add .
+          git add docs/cookbook
           if git diff --staged --quiet; then
-            echo "No changes to commit"
-            echo "CHANGES_MADE=false" >> $GITHUB_ENV
+            echo "changed=false" >> "$GITHUB_OUTPUT"
           else
             git commit -m "📚 Sync cookbook from ${{ github.repository }}@${{ github.sha }}
 
-            Updated cookbook content and navigation from community contributions.
-            
+            Updated cookbook content from the canonical repository.
+
             Source: ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}"
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Generate cookbook navigation and gallery data
+        run: |
+          cd docs-repo
+          pnpm sync-cookbook
+
+      - name: Commit and push changes
+        run: |
+          cd docs-repo
+          git add config/navigation.json snippets/cookbookData.jsx
+          if [ "${{ steps.cookbook-content.outputs.changed }}" = "true" ]; then
+            git commit --amend --no-edit
+            git push
+            echo "CHANGES_MADE=true" >> $GITHUB_ENV
+          elif git diff --staged --quiet; then
+            echo "No changes to commit"
+            echo "CHANGES_MADE=false" >> $GITHUB_ENV
+          else
+            git commit -m "📚 Regenerate cookbook navigation and gallery data"
             git push
             echo "CHANGES_MADE=true" >> $GITHUB_ENV
           fi
 
       - name: Create deployment comment
         if: env.CHANGES_MADE == 'true'
         continue-on-error: true
-        uses: actions/github-script@v8
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v8.0.0
         with:
           script: |
             try {
@@ -100,7 +111,7 @@ jobs:
 
                 📈 Changes will be live on docs.perplexity.ai within a few minutes.
 
-                🔗 [View docs site](https://docs.perplexity.ai/cookbook)`
+                🔗 [View docs site](https://docs.perplexity.ai/docs/cookbook)`
               });
               console.log('✅ Success comment posted successfully');
             } catch (error) {
@@ -111,7 +122,7 @@ jobs:
       - name: Report sync failure
         if: failure()
         continue-on-error: true
-        uses: actions/github-script@v8
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v8.0.0
         with:
           script: |
             try {
@@ -145,4 +156,4 @@ jobs:
           else
             echo "ℹ️  No changes to sync"
             echo "📄 Cookbook content is already up to date"
-          fi 
+          fi
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,25 +1,22 @@
 # Contributing to Perplexity API Cookbook
 
-Thank you for your interest in contributing to our API Cookbook! We welcome high-quality examples that showcase the capabilities of Perplexity's Sonar API.
+Thank you for your interest in contributing to our API Cookbook! We welcome high-quality examples that teach developers how to use the Perplexity API Platform.
 
 ## Structure
 
-This cookbook contains three main sections:
+This cookbook contains two main sections:
 
 ### 1. **Examples** (`/docs/examples/`)
 Step-by-step tutorials and example implementations that teach specific concepts or solve common use cases.
 
-### 2. **Showcase** (`/docs/showcase/`)
-Community-built projects that demonstrate real-world applications of the Sonar API.
-
-### 3. **Articles** (`/docs/articles/`)
+### 2. **Articles** (`/docs/articles/`)
 In-depth integration guides and advanced implementation tutorials for complex use cases and integrations with other tools.
 
 ## Contributing Guidelines
 
 ### What We're Looking For
 
-- **Clear, educational content** that helps developers understand how to use the Sonar API effectively
+- **Clear, educational content** that helps developers understand how to use the Agent API, Search API, or Embeddings API effectively
 - **Real-world use cases** that solve actual problems
 - **Well-documented code** with clear explanations
 - **Novel applications** that showcase unique ways to leverage the API
@@ -86,14 +83,6 @@ Any known limitations or considerations users should be aware of.
 4. Include any necessary code snippets in your MDX file
 5. Submit a pull request
 
-### For Showcase Projects
-
-1. Build your project in a separate public repository
-2. Fork this repository
-3. Create a new MDX file under `/docs/showcase/your-project-name.mdx`
-4. Include screenshots or demos if applicable
-5. Submit a pull request
-
 ### For Articles
 
 1. Fork this repository
@@ -113,7 +102,6 @@ Brief description of your contribution
 
 ## Type of Contribution
 - [ ] Example Tutorial
-- [ ] Showcase Project
 - [ ] Article/Integration Guide
 
 ## Checklist
@@ -157,4 +145,4 @@ If you have questions about contributing, please:
 2. Open an issue for discussion before starting major work
 3. Contact us at api@perplexity.ai for specific questions
 
-We look forward to seeing your creative applications of the Perplexity Sonar API!
+We look forward to seeing your creative applications of the Perplexity API Platform!
diff --git a/README.md b/README.md
@@ -1,44 +1,27 @@
-A comprehensive collection of practical examples, integration guides, and community showcases for building with [Perplexity's Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart) — the new primary API for building hosted agents with native web access, citations, code execution, subagents, and durable, long-running work.
+A comprehensive collection of practical examples and integration guides for building with [Perplexity's Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart), Search API, and Embeddings API.
 
 > **Agent API is now the primary Perplexity API.** New projects should build on the Agent API. The Sonar API (`/chat/completions`) is deprecated — if you're on Sonar, see the [migrate from Sonar guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar) to move to the Agent API.
 
-📖 **[View the full cookbook →](https://docs.perplexity.ai/cookbook)**
+📖 **[View the full cookbook →](https://docs.perplexity.ai/docs/cookbook)**
 
 ## What's Inside
 
 ### 🛠️ [Examples](docs/examples/)
-Ready-to-run applications demonstrating real-world use cases:
-
-- **[Equity Research Brief](docs/examples/equity-research-brief/)** - Agent API + `finance_search` for ticker-level research briefs
-- **[Finance Chart (Sandbox)](docs/examples/finance-chart-sandbox/)** - Agent API + `finance_search` + `sandbox` to chart a stock's price history
-- **[Fact Checker CLI](docs/examples/fact-checker-cli/)** - Verify claims and articles for accuracy
-- **[Daily Knowledge Bot](docs/examples/daily-knowledge-bot/)** - Automated daily fact delivery system  
-- **[Disease Information App](docs/examples/disease-qa/)** - Interactive medical information lookup
-- **[Financial News Tracker](docs/examples/financial-news-tracker/)** - Real-time market analysis
-- **[Academic Research Finder](docs/examples/research-finder/)** - Literature discovery and summarization
-- **[Discord Bot](docs/examples/discord-py-bot/)** - Discord integration example
-
-### 🌟 [Community Showcase](docs/showcase/)
-Community-built applications including:
-- News and finance apps
-- AI-powered search tools  
-- Browser extensions
-- Educational platforms
-- And many more innovative projects
+Ready-to-run applications demonstrating research, finance, sandbox, MCP, multimodal, Search API, and embeddings workflows.
 
 ### 📚 [Integration Guides](docs/articles/)
 In-depth tutorials for advanced implementations:
-- Migrating from Sonar to the Agent API
-- Memory management patterns
-- OpenAI agents integration
-- Multi-modal implementations
+- Agent API orchestration and tool use
+- Search filtering and academic research
+- Structured outputs and streaming citations
+- Embeddings and retrieval-augmented generation
 
 ## Quick Start
 
-1. **Browse the [documentation](https://docs.perplexity.ai/cookbook)** to find examples that match your needs
+1. **Browse the [documentation](https://docs.perplexity.ai/docs/cookbook)** to find examples that match your needs
 2. **Clone this repository** and navigate to any example directory
 3. **Follow the setup instructions** in each example's README
-4. **Get your API key** from [Perplexity](https://docs.perplexity.ai/guides/getting-started)
+4. **Get your API key** from [Perplexity](https://console.perplexity.ai)
 5. **Build and customize** for your specific use case
 
 ## API Key Setup
@@ -49,14 +32,14 @@ All examples require a Perplexity API key:
 export PPLX_API_KEY="your-api-key-here"
 ```
 
-Get your API key at [docs.perplexity.ai](https://docs.perplexity.ai/guides/getting-started).
+Get your API key in the [API Portal](https://console.perplexity.ai).
 
 ## Contributing
 
-Have a project built with the Agent API? We'd love to feature it! 
+Have an example built with the Perplexity API Platform? We'd love to include it.
 
 - **[Submit an Example Tutorial](CONTRIBUTING.md#for-examples)**
-- **[Submit a Showcase Project](CONTRIBUTING.md#for-showcase-projects)**  
+- **[Submit an Integration Guide](CONTRIBUTING.md#for-articles)**
 - **[View Full Contributing Guidelines](CONTRIBUTING.md)**
 
 ## Resources
@@ -68,4 +51,4 @@ Have a project built with the Agent API? We'd love to feature it!
 
 ---
 
-*This repository syncs to [docs.perplexity.ai/cookbook](https://docs.perplexity.ai/cookbook) on every commit.*
+*This repository syncs to [docs.perplexity.ai/docs/cookbook](https://docs.perplexity.ai/docs/cookbook) on every commit to `main`.*