📚 Full Documentation & Advanced Guide: https://henrique-coder.github.io/perplexity-webui-scraper

What is this?

This library lets you interact with Perplexity AI programmatically using the same web endpoints as the browser — no official API key required. It supports conversations, file uploads, streaming, an MCP server for AI agents, and a drop-in OpenAI-compatible REST API.

• Requirements: A Perplexity account and your browser session token. Free accounts support text prompts; paid tiers are required for Pro/Max models and file uploads.
• Key Features: 18 models (GPT-5.6 Terra, Claude Sonnet 5, Claude Opus, Gemini, Deep Research…), file attachments (images, PDFs, …), streaming, MCP Server for AI agents, OpenAI-compatible REST API, multi-turn conversation thread continuation.

Community

• Contributing guide
• Security policy
• Support guide
• Code of conduct
• Discussions
• Sponsor the project

Installation

Install the package depending on your use case:

This project is distributed as a Python package on PyPI and as optional container images on GHCR. GitHub Releases contain the Python wheel and source distribution; native standalone executables are not published.

As a Core Library

Install only the core python library without any extra dependencies.

uv add perplexity-webui-scraper

Full Installation (Everything)

Install all optional dependencies (cli, api, mcp) in one go. Recommended if you want to use all tools out-of-the-box.

uv add "perplexity-webui-scraper[all]"

CLI Tools

Install with terminal UX dependencies to use the interactive chat and token CLI commands.

uv add "perplexity-webui-scraper[cli]"

External Servers

Install dependencies required for the MCP Server or the OpenAI-compatible REST API.

# MCP Server for AI agents
uv add "perplexity-webui-scraper[mcp]"
OpenAI-compatible API server
uv add "perplexity-webui-scraper[api]"

Quick Start

1. Get your session token

# Interactive CLI wizard — walks you through email auth
uv run perplexity-webui-scraper token

Or retrieve __Secure-next-auth.session-token manually from your browser cookies on perplexity.ai.

2. Basic usage

from perplexitywebuiscraper import Perplexity
client = Perplexity(sessi) conversation = client.create_conversation()
print(client.getaccountprofile().account_tier)
conversation.ask("What is quantum computing?") print(conversation.answer)
Follow-ups preserve context automatically
conversation.ask("Explain it simpler")
print(conversation.answer)

Before each prompt, the library checks /api/auth/session and raises ModelAccessError if the selected model requires a higher tier than the authenticated account. When the session payload does not expose enough subscription data, it falls back to /rest/user/settings. Free accounts can use text prompts, but file attachments raise FileAccessError.

perplexity/best adapts to the account tier: free accounts use Perplexity's internal turbo preference, while Pro/Max accounts use pplxproupgraded; both use copilot mode.

3. Streaming

for chunk in conversation.ask("Explain AI", stream=True):
    if chunk.last_chunk:
        print(chunk.last_chunk, end="", flush=True)

4. Choose a model

from perplexitywebuiscraper import ConversationConfig
conversation = client.create_conversation(ConversationConfig(model="perplexity/best")) conversation.ask("Solve this step by step: ...") print(conversation.answer)

5. List all available models

from perplexitywebuiscraper import MODELS
for model in MODELS.list_all():     print(f"{model.id:40} {model.name}")

Available CLI

| Command | Extra | Description | | ------------------------------------- | ----- | ----------------------------------------------------------------------------- | | perplexity-webui-scraper token | cli | Interactive email auth wizard to generate a session token (supports TOTP 2FA) | | perplexity-webui-scraper chat | cli | Ask Perplexity AI questions with real-time streaming output | | perplexity-webui-scraper chat setup | cli | Configure saved token and default model for the chat command | | perplexity-webui-scraper mcp | mcp | Start the MCP server | | perplexity-webui-scraper api | api | Start the OpenAI-compatible REST API server |

OpenAI-Compatible API

Run a local server that accepts OpenAI-formatted requests and forwards them to Perplexity. Works as a drop-in replacement for any OpenAI client — authentication is done per-request via Authorization: Bearer, exactly like the real API.

# Start the server (no token needed at startup)
perplexity-webui-scraper api
Custom host and port
perplexity-webui-scraper api --host 0.0.0.0 --port 8080
Development mode with auto-reload
perplexity-webui-scraper api --reload

Running via Container (Podman)

# Pull the published multi-arch API image
podman pull ghcr.io/henrique-coder/perplexity-webui-scraper:latest
Run the server (exposing port 8000)
podman run --rm -p 8000:8000 ghcr.io/henrique-coder/perplexity-webui-scraper:latest

Optional MCP image for containerized stdio setups:

# Pull the published multi-arch MCP image
podman pull ghcr.io/henrique-coder/perplexity-webui-scraper:mcp
Run MCP server (requires token)
podman run --rm -e PERPLEXITYSESSIONTOKEN=your_token ghcr.io/henrique-coder/perplexity-webui-scraper:mcp

For local development, you can still build the provided container files:

# API image: installs the api extra, exposes port 8000, and starts the REST server.
podman build -t perplexity-api -f Containerfile .
podman run --rm -it -p 8000:8000 perplexity-api
MCP image: installs the mcp extra and starts the stdio MCP server. It does not expose an HTTP port.
podman build -t perplexity-mcp -f Containerfile.mcp .
podman run --rm -it -e PERPLEXITYSESSIONTOKEN=your_token perplexity-mcp

CLI options

| Option | Short | Default | Description | | ------------- | ----- | ----------- | ------------------------ | | --host | -H | 127.0.0.1 | Bind address | | --port | -p | 8000 | Port to listen on | | --reload | | False | Enable auto-reload (dev) | | --log-level | | info | Uvicorn log level |

Authentication

Pass your Perplexity session token as the API key in every request — exactly like the OpenAI API:

# curl
curl http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer YOURSESSIONTOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "perplexity/best", "messages": [{"role": "user", "content": "Hello!"}]}'
Streaming
curl -N http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer YOURSESSIONTOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "perplexity/best", "messages": [{"role": "user", "content": "Hello!"}], "stream": true}'

from openai import OpenAI
client = OpenAI(     base_url="http://localhost:8000/v1",     apikey="YOURSESSION_TOKEN",  # sent as Authorization: Bearer automatically )
response = client.chat.completions.create(     model="perplexity/best",     messages=[{"role": "user", "content": "Hello!"}], ) print(response.choices[0].message.content)

API endpoints

| Method | Path | Description | | ------ | ---------------------- | ------------------------------------------- | | GET | /v1/models | List all available models | | POST | /v1/chat/completions | Chat completion (streaming + non-streaming) | | GET | /docs | Interactive Swagger UI | | GET | /redoc | ReDoc documentation |

Fields not supported by Perplexity (e.g. temperature, top_p) are accepted for client compatibility but silently ignored.

MCP Server

Expose every Perplexity model as a separate tool for AI agents (Claude Desktop, Antigravity, etc.):

{
  "mcpServers": {
    "perplexity-webui-scraper": {
      "command": "uvx",
      "args": [
        "--from",
        "perplexity-webui-scraper[mcp]@latest",
        "perplexity-webui-scraper",
        "mcp"
      ],
      "env": { "PERPLEXITYSESSIONTOKEN": "yourtokenhere" }
    }
  }
}

See the full MCP documentation for all tools and configuration details.

Disclaimer

This is an unofficial library. It uses internal APIs that may change without notice. Use at your own risk. By using this library, you agree to Perplexity AI's Terms of Service.