Skip to content
Back to search

XposedOrNot-API

Open-source API to check if an email has been exposed in a data breach and monitor breaches across your verified domains. Real-time alerts and breach analytics protect your online identity.

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/XposedOrNot/XposedOrNot-API 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/XposedOrNot/XposedOrNot-API'

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/xposedornot--xposedornot-api/badge.svg)](/listings/xposedornot--xposedornot-api)

HTML

<a href="/listings/xposedornot--xposedornot-api"><img src="/api/listings/xposedornot--xposedornot-api/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.

Using Docker Compose (Recommended)

1. **Clone the Repository:**

```shell git clone https://github.com/XposedOrNot/XposedOrNot-API ```

2. **Update the necessary environment variables in the docker-compose.yml file if needed, then run:**

```shell docker compose up ```

This command will build API and Datastore Docker images. Note that the project source directory is mapped in the Docker container, so any changes in the source code won't require rebuilding the Docker image.

Local Installation

1. **Clone the Repository:**

```shell git clone https://github.com/XposedOrNot/XposedOrNot-API ```

2. **Install Required Packages**

```shell sudo apt-get install -y python3-pip build-essential libffi-dev python3-dev ```

Then [install the gcloud CLI](https://cloud.google.com/sdk/docs/install) — it's not in the stock Debian/Ubuntu repositories and is needed for step 4 (Datastore authentication or the local emulator).

3. **Install Python Libraries**

```shell pip3 install -r requirements.txt ```

4. **Setup Google Cloud Datastore**

Before running XposedOrNot-API, choose one of the following options:

- [Run local Google DataStore emulator](https://cloud.google.com/datastore/docs/tools/datastore-emulator) and debug using the local emulator rather than directly connect to Google DataStore.

```shell # For posix platforms, e.g. linux, mac: gcloud beta emulators datastore start ```

- [Authenticate to Google DataStore](https://cloud.google.com/sdk/gcloud/reference/beta/auth/application-default) and directly debug using Google DataStore.

5. **Run the application**

```shell python3 main.py ```

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 · 341 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. <h1 align="center">XposedOrNot API</h1>
  2. <p align="center">
  3. 🎉 Your free API for real-time data breach monitoring and analytics. <br>
  4. <a href="https://github.com/XposedOrNot/XposedOrNot-API/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue"></a>
  5. <a href="https://github.com/XposedOrNot/XposedOrNot-API/blob/master/CONTRIBUTING.md"><img src="https://img.shields.io/badge/Contributions-Welcome-brightgreen"></a>
  6. <a href="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/black.yml"><img src="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/black.yml/badge.svg" alt="Black"></a>
  7. <a href="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/pylint.yml"><img src="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/pylint.yml/badge.svg" alt="Pylint"></a>
  8. <a href="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/codeql.yml"><img src="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
  9. <a href="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/bandit.yml"><img src="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/bandit.yml/badge.svg" alt="Bandit"></a>
  10. <a href="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/pip-audit.yml"><img src="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/pip-audit.yml/badge.svg" alt="Dependency Audit"></a>
  11. <a href="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/fuzzing.yml"><img src="https://github.com/XposedOrNot/XposedOrNot-API/actions/workflows/fuzzing.yml/badge.svg" alt="Atheris Fuzzing"></a>
  12. <a href="https://securityscorecards.dev/viewer/?uri=github.com/XposedOrNot/XposedOrNot-API"><img src="https://api.securityscorecards.dev/projects/github.com/XposedOrNot/XposedOrNot-API/badge" alt="OpenSSF Scorecard"></a>
  13. <a href="https://www.bestpractices.dev/projects/11418"><img src="https://www.bestpractices.dev/projects/11418/badge?v=1" alt="OpenSSF Best Practices"></a>
  14. </p>
  15. <p align="center">
  16. <a href="https://api.xposedornot.com/docs" target="_blank">XposedOrNot API Playground</a> ·
  17. <a href="https://xposedornot.com" target="_blank"> XposedOrNot.com</a>
  18. </p> <br>
  19. <p align="center">
  20. <img src="https://github.com/XposedOrNot/XposedOrNot-Website/blob/master/static/images/xon.webp" alt="XposedOrNot demo">
  21. </p>
  22. ## What is XposedOrNot API?
  23. Data breaches happen constantly, and most people only find out long after their email and passwords are already circulating. I built XposedOrNot so you don't have to wonder. Check an email or domain and know right away whether it's turned up in a known breach.
  24. This repo is the API that powers it all: the breach lookups, the analytics, and the alerts. It's free to use, and it's open-source, so you can read exactly how every check works rather than taking my word for it.
  25. Give it a try below, and if you find it useful, I'd love for you to build something with it.
  26. Devanand Premkumar, creator of XposedOrNot
  27. [![Twitter/X](https://img.shields.io/badge/Twitter%2FX-blue?style=flat-square&logo=x&logoColor=white)](https://x.com/devaonbreaches)
  28. [![Mastodon](https://img.shields.io/badge/-Mastodon-blue?style=flat-square&logo=mastodon&logoColor=white)](https://infosec.exchange/@DevaOnBreaches)
  29. ## Quick Example
  30. Check if an email has been exposed in data breaches:
  31. ```bash
  32. curl https://api.xposedornot.com/v1/check-email/test@example.com
  33. ```
  34. Response:
  35. ```json
  36. {
  37. "breaches": [["Adobe", "LinkedIn"]],
  38. "email": "test@example.com",
  39. "status": "success"
  40. }
  41. ```
  42. Get detailed breach analytics:
  43. ```bash
  44. curl "https://api.xposedornot.com/v1/breach-analytics?email=test@example.com"
  45. ```
  46. ## Rate Limits & API Access
  47. - **No API key required** for basic endpoints (`/v1/check-email`, `/v1/breach-analytics`, `/v1/breaches`)
  48. - **API key required** for domain breach monitoring — see [Domain endpoints & API keys](#domain-endpoints--api-keys) for how to get and use one
  49. Rate limits are applied **per IP, per endpoint**:
  50. | Endpoint | Per second | Per hour | Per day |
  51. |----------|:----------:|:--------:|:-------:|
  52. | `GET /v1/check-email/{email}` | 2 | 25 | 100 |
  53. | `GET /v1/breach-analytics` | 2 | 25 | 100 |
  54. | `GET /v1/breaches` | 2 | 50 | 100 |
  55. | `POST /v1/domain-breaches/` | 2 | 25 | 50 |
  56. When a limit is exceeded the API returns `429 Too Many Requests` with a `Retry-After`
  57. header (seconds) and a JSON body carrying `retry_after` and `reset_time`, so clients
  58. can back off precisely. On `/v1/check-email` and `/v1/breach-analytics` the body also
  59. carries a human-readable `message` and an `upgrade` block (`plan`, `url`, `note`)
  60. pointing at xonAPI+, and the response sets a `Link: <...>; rel="help"` header to the
  61. plans page.
  62. ### Commercial use & higher rate limits
  63. The free API above is for personal and low-volume use, and it stays free. If
  64. you're building a product on breach data or need more throughput,
  65. [xonAPI+](https://plus.xposedornot.com/products/api) offers paid plans from
  66. $9/month with rate limits up to 25,000 requests/minute, API-key access, and
  67. commercial support. It's the same breach data, and it's what keeps the free
  68. tier free.
  69. For full documentation, see the [API docs](https://xposedornot.com/api_doc) and the [API playground](https://api.xposedornot.com/docs).
  70. ## API Endpoints
  71. The full, always-current spec lives at [`/docs`](https://api.xposedornot.com/docs)
  72. (Swagger) and [`/openapi.json`](https://api.xposedornot.com/openapi.json). The
  73. endpoints you'll reach for most:
  74. ### Breach lookups
  75. | Method | Path | What it does |
  76. |--------|------|--------------|
  77. | GET | `/v1/check-email/{email}` | Quick check: is this email in a known breach? |
  78. | GET | `/v1/breach-analytics?email=` | Detailed breach analytics for an email |
  79. | GET | `/v1/breaches` | List all known breaches (optional `?domain=`) |
  80. | GET | `/v1/domain-breach-summary` | Summary of breaches for a domain |
  81. ### Stats & feeds
  82. | Method | Path | What it does |
  83. |--------|------|--------------|
  84. | GET | `/v1/metrics` | Top-level breach metrics |
  85. | GET | `/v1/metrics/detailed` | Expanded metrics |
  86. | GET | `/v1/metrics/domain/{domain}` | Metrics for a single domain |
  87. | GET | `/v1/analytics/pulse` | Recent breach activity pulse |
  88. | GET | `/v1/xon-pulse` | XposedOrNot activity feed |
  89. | GET | `/v1/rss` | Breach updates as an RSS feed |
  90. ### Domain endpoints & API keys
  91. Breach data for a domain is only available once you've **verified ownership** of
  92. that domain, and calls are authenticated with an API key tied to your account.
  93. **Getting an API key** — keys are issued and managed from the web console, not
  94. via a public endpoint:
  95. 1. Sign in at [xposedornot.com](https://xposedornot.com).
  96. 2. Open your **CxO Dashboard** and verify the domain(s) you want to monitor.
  97. 3. Go to **API Key Management** (linked from the dashboard). Your key is shown
  98. there; use **Reset API Key** to rotate it.
  99. **Using the key** — pass it in the `x-api-key` header. The domain-breaches
  100. endpoint takes no body; it returns breaches across *all* the domains you've
  101. verified:
  102. ```bash
  103. curl -L -X POST \
  104. -H "x-api-key: <YOUR_API_KEY>" \
  105. -H "Content-Length: 0" \
  106. https://api.xposedornot.com/v1/domain-breaches/
  107. ```
  108. An invalid key (or one with no verified domains) returns `401 Invalid or missing
  109. API key`; omitting the `x-api-key` header entirely returns `422`. See the
  110. [API docs](https://xposedornot.com/api_doc) for the full domain verification and
  111. alert-subscription flows.
  112. ## Use it from your AI tools (MCP)
  113. XposedOrNot ships a built-in [Model Context Protocol](https://modelcontextprotocol.io)
  114. server, so AI assistants can check breaches directly. Point your MCP client at
  115. `https://api.xposedornot.com/mcp` (Streamable HTTP, JSON-RPC 2.0 over POST).
  116. No API key or authentication is needed; all tools are read-only and never
  117. return passwords.
  118. Tools exposed:
  119. - **`check_email_breaches`**: check if an email appears in any known breach
  120. - **`get_breach_analytics`**: detailed breach history, risk score and paste
  121. exposure for an email
  122. - **`list_breaches`**: browse the breach catalog, filter by domain or breach ID
  123. - **`domain_breach_summary`**: aggregate breach counts for a domain
  124. - **`get_breach_metrics`**: system-wide breach statistics
  125. - **`get_recent_breaches`**: most recently added breaches, newest first
  126. Quick connect:
  127. ```bash
  128. claude mcp add --transport http xposedornot https://api.xposedornot.com/mcp
  129. ```
  130. For Cline, Cursor, Gemini CLI and other clients, see
  131. [llms-install.md](llms-install.md). A machine-readable server card is at
  132. `https://api.xposedornot.com/.well-known/mcp/server-card.json`.
  133. A quick `tools/list` call:
  134. ```bash
  135. curl -X POST https://api.xposedornot.com/mcp \
  136. -H "Content-Type: application/json" \
  137. -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
  138. ```
  139. ## Why use XposedOrNot API?
  140. XposedOrNot was the first open-source tool to monitor and alert on data breaches, and this API gives you direct access to everything it has collected and keeps current. With it you can:
  141. - Check whether an email has appeared in a known data breach, with stats on where and when
  142. - See if an email shows up in public pastes
  143. - Run a single combined search across both breaches and pastes
  144. - Check whether a password has been exposed without ever revealing your identity
  145. Prefer to just look something up without writing code? You can do all of this on the website too: https://xposedornot.com.
  146. ## Security
  147. This project is fully open-source and uses automated security tooling (Black, Pylint, CodeQL, OpenSSF Scorecard). For security details, see [SECURITY.md](SECURITY.md).
  148. Please do not report security vulnerabilities through public GitHub issues. Instead, refer to our [Responsible Disclosure Guidelines](https://xposedornot.com/responsible-disclosure) for reporting these issues in a secure manner.
  149. ## Prerequisites
  150. - **Docker** (recommended): Docker 20.10+ and Docker Compose V2
  151. - **Local install**: Python 3.11+, Google Cloud SDK
  152. ## Quick Start for Local Development
  153. ### Using Docker Compose (Recommended)
  154. 1. **Clone the Repository:**
  155. ```shell
  156. git clone https://github.com/XposedOrNot/XposedOrNot-API
  157. ```
  158. 2. **Update the necessary environment variables in the docker-compose.yml file if needed, then run:**
  159. ```shell
  160. docker compose up
  161. ```
  162. This command will build API and Datastore Docker images. Note that the project source directory is mapped in the Docker container, so any changes in the source code won't require rebuilding the Docker image.
  163. ### Local Installation
  164. 1. **Clone the Repository:**
  165. ```shell
  166. git clone https://github.com/XposedOrNot/XposedOrNot-API
  167. ```
  168. 2. **Install Required Packages**
  169. ```shell
  170. sudo apt-get install -y python3-pip build-essential libffi-dev python3-dev
  171. ```
  172. Then [install the gcloud CLI](https://cloud.google.com/sdk/docs/install) — it's not in the stock Debian/Ubuntu repositories and is needed for step 4 (Datastore authentication or the local emulator).
  173. 3. **Install Python Libraries**
  174. ```shell
  175. pip3 install -r requirements.txt
  176. ```
  177. 4. **Setup Google Cloud Datastore**
  178. Before running XposedOrNot-API, choose one of the following options:
  179. - [Run local Google DataStore emulator](https://cloud.google.com/datastore/docs/tools/datastore-emulator)
  180. and debug using the local emulator rather than directly connect to Google DataStore.
  181. ```shell
  182. # For posix platforms, e.g. linux, mac:
  183. gcloud beta emulators datastore start
  184. ```
  185. - [Authenticate to Google DataStore](https://cloud.google.com/sdk/gcloud/reference/beta/auth/application-default) and directly debug using Google DataStore.
  186. 5. **Run the application**
  187. ```shell
  188. python3 main.py
  189. ```
  190. ## Configuration
  191. Configuration is read from environment variables. For Docker Compose these are
  192. already set in `docker-compose.yml`; for a local install, copy `.env.example` to
  193. `.env` and fill in the values (or export them in your shell).
  194. ### Required (the app won't start without these)
  195. | Variable | What it's for |
  196. |----------|---------------|
  197. | `SECRET_APIKEY` | Secret used to sign issued API keys |
  198. | `SECURITY_SALT` | Salt for signing verification tokens |
  199. | `WTF_CSRF_SECRET_KEY` | CSRF protection secret |
  200. | `ENCRYPTION_KEY` | Fernet key for encrypting stored data |
  201. | `AUTH_EMAIL` | Cloudflare account email |
  202. | `AUTHKEY` | Cloudflare API key |
  203. | `CF_MAGIC` | Cloudflare integration token |
  204. | `CF_UNBLOCK_MAGIC` | Cloudflare unblock token |
  205. | `MJ_API_KEY` | Mailjet API key, for sending alert emails ([mailjet.com](https://www.mailjet.com/)) |
  206. | `MJ_API_SECRET` | Mailjet API secret |
  207. > For local development you can set these to any placeholder value; the defaults
  208. > in `docker-compose.yml` show the expected format.
  209. ### Redis (rate limiting & state)
  210. | Variable | Default | Notes |
  211. |----------|---------|-------|
  212. | `REDIS_HOST` | `localhost` | Redis host |
  213. | `REDIS_PORT` | `6379` | Redis port |
  214. | `REDIS_DB` | `0` | Redis database number |
  215. | `REDIS_PASSWORD` | _(none)_ | Set if your Redis requires auth |
  216. ### Google Cloud (Datastore & Pub/Sub)
  217. | Variable | Default | Notes |
  218. |----------|---------|-------|
  219. | `PROJECT_ID` | _(none)_ | GCP project ID |
  220. | `DATASTORE_EMULATOR_HOST` | _(none)_ | Point at the local emulator, e.g. `localhost:8000` |
  221. | `TOPIC_ID` | _(none)_ | Pub/Sub topic for the live-visitor globe feed |
  222. ### Optional
  223. | Variable | Default | Notes |
  224. |----------|---------|-------|
  225. | `ENVIRONMENT` | `production` | `production` or `development` |
  226. | `BASE_URL` | `https://api.xposedornot.com` | Public base URL used in links |
  227. | `PORT` | `8080` | Port the server listens on |
  228. | `ENABLE_SCHEDULER` | `false` | Run the background digest scheduler |
  229. | `DEBUG_EMAIL` | _(none)_ | Override recipient for debug emails |
  230. | `SENIORITY_ENRICH_URL` / `SENIORITY_ENRICH_SECRET` | _(none)_ | External seniority-enrichment service |
  231. | `DOMAIN_EMAIL_LIMITS_ENABLED` | `true` | Kill switch for domain email verification anti-bombing limits |
  232. | `DOMAIN_EMAIL_RECIPIENT_COOLDOWN_SECONDS` | `900` | Cooldown between challenges to the same role address |
  233. | `DOMAIN_EMAIL_DOMAIN_MAX_PER_HOUR` | `5` | Max verification emails per domain per hour |
  234. | `DOMAIN_EMAIL_IP_MAX_PER_HOUR` | `10` | Max verification emails per client IP per hour |
  235. | `DOMAIN_EMAIL_GLOBAL_DAILY_BUDGET` | `2000` | Global daily cap on verification emails |
  236. ## Contributing
  237. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.
  238. ## Authors
  239. * **Devanand Premkumar** - *Initial work* - [DevaOnBreaches](https://github.com/DevaOnBreaches)
  240. ## License
  241. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
  242. ## Acknowledgments
  243. * Thanks to the Python community and the maintainers of every library this project leans on. XposedOrNot stands on your work.
  244. * And to everyone who has reviewed the code and reported issues: thank you. A second set of eyes catches what I can't.
  245. ## Show Your Support
  246. If this saved you some trouble, a few things genuinely help:
  247. - ⭐ Star the repo so others can find it
  248. - Fork it and send a pull request; contributions are welcome
  249. - Share it with someone who'd find it useful

Ratings and comments

Sign in to rate this skill.

Sign in

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