perplexity-webui-scraper

<div align="center"> <img src="https://raw.githubusercontent.com/henrique-coder/perplexity-webui-scraper/prod/docs/assets/icon.png" width="128" alt="Logo"> # Perplexity WebUI Scraper Python scraper to extract AI responses from [Perplexity's](https://www.perplexity.ai) web interface. [](https://pypi.org/project/perplexity-webui-scraper) [](https://pypi.org/project/perplexity-webui-scraper) [](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/LICENSE) </div> Documentation: [perplexity-webui-scraper.readthedocs.io](https://perplexity-webui-scraper.readthedocs.io) ## About This unofficial library uses Perplexity's internal WebUI endpoints with a browser session token. It supports conversations, file uploads, streaming, an MCP server, and an OpenAI-compatible REST API. A Perplexity account and its browser session token are required. Free accounts support text prompts; paid tiers are required for Pro/Max models and file uploads. ## Community - [Contributing guide](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/CONTRIBUTING.md) - [Security policy](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/SECURITY.md) - [Support guide](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/SUPPORT.md) - [Code of conduct](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/CODE_OF_CONDUCT.md) - [Discussions](https://github.com/henrique-coder/perplexity-webui-scraper/discussions) - [Sponsor the project](https://github.com/sponsors/henrique-coder) ## 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. ### Core library Install the core Python library without optional features. ```bash uv add perplexity-webui-scraper ``` ### All optional features Install the `cli`, `api`, and `mcp` extras together. ```bash uv add "perplexity-webui-scraper[all]" ``` ### CLI tools Install with terminal UX dependencies to use the interactive `chat` and `token` CLI commands. ```bash uv add "perplexity-webui-scraper[cli]" ``` ### Servers Install dependencies required for the MCP Server or the OpenAI-compatible REST API. ```bash # 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 ```bash # Interactive email authentication uv run perplexity-webui-scraper token ``` Or retrieve `__Secure-next-auth.session-token` manually from your browser cookies on `perplexity.ai`. ### 2. Basic usage ```python from perplexity_webui_scraper import Perplexity client = Perplexity(session_token="YOUR_TOKEN") conversation = client.create_conversation() print(client.get_account_profile().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 an `available` 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`. Models use one of three statuses: `available` (confirmed working normally), `unknown` (not yet verified, including custom identifiers), or `unavailable` (confirmed not working). `is_official` separately records whether a model is listed in Perplexity's official WebUI. `last_tested_at` records the last test in ISO 8601 UTC and is `null` for untested models. Any non-available status requires `allow_risky_model=True`; after acknowledgement, the backend makes the final entitlement decision. 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 `pplx_pro_upgraded`; both use `copilot` mode. ### 3. Streaming ```python for chunk in conversation.ask("Explain AI", stream=True): if chunk.last_chunk: print(chunk.last_chunk, end="", flush=True) ``` ### 4. Choose a model ```python from perplexity_webui_scraper import ConversationConfig conversation = client.create_conversation(ConversationConfig(model="perplexity/best")) conversation.ask("Solve this step by step: ...") print(conversation.answer) ``` ### 5. List registered models ```python from perplexity_webui_scraper 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 the supported OpenAI chat-completions fields and forwards requests to Perplexity. Each request passes the Perplexity session token through `Authorization: Bearer`. ```bash # 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) ```bash # 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: ```bash # 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 PERPLEXITY_SESSION_TOKEN=your_token ghcr.io/henrique-coder/perplexity-webui-scraper:mcp ``` For local development, you can still build the provided container files: ```bash # 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 PERPLEXITY_SESSION_TOKEN=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: ```bash # curl export PERPLEXITY_SESSION_TOKEN="your_session_token" curl http://localhost:8000/v1/chat/completions \ -H "Authorization: Bearer $PERPLEXITY_SESSION_TOKEN" \ -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 $PERPLEXITY_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{"model": "perplexity/best", "messages": [{"role": "user", "content": "Hello!"}], "stream": true}' ``` ```python from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="YOUR_SESSION_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 registered 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.): ```json { "mcpServers": { "perplexity-webui-scraper": { "command": "uvx", "args": [ "--from", "perplexity-webui-scraper[mcp]@latest", "perplexity-webui-scraper", "mcp" ], "env": { "PERPLEXITY_SESSION_TOKEN": "your_token_here" } } } } ``` See the [MCP documentation](https://perplexity-webui-scraper.readthedocs.io/page/mcp-server/) for tools and configuration. ## 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](https://www.perplexity.ai/hub/legal/terms-of-service).