My domains: track your own names
The /api/v1/my-domains routes keep a private list of the names you own or follow, with the latest values Revised holds for each and a log of what changed.
/api/v1/my-domains keeps a private list of names you own or follow. Each row carries the latest values Revised holds for the name, and a change log records what moved. Any registrable domain works, not only names Revised tracks. It is on every plan and costs nothing.
The list belongs to the account behind the key: every key and every MCP session on the account sees the same list, and no name in it is shown to anyone else. The MCP equivalents are the My domains tools.
Routes
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/my-domains | The list, newest first. |
POST | /api/v1/my-domains | Add names. |
GET | /api/v1/my-domains/{id} | One row. |
PATCH | /api/v1/my-domains/{id} | Set a row’s label or note. |
DELETE | /api/v1/my-domains/{id} | Remove one row. |
POST | /api/v1/my-domains/remove | Remove many rows. |
GET | /api/v1/my-domains/changes | The change log. |
GET | /api/v1/my-domains/alerts | Digest settings. |
PUT | /api/v1/my-domains/alerts | Change digest settings. |
A row id is a UUID from the list or from an add. Names never go in a URL: a row is addressed by its id.
Add names
curl -X POST https://getrevised.com/api/v1/my-domains \
-H "Authorization: Bearer $REVISED_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domains": ["example.com", "https://shop.example.org/", "not a domain"], "label": "portfolio"}'domains takes 1 to 2,000 names or URLs a request; send more in another request. Each is reduced to its registrable domain (shop.example.org is stored as example.org) and de-duplicated. label is optional, up to 80 characters, and applies to every name the request adds.
{
"accepted": [
{ "domain": "example.com", "id": "0b8f3c2e-5a41-4d7e-9c1a-2f6b8e4d1a90" },
{ "domain": "example.org", "id": "6c2d9e1f-3b7a-4e58-a0d4-9f1e2c3b4a57" }
],
"duplicate": [],
"invalid": [{ "input": "not a domain", "reason": "…" }],
"counts": { "accepted": 2, "duplicate": 0, "invalid": 1, "submitted": 3, "total_in_list": 2 }
}duplicate lists names already in the list or repeated in the request. invalid echoes what could not be stored, with the reason.
The account’s cap on stored names applies to the whole request: if the request would pass it, nothing is added. The answer is 429 rate_limited with refusal: "limit_reached", cap, count (names held) and remaining (how many more fit). Waiting does not change it; send fewer names or remove some. The cap is on Plans and limits.
Read the list
GET /api/v1/my-domains takes limit (default 25, 1 to 50) and offset. It returns items, total, limit, offset and next_offset (null on the last page).
{
"id": "0b8f3c2e-5a41-4d7e-9c1a-2f6b8e4d1a90",
"domain": "example.com",
"label": "portfolio",
"note": null,
"added_at": "2026-11-02T09:14:03.120Z",
"updated_at": "2026-11-02T09:14:03.120Z",
"summary": {
"valuation": null,
"history_verdict": null,
"citability": null,
"referring_domains": 37,
"registration_status": null,
"expiry": null
}
}summary holds the latest stored values: valuation (low_usd, high_usd), history_verdict, citability (band, score), referring_domains, registration_status and expiry (expires_at, days_until_expiry). A null is data we do not hold yet, never a zero. Reading the list never starts a live check; look a name up with live=1 for that.
valuation and history_verdict are part of the shape but stay null today. The list, and the scheduled re-check behind the change log, read stored data only (links, traffic, archive, citability, and registration where a live lookup left it) and never run the valuation or history checks. Use GET /api/v1/valuation and POST /api/v1/history for those.
GET /api/v1/my-domains/{id} returns one row in the same shape. An id that is not in your list, including one that belongs to someone else, is 404.
Label, note and remove
PATCH /api/v1/my-domains/{id} takes {"label": "...", "note": "..."}: a label up to 80 characters, a note up to 1,000. A key you leave out is unchanged; null or "" clears it. It returns the updated row.
DELETE /api/v1/my-domains/{id} removes one row and returns {"removed": 1, "not_found": 0}, or 404 when the id is not in your list.
POST /api/v1/my-domains/remove takes {"ids": [...], "domains": [...]}, either or both, up to 2,000 entries in all. Names are normalised the way an add normalises them. It returns removed and not_found (how many matched nothing). Removing is permanent: add a name again to restore it, without its old label and note.
What changed
GET /api/v1/my-domains/changes is the change log of your own names, newest first. It is built from stored data re-checked on a schedule, so it never starts a live check.
| Parameter | Meaning |
|---|---|
since | An ISO date or datetime, e.g. 2026-11-01. Only changes after it. |
domain_id | One row’s id. |
material_only | true for only the changes a digest would list. |
limit, offset | Default 50, up to 200. |
It returns items, total, limit, offset, next_offset and since (the filter echoed back, or null). Each entry has domain, domain_id, changed_at and changes, a list of {field, from, to, material}.
Digest settings
GET /api/v1/my-domains/alerts returns cadence (off, daily or weekly) and types, a switch per change type: valuation, history_verdict, citability_band, referring_domains, registration_status, expiry_date, availability and expiry_soon (expiry within 30 days). The digest is off until you choose a cadence.
PUT /api/v1/my-domains/alerts takes {"cadence": "...", "types": {"<type>": true}}. A key you leave out is unchanged, and choosing daily or weekly is the opt-in. Only your own names are ever in a digest, and every digest has a one-click unsubscribe.
Errors
| Status | error.code | When |
|---|---|---|
| 400 | invalid_request | A body that is not a JSON object or is too large, no names, more than 2,000 entries, or a label or note over its length. |
| 404 | not_found | An id that is not in your list. |
| 409 | conflict | A new account still being set up. Carries Retry-After: 60. |
| 429 | rate_limited | The stored-name cap, as above, or the per-key rate limit. |
See Errors for the envelope.