--- name: plaud-api description: Use when accessing Plaud voice recorder data (recordings, transcripts, AI summaries) - guides credential setup and provides patterns for plaud_client.py aliases: - plaud - plaud-recordings ---

Plaud API Skill

Access Plaud voice recorder data including recordings, transcripts, and AI-generated summaries.

Overview

The Plaud API provides access to:

• Audio files: MP3 recordings from your Plaud device
• Transcripts: Full text transcriptions with speaker diarization
• AI summaries: Auto-generated notes and summaries

Core principle: Use plaud_client.py (included in this skill), not raw API calls. The client handles authentication, error handling, and response parsing.

When to Use This Skill

Use this skill when:

• User mentions "Plaud", "Plaud recording", or "transcript from Plaud"
• Need to access voice recorder data
• Working with recordings, transcripts, or AI notes from a Plaud device

Interactive Credential Tutorial

Before using the Plaud API, you need to extract credentials from the web app.

Step 1: Navigate to Plaud Web App

Open Chrome and go to: https://web.plaud.ai

Log in with your Plaud account if not already logged in.

Step 2: Open Chrome DevTools

Press F12 (or Cmd+Option+I on Mac) to open DevTools.

Step 3: Find localStorage Values

1. Click the Application tab in DevTools
2. In the left sidebar, expand Local Storage
3. Click on https://web.plaud.ai

Step 4: Copy Required Values

Find and copy these two values:

| Key | Description | |-----|-------------| | tokenstr | Your bearer token (starts with "bearer eyJ...") | | plaud_user_api_domain | API endpoint (e.g., "https://api-euc1.plaud.ai") |

Step 5: Create .env File

Create or update the .env file in the skill directory (~/.claude/skills/plaud-api/):

# In the skill directory
cd ~/.claude/skills/plaud-api
cp .env.example .env
# Edit .env with your actual credentials

Or create it directly:

cat > ~/.claude/skills/plaud-api/.env << 'EOF'
PLAUD_TOKEN=bearer eyJ...your_full_token_here...
PLAUD_API_DOMAIN=https://api-euc1.plaud.ai
EOF

Important: Include the full token including the "bearer " prefix.

Step 6: Verify Setup

Test that credentials work:

cd ~/.claude/skills/plaud-api
python3 plaud_client.py list

If successful, you'll see a list of your recordings with file IDs, durations, and names.

First-time setup: Install dependencies if needed:

pip install -r ~/.claude/skills/plaud-api/requirements.txt

.env File Format

PLAUD_TOKEN=bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
PLAUD_API_DOMAIN=https://api-euc1.plaud.ai

Notes:

• The token includes the "bearer " prefix
• API domain is region-specific (EU users: api-euc1, US users may differ)

Quick Reference

All commands should be run from the skill directory (~/.claude/skills/plaud-api):

| Task | Command | |------|---------| | List all recordings | python3 plaud_client.py list | | List as JSON | python3 plaud_client.py list --json | | Get file details | python3 plaud_client.py details | | Get details as JSON | python3 plaud_client.py details --json | | Download audio | python3 plaud_client.py download | | Download to path | python3 plaud_client.py download -o output.mp3 | | Download all files | python3 plaud_client.py download-all -o ./recordings | | Get file tags/folders | python3 plaud_client.py tags |

Common Patterns

Fetch Recent Transcripts

cd ~/.claude/skills/plaud-api

# List files to find IDs
python3 plaud_client.py list

# Get transcript for a specific file
python3 plaud_client.py details <file_id> --json | jq '.data.trans_result'

File ID Discovery

File IDs are 32-character hex strings. Find them from:

1. URLs: https://web.plaud.ai/file/{file_id}
2. List output: First column in python3 plaud_client.py list
3. JSON output: python3 plaud_client.py list --json | jq '.[].id'

Get AI Summary

python3 plaud_client.py details <file_id> --json | jq '.data.ai_content'

Batch Operations

# Download all recordings to a folder
python3 plaud_client.py download-all -o ./all_recordings

# Get all file IDs
python3 plaud_client.py list --json | jq -r '.[].id'

Extract Transcript Text Only

# Get plain transcript text (all segments concatenated)
python3 plaud_client.py details <file_id> --json | jq -r '.data.trans_result.segments[].text' | tr '\n' ' '

Error Handling

| Error | Cause | Fix | |-------|-------|-----| | 401 Unauthorized | Token expired or invalid | Re-extract token from localStorage | | Empty response | Invalid file_id format | Verify file_id is 32 hex characters | | Connection error | Wrong API domain | Check PLAUD_API_DOMAIN in .env | | Token required | Missing .env or PLAUD_TOKEN | Follow credential tutorial above |

Token Refresh

Plaud tokens are long-lived (~10 months), but when they expire:

1. Log into https://web.plaud.ai
2. Open DevTools > Application > Local Storage
3. Copy the new tokenstr value
4. Update your .env file

API Reference

For detailed API documentation, see PLAUD_API.md included in this skill directory.

Key endpoints used by plaud_client.py:

• GET /file/simple/web - List all files
• GET /file/detail/{file_id} - Get file details with transcript
• GET /file/download/{file_id} - Download MP3 audio
• GET /filetag/ - Get file tags/folders

Included Files

| File | Purpose | |------|---------| | plaud_client.py | CLI tool for all Plaud API operations | | PLAUD_API.md | Detailed API endpoint documentation | | requirements.txt | Python dependencies | | .env.example | Template for credentials |