URL: /docs/api/my-domains

---
title: "My domains: track your own names"
sidebarTitle: My domains
description: 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.
icon: list-checks
---

`/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](/docs/mcp/tools#my-domains).

<Note>
  These routes are live but are not in the [OpenAPI document](https://getrevised.com/api/v1/openapi.json), so the Reference tab does not list them. This page is their reference.
</Note>

## 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

```bash
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.

```json Response (illustrative)
{
  "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](/docs/api/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).

```json Row (illustrative)
{
  "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](/docs/api/lookup) 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`](/docs/guides/checks-on-any-domain#valuation) and [`POST /api/v1/history`](/docs/guides/checks-on-any-domain#spam-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](/docs/api/errors) for the envelope.
