API Documentation
The BreachRegistry REST API provides programmatic access to our indexed breach intelligence database. All endpoints return JSON and require a valid API key. Base URL: https://breachregistry.com/api/public/v1
SYSTEM STATUS & UPTIME
Check operational status, API endpoint health, and latency metrics.
Authentication
All requests to the /api/public/v1/* endpoints must include a valid API key in the Authorization header. API keys can be generated from your dashboard — you must have member status or higher.
HOW TO GET A KEY
- Log in at /login
- Go to /dashboard/api
- Click GENERATE KEY (requires member status)
- Copy your key — it is displayed only once
- Pass it as
Authorization: Bearer br_live_...
Rate Limits
Each API key is limited to 100 requests per 60 seconds (rolling window). When you exceed the limit, requests return HTTP 429 until the window resets. All responses include rate limit headers.
| HEADER | DESCRIPTION |
|---|---|
| X-RateLimit-Limit | Total allowed requests per window (100) |
| X-RateLimit-Remaining | Requests remaining in current window |
| X-RateLimit-Reset | Unix timestamp when the window resets |
| Retry-After | Seconds to wait before retrying (on 429) |
Endpoints
Error Codes
All errors follow a consistent envelope format with a machine-readable code field.
| STATUS | CODE | DESCRIPTION |
|---|---|---|
| 401 | UNAUTHORIZED | Missing, malformed, or invalid API key |
| 403 | FORBIDDEN | Key exists but is revoked or lacks permission |
| 400 | INVALID_ID | The provided :id is not a valid UUID or breach ID |
| 404 | NOT_FOUND | No published breach found for that identifier |
| 429 | RATE_LIMITED | Rate limit exceeded — wait 60 seconds before retrying |
| 500 | QUERY_ERROR | Internal server error — please try again |
Security
CORS RESTRICTIONS
All /api/public/* routes enforce strict CORS. Only requests from authorized origins are accepted. Do not attempt to call the API directly from a browser on a foreign domain — preflight requests will be rejected.
KEY STORAGE
API keys are stored as SHA-256 hashes. We cannot recover your key if lost — only regenerate. Never commit keys to source control. Treat them like passwords.
RATE LIMITING
100 requests per 60-second window per key. Automated scraping will trigger rate limiting. Repeated violations may result in key revocation.
BEST PRACTICES
Set keys as environment variables (BREACHREGISTRY_API_KEY). Never expose in client-side code. Rotate regularly. Monitor your usage in /dashboard/api.