Developer API
REST access to ranked drops, search, dossiers, watchlists, portfolio, and CSV exports. Available on Pro ($29/mo, 100 req/day) and API ($99/mo, 10,000 req/day).
Base URL
https://namenotifier.comGenerate an API key from your account page. Free and Core plans cannot use the JSON API; Core can still export CSV from the UI.
Generate an API key from your account page → API tab. Keys look like nn_ plus 48 hex characters. Store the plaintext — we only keep a bcrypt hash, so we can’t show it to you again after the first view.
Send the key on every request as a Bearer token:
curl https://namenotifier.com/api/v1/drops \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"| Plan | Requests / day | CSV export |
|---|---|---|
| Free | — | — |
| Core ($12 / mo) | — | yes |
| Pro ($29 / mo) | 100 | yes |
| API ($99 / mo) | 10,000 | yes |
Every successful response includes these headers so you can back off before hitting a 429:
x-ratelimit-limit: 100
x-ratelimit-remaining: 99
x-ratelimit-reset: 1776595200 # unix seconds, next midnight UTCRate-limit window resets at 00:00 UTC. Limits are enforced per user account, so rotating an API key does not reset usage.
Every error response is JSON with an error field. HTTP status codes follow the usual conventions.
401 { "error": "authentication required" }
403 { "error": "CSV export requires the Core plan or above" }
404 { "error": "not found" }
429 { "error": "rate limit exceeded",
"plan": "pro",
"limit": 100,
"resetAt": 1776595200000 }Latest active drop list by default, scored and sorted by DQS. Results respect the registeredAgain filter — domains re-claimed by the original owner are excluded automatically.
| Param | Example | Meaning |
|---|---|---|
| tld | com,io | CSV of TLDs to filter |
| min_dqs | 55 | Minimum DQS 0–100 |
| max_len | 8 | Maximum SLD length (chars) |
| q | ai | Case-insensitive substring match on domain name |
| stage | catchable | One of redemption | pending-delete | catchable | released |
| view | active | active (default) | today | all. Ignored when stage is set. |
| limit | 100 | Max rows returned. Default 100, max 1000. |
{
"date": "2026-05-19",
"count": 3,
"limit": 100,
"offset": 0,
"availableTlds": ["com", "io", "org", ...],
"drops": [
{
"name": "namenotifier.com",
"tld": "com",
"length": 12,
"dqs": 64,
"explanation": "clear product-name domain with strong brand fit",
"signals": { "lengthBand": "short", "dictionary_quality": 0.0, ... }
},
...
]
}The signals object contains the DQS component breakdown — shape varies by scorer version. Treat unknown keys as optional.
Full-corpus prefix search powered by the same FTS index as the web search page. Useful when you know the stem or keyword you want and need to find both active and historical dossiers.
| Param | Example | Meaning |
|---|---|---|
| q | namenotifier | Required search query. Prefix-style matching. |
| tld | com,net | Optional CSV of TLDs |
| stage | redemption | Optional lifecycle filter |
| view | active | Limit to active pipeline when stage is not set |
| min_dqs | 40 | Minimum DQS 0–100 |
| max_len | 12 | Maximum SLD length |
| limit | 20 | Default 20, max 100 |
| offset | 100 | Pagination offset, max 10,000 |
curl "https://namenotifier.com/api/v1/search?q=namenotifier&tld=com" \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"{
"query": "namenotifier",
"total": 1,
"totalCapped": false,
"count": 1,
"limit": 20,
"offset": 0,
"results": [
{
"domain": "namenotifier.com",
"tld": "com",
"length": 12,
"currentStatus": "available",
"latestDrop": {
"date": "2026-05-19",
"dqs": 64,
"explanation": "clear product-name domain with strong brand fit"
}
}
]
}Dossier for a single domain. Includes the latest drop record (null if the name is no longer in the active pipeline) and community feedback totals.
curl https://namenotifier.com/api/v1/domain/namenotifier.com \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"{
"domain": "namenotifier.com",
"tld": "com",
"length": 12,
"currentStatus": "available",
"dropPredictedAt": null,
"latestDrop": {
"date": "2026-05-19",
"dqs": 64,
"explanation": "clear product-name domain with strong brand fit",
"signals": { ... }
},
"feedback": { "up": 12, "down": 1 }
}currentStatus is the pipeline’s internal flag — do not use it as a user-facing label. For the honest lifecycle stage (redemption / pending-delete / catchable / released) derive from latestDrop.date against today, or see the full rendered dossier at /domain/{name}.
404 is returned when the domain has never been observed by the ingest pipeline.
Your backorder claims — the /portfolio UI exposed as JSON. Includes alert-rule attribution when you marked the claim as triggered by a saved filter.
| Param | Example | Meaning |
|---|---|---|
| status | caught,sold | CSV of attempted | caught | registered | lost | sold |
| from | 2026-05-01 | ISO date — filter reportedAt >=from |
| to | 2026-05-31 | ISO date — filter reportedAt <to |
| limit | 100 | Max rows. Default 100, max 1000. |
{
"count": 1,
"claims": [
{
"id": 42,
"domain": "namenotifier.com",
"tld": "com",
"status": "caught",
"registrar": "godaddy",
"acquiredPriceUsd": 50,
"resalePriceUsd": null,
"soldAt": null,
"reportedAt": "2026-05-19T12:00:00.000Z",
"updatedAt": "2026-05-19T12:00:00.000Z",
"userNotes": "example portfolio note",
"alertRule": { "id": 5, "name": "example saved filter" }
}
]
}Scriptable watchlist management for Pro and API customers. Adding a domain uses the same paid-plan external-domain quota as the UI when the name is not yet in the corpus, then queues DNS/RDAP verification.
curl "https://namenotifier.com/api/v1/watchlist?sort=lifecycle&limit=100" \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"curl https://namenotifier.com/api/v1/watchlist \
-X POST \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"domainName":"example.com"}'curl "https://namenotifier.com/api/v1/watchlist?domain=example.com" \
-X DELETE \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"{
"count": 1,
"limit": 100,
"offset": 0,
"sort": "lifecycle",
"summary": { "total": 1, "external": 0, "renewed": 0, "checkable": 1 },
"watchlist": [
{
"domain": "example.com",
"source": "corpus",
"rdapObservedState": "redemption",
"rdapVerifiedAt": "2026-05-21T08:00:00.000Z",
"latestDropDate": "2026-05-21",
"dqs": 64
}
]
}Programmatic alert-rule management for Pro and API customers. Same validation as the in-app surface — plan caps on number of active rules, plan-gated channel types (free is email only; core/pro/api add webhook + telegram), and SSRF guard on webhook URLs.
curl "https://namenotifier.com/api/v1/alerts?limit=50" \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"curl https://namenotifier.com/api/v1/alerts \
-X POST \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Short .com / .net brandables",
"filter": { "tlds": ["com","net"], "minDqs": 70, "maxLength": 8 },
"channels": [{ "type": "email" }]
}'curl https://namenotifier.com/api/v1/alerts/42 \
-X PATCH \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "active": false }'curl https://namenotifier.com/api/v1/alerts/42 \
-X DELETE \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"{
"count": 1,
"limit": 50,
"offset": 0,
"alerts": [
{
"id": 42,
"name": "Short .com / .net brandables",
"filter": { "tlds": ["com","net"], "minDqs": 70, "maxLength": 8 },
"channels": [{ "type": "email" }],
"active": true,
"createdAt": "2026-05-22T15:00:00.000Z"
}
]
}POST returns 201 with { "id": <new>, "alert": { ... } }. Plan-cap or channel-gate violations return 403 with code: "PLAN_LIMIT". Webhook URLs that fail the SSRF guard return 400 with a clear message.
CSV export of the ranked drops feed. Accepts the same filter params as /api/v1/drops plus stage, and returns up to 10,000 rows per call. Requires Core plan or above (free gets 403).
curl -OJ https://namenotifier.com/api/export/drops?tld=com,io&min_dqs=60 \
-H "Authorization: Bearer nn_xxxxxxxxxxxxxxxxxxxxxxxx"Response headers include Content-Disposition: attachment; filename="drops-YYYY-MM-DD.csv". Columns: domain,tld,length,dqs,explanation. Explanation is quoted with doubled inner quotes (standard CSV).
Cookie-session auth also works for this endpoint — the web UI’s “Export” button uses the same URL without an Authorization header. API-key auth is the recommended path for scripts.
Watchlist CSV export is also scriptable with the same Bearer header at /api/export/watchlist, up to 10,000 rows per file.
Portfolio/backorder claim CSV export is available at /api/export/portfolio for Core plan and above, with the same daily export budget and 10,000-row file cap.
Three unauthenticated endpoints for monitors. Keep the distinction in mind when wiring alerts — the shallow health endpoint stays 200 even when data is stale (Docker depends on that), while /api/ready/ingest is the honest “is the ingest pipeline fresh” canary.
| Path | Shape | Use for |
|---|---|---|
| /api/health | { status, latestDropDate, stale, uptime } | Docker healthcheck — always 200 |
| /api/ready | { ready, uptime, node, checks: { database, drops, environment } } | Boot-up readiness probe |
| /api/ready/ingest | { status, latestDropDate, hoursOld, staleAfterHours } | External monitors — 503 when drops >48h stale |
{
"status": "ok",
"latestDropDate": "2026-05-19",
"stale": false,
"uptime": 86412
}Unauthenticated index returning the list of public endpoints and auth instructions. Useful as a smoke test from a script.
{
"name": "NameNotifier Public API",
"version": "1.0",
"endpoints": [
{ "method": "GET", "path": "/api/v1/drops", ... },
{ "method": "GET", "path": "/api/v1/search", ... },
{ "method": "GET", "path": "/api/v1/domain/{name}", ... },
{ "method": "GET", "path": "/api/v1/portfolio", ... },
{ "method": "GET/POST/DELETE", "path": "/api/v1/watchlist", ... }
],
"auth": "Authorization: Bearer nn_xxxxxx — generate on your /account page.",
"docs": "https://namenotifier.com/api-docs"
}Open a support ticket from the support page. Production API behavior should match this document exactly — if you observe a mismatch, file it as a bug and include the exact request + response.