Skip to content
Back to search

perplexity-webui-scraper

An advanced, high-performance Python client, MCP server, and REST API for reverse-engineering Perplexity AI's WebUI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/henrique-coder/perplexity-webui-scraper with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/henrique-coder/perplexity-webui-scraper'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/henrique-coder--perplexity-webui-scraper/badge.svg)](/listings/henrique-coder--perplexity-webui-scraper)

HTML

<a href="/listings/henrique-coder--perplexity-webui-scraper"><img src="/api/listings/henrique-coder--perplexity-webui-scraper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

uv add perplexity-webui-scraper

All optional features

Install the `cli`, `api`, and `mcp` extras together.

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]"

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]"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 280 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/henrique-coder/perplexity-webui-scraper/prod/docs/assets/icon.png" width="128" alt="Logo">
  3. # Perplexity WebUI Scraper
  4. Python scraper to extract AI responses from [Perplexity's](https://www.perplexity.ai) web interface.
  5. [![PyPI](https://img.shields.io/pypi/v/perplexity-webui-scraper?color=blue)](https://pypi.org/project/perplexity-webui-scraper)
  6. [![Python](https://img.shields.io/pypi/pyversions/perplexity-webui-scraper)](https://pypi.org/project/perplexity-webui-scraper)
  7. [![License](https://img.shields.io/github/license/henrique-coder/perplexity-webui-scraper?color=green)](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/LICENSE)
  8. </div>
  9. Documentation: [perplexity-webui-scraper.readthedocs.io](https://perplexity-webui-scraper.readthedocs.io)
  10. ## About
  11. This unofficial library uses undocumented Perplexity WebUI endpoints with a browser session token. It supports conversations, file uploads, and streaming; optional extras provide the MCP server and OpenAI-compatible REST API.
  12. 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.
  13. Python 3.11 through 3.15 are supported. Python 3.15 is the primary runtime for direct end-user installations, API/MCP containers, and the local `.python-version` pin. CI quality, documentation, and package build jobs use Python 3.14. The unit-test matrix covers Python 3.11 through 3.15 across Linux, macOS, and Windows.
  14. ## Community
  15. - [Contributing guide](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/CONTRIBUTING.md)
  16. - [Security policy](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/SECURITY.md)
  17. - [Support guide](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/SUPPORT.md)
  18. - [Code of conduct](https://github.com/henrique-coder/perplexity-webui-scraper/blob/prod/CODE_OF_CONDUCT.md)
  19. - [Discussions](https://github.com/henrique-coder/perplexity-webui-scraper/discussions)
  20. - [Sponsor the project](https://github.com/sponsors/henrique-coder)
  21. ## Installation
  22. The package is published to PyPI. API and MCP container images are published to GHCR. GitHub Releases include the wheel and source distribution; the project does not publish standalone executables.
  23. ### Core library
  24. Install the core Python library without optional features.
  25. ```bash
  26. uv add perplexity-webui-scraper
  27. ```
  28. ### CLI and server extras
  29. Install only the features you need. Use the `token`, `api`, and `mcp` extras individually or together.
  30. ```bash
  31. # Install from PyPI
  32. uv add 'perplexity-webui-scraper[token]' # Email token generator
  33. uv add 'perplexity-webui-scraper[api]' # REST API server
  34. uv add 'perplexity-webui-scraper[mcp]' # MCP server
  35. uv add 'perplexity-webui-scraper[all]' # All optional features
  36. ```
  37. ## Quick Start
  38. ### 1. Get your session token
  39. The base install does not include token-generation dependencies. Install the `token` extra first:
  40. ```bash
  41. uv add 'perplexity-webui-scraper[token]'
  42. uv run perplexity-webui-scraper token --email user@example.com
  43. ```
  44. The token command accepts an optional `--email` argument and prompts for an address when omitted. You can also retrieve `__Secure-next-auth.session-token` manually from your browser cookies on `perplexity.ai`.
  45. ### 2. Basic usage
  46. ```python
  47. from perplexity_webui_scraper import Perplexity
  48. client = Perplexity(session_token="YOUR_TOKEN")
  49. conversation = client.create_conversation()
  50. print(client.get_account_profile().account_tier)
  51. conversation.ask("What is quantum computing?")
  52. print(conversation.answer)
  53. # Follow-ups preserve context automatically
  54. conversation.ask("Explain it simpler")
  55. print(conversation.answer)
  56. ```
  57. 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`.
  58. `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.
  59. ### 3. Streaming
  60. ```python
  61. printed = ""
  62. for response in conversation.ask("Explain AI", stream=True):
  63. current = response.answer or "".join(response.chunks)
  64. if current.startswith(printed):
  65. delta = current[len(printed) :]
  66. print(delta, end="", flush=True)
  67. printed = current
  68. elif current:
  69. printed = current
  70. print(f"\r{printed}", end="", flush=True)
  71. ```
  72. ### 4. Choose a model
  73. ```python
  74. from perplexity_webui_scraper import ConversationConfig
  75. conversation = client.create_conversation(ConversationConfig(model="perplexity/best"))
  76. conversation.ask("Solve this step by step: ...")
  77. print(conversation.answer)
  78. ```
  79. ### 5. List registered models
  80. ```python
  81. from perplexity_webui_scraper import MODELS
  82. for model in MODELS.list_all():
  83. print(f"{model.id:40} {model.name}")
  84. ```
  85. ## CLI commands
  86. Use `-h` or `--help` with the root command or any subcommand. The token command accepts `-e` or `--email`.
  87. | Command | Extra | Description |
  88. | ------------------------------------------------- | ------- | ---------------------------------------------------------------------- |
  89. | `perplexity-webui-scraper token -e/--email EMAIL` | `token` | Generate a session token through email authentication (including TOTP) |
  90. | `perplexity-webui-scraper api` | `api` | Start the OpenAI-compatible REST API server |
  91. | `perplexity-webui-scraper mcp` | `mcp` | Start the MCP server |
  92. ## OpenAI-compatible API
  93. Run a local server that accepts the supported subset of OpenAI Responses and legacy Chat Completions requests. Both routes use the same Perplexity conversation core. The Responses route accepts text and base64 data-URL images, supports streaming and process-local `previous_response_id` continuation, and rejects unsupported request fields. Tool execution, durable response retrieval, and remote image fetching are not implemented.
  94. ```bash
  95. # Start with clients supplying their Perplexity token per request
  96. perplexity-webui-scraper api
  97. # Optional server-default upstream token, protected by a separate gateway key
  98. PERPLEXITY_SESSION_TOKEN="$PPLX_TOKEN" PERPLEXITY_API_KEY="$GATEWAY_KEY" perplexity-webui-scraper api
  99. # Custom host and port
  100. perplexity-webui-scraper api --host 0.0.0.0 --port 8080
  101. # Development mode with auto-reload
  102. perplexity-webui-scraper api --reload
  103. ```
  104. ### Container deployment with Podman
  105. ```bash
  106. # Pull the published multi-arch API image
  107. podman pull ghcr.io/henrique-coder/perplexity-webui-scraper:latest
  108. # Run the server (exposing port 8000)
  109. podman run --rm -p 8000:8000 ghcr.io/henrique-coder/perplexity-webui-scraper:latest
  110. ```
  111. Optional MCP image for containerized stdio setups:
  112. ```bash
  113. # Pull the published multi-arch MCP image
  114. podman pull ghcr.io/henrique-coder/perplexity-webui-scraper:mcp
  115. # Run MCP server (requires token)
  116. podman run --rm -e PERPLEXITY_SESSION_TOKEN=your_token ghcr.io/henrique-coder/perplexity-webui-scraper:mcp
  117. ```
  118. For local development, you can still build the provided container files:
  119. ```bash
  120. # API image: installs the `api` extra, exposes port 8000, and starts the REST server.
  121. podman build -t perplexity-api -f Containerfile .
  122. podman run --rm -it -p 8000:8000 perplexity-api
  123. # MCP image: installs the `mcp` extra and starts the stdio MCP server. It does not expose an HTTP port.
  124. podman build -t perplexity-mcp -f Containerfile.mcp .
  125. podman run --rm -it -e PERPLEXITY_SESSION_TOKEN=your_token perplexity-mcp
  126. ```
  127. ### CLI options
  128. | Option | Short | Default | Description |
  129. | ------------- | ----- | ----------- | ------------------------------------- |
  130. | `--host` | `-H` | `127.0.0.1` | Bind address |
  131. | `--port` | `-p` | `8000` | Port to listen on |
  132. | `--reload` | | `False` | Enable auto-reload (development only) |
  133. | `--log-level` | | `info` | Uvicorn log level |
  134. ### Authentication
  135. Without a server-default token, send your Perplexity token as `Authorization: Bearer $PERPLEXITY_SESSION_TOKEN`. When `PERPLEXITY_SESSION_TOKEN` is configured on the server, requests may omit `Authorization` but must include the separate gateway key in `X-API-Key`. A caller Bearer token overrides the server default, but gateway authentication is still required.
  136. ```bash
  137. # curl
  138. export PERPLEXITY_SESSION_TOKEN='your_session_token'
  139. curl http://localhost:8000/v1/chat/completions \
  140. -H 'Authorization: Bearer $PERPLEXITY_SESSION_TOKEN' \
  141. -H 'Content-Type: application/json' \
  142. -d '{"model": "perplexity/best", "messages": [{"role": "user", "content": "Hello!"}]}'
  143. # Streaming
  144. curl -N http://localhost:8000/v1/chat/completions \
  145. -H 'Authorization: Bearer $PERPLEXITY_SESSION_TOKEN' \
  146. -H 'Content-Type: application/json' \
  147. -d '{"model": "perplexity/best", "messages": [{"role": "user", "content": "Hello!"}], "stream": true}'
  148. ```
  149. ```python
  150. from openai import OpenAI
  151. client = OpenAI(
  152. base_url="http://localhost:8000/v1",
  153. api_key="YOUR_SESSION_TOKEN", # sent as Authorization: Bearer automatically
  154. )
  155. response = client.chat.completions.create(
  156. model="perplexity/best",
  157. messages=[{"role": "user", "content": "Hello!"}],
  158. )
  159. print(response.choices[0].message.content)
  160. ```
  161. Responses API request with server-configured upstream credentials:
  162. ```bash
  163. curl http://localhost:8000/v1/responses \
  164. -H 'X-API-Key: $GATEWAY_KEY' \
  165. -H 'Content-Type: application/json' \
  166. -d '{"model":"perplexity/best","input":"Hello!"}'
  167. ```
  168. ### API endpoints
  169. | Method | Path | Description |
  170. | ------ | ---------------------- | ------------------------------------------------------------------- |
  171. | `GET` | `/v1/models` | List registered models |
  172. | `POST` | `/v1/responses` | Responses text and base64 image input (streaming and non-streaming) |
  173. | `POST` | `/v1/chat/completions` | Legacy Chat Completions (streaming and non-streaming) |
  174. | `GET` | `/docs` | Interactive Swagger UI |
  175. | `GET` | `/redoc` | ReDoc API documentation |
  176. > Chat Completions accepts and ignores some unsupported OpenAI fields. Responses rejects unknown request fields. Neither route implements the full OpenAI API.
  177. ### `POST /v1/responses`
  178. The Responses route accepts `model`, `input`, `instructions`, `stream`, `previous_response_id`, and the `perplexity` extension object. It accepts a string input or supported text and base64 image items. Unknown request fields and unsupported input item types return `422`. Tool execution, durable response retrieval, and token-usage accounting are not implemented. Continuation IDs map to an in-memory conversation thread and expire with the process-local cache.
  179. ## MCP server
  180. Expose every Perplexity model as a separate tool for AI agents (Claude Desktop, Antigravity, etc.):
  181. ```json
  182. {
  183. "mcpServers": {
  184. "perplexity-webui-scraper": {
  185. "command": "uvx",
  186. "args": [
  187. "--from",
  188. "perplexity-webui-scraper[mcp]",
  189. "perplexity-webui-scraper",
  190. "mcp"
  191. ],
  192. "env": { "PERPLEXITY_SESSION_TOKEN": "your_token_here" }
  193. }
  194. }
  195. }
  196. ```
  197. See the [MCP documentation](https://perplexity-webui-scraper.readthedocs.io/page/mcp-server/) for tools and configuration.
  198. ## Disclaimer
  199. 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).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.