# Domains

A domain is one listing on your account. Everything here needs `domains:read`,
and the three writing endpoints need `domains:write`; see
[Authentication](https://ydomain.com/docs/api/authentication) for keys and abilities.

| Method | Path | Ability |
| --- | --- | --- |
| `GET` | `/domains` | `domains:read` |
| `GET` | `/domains/{domain}` | `domains:read` |
| `POST` | `/domains` | `domains:write` |
| `PATCH` | `/domains/{domain}` | `domains:write` |
| `DELETE` | `/domains/{domain}` | `domains:write` |

`{domain}` is either the UUID or the full domain name, so
`/domains/example.net` and `/domains/01920f1a-…` address the same listing.

## The domain object

```json
{
  "id": "01920f1a-6c4e-7a51-9d0b-4c8f2b7e1a33",
  "name": "example",
  "extension": "net",
  "domain": "example.net",
  "description": "Short and easy to say out loud.",
  "status": "active",
  "featured": false,
  "pricing": {
    "price": 1950,
    "sale_price": null,
    "sale_ends_at": null,
    "effective_price": 1950,
    "offer_from": 950,
    "currency": "EUR",
    "accepts_offers": true
  },
  "metrics": {
    "seo_score": 29,
    "moz_da": 31,
    "moz_links": 623,
    "moz_spam": 11,
    "majestic_tf": 28,
    "majestic_cf": 23,
    "traffic_per_month": 120,
    "updated_at": "2026-09-01T03:14:00+00:00"
  },
  "valuation": {
    "marketplace": 2400,
    "auction": 1400,
    "brokerage": 3100,
    "source": "estivai",
    "updated_at": "2026-09-01T03:14:00+00:00"
  },
  "categories": ["tech", "short"],
  "stats": {
    "views": 412,
    "leads": 3
  },
  "url": "https://ydomain.com/domains/example.net",
  "created_at": "2026-01-08T10:22:41+00:00",
  "updated_at": "2026-09-12T19:03:55+00:00"
}
```

`categories` is present when the listing was loaded with them, which is the
case on every endpoint here.

### Status

| Value | Meaning |
| --- | --- |
| `draft` | Not published; only you can see it |
| `active` | Published on the marketplace |
| `parked` | Published, but says nothing about a sale |
| `contact` | Published, no amount shown, offers welcome |
| `pending` | Under offer |
| `sold` | Sold |
| `expired` | Registration lapsed |
| `hidden` | Taken off the marketplace, kept on your account |

A `parked` listing, and any listing without a price, sale price or minimum
offer, shows no price, no offer invitation and no for-sale wording anywhere:
not on its page, not in a card, not in structured data. An `offer_amount` sent
to such a listing is dropped. This is a legal requirement, not a display
preference, so it is enforced on the server and cannot be switched off.

`sold` cannot be set through `POST /domains`; it is set by `PATCH` and stamps
`sold_at` for you.

### Pricing

- `price` — the asking price.
- `sale_price` — a temporary lower price; must be below `price`.
- `sale_ends_at` — when that sale price stops applying.
- `effective_price` — what a buyer actually sees right now: the sale price
  while it runs, otherwise the price.
- `offer_from` — the minimum offer you will consider.
- `accepts_offers` — whether the listing takes offers at all.

## List your domains

```bash
curl "https://ydomain.com/api/v1/domains?status=active&per_page=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

| Parameter | Default | Notes |
| --- | --- | --- |
| `status` | — | One of the status values above |
| `per_page` | `25` | Capped at 100 |
| `page` | `1` | |

```json
{
  "data": [
    {
      "id": "01920f1a-6c4e-7a51-9d0b-4c8f2b7e1a33",
      "domain": "example.net",
      "status": "active",
      "pricing": { "effective_price": 1950, "currency": "EUR" },
      "stats": { "views": 412, "leads": 3 }
    },
    {
      "id": "01920f1a-8d13-7b02-8a71-2f5c9e4d7b10",
      "domain": "example.org",
      "status": "parked",
      "pricing": { "effective_price": null, "currency": "EUR" },
      "stats": { "views": 88, "leads": 0 }
    }
  ],
  "links": { "next": "https://ydomain.com/api/v1/domains?page=2" },
  "meta": { "current_page": 1, "last_page": 74, "per_page": 2, "total": 148 }
}
```

The objects above are abbreviated; the full shape is the one at the top of this
page. Newest listings come first.

## Read one domain

```bash
curl https://ydomain.com/api/v1/domains/example.net \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```json
{
  "data": {
    "id": "01920f1a-6c4e-7a51-9d0b-4c8f2b7e1a33",
    "domain": "example.net",
    "status": "active",
    "pricing": { "price": 1950, "currency": "EUR", "accepts_offers": true }
  }
}
```

A domain that is not yours gives `404`.

## Create a domain

`name` and `extension` are separate, and the pair must be unique across the
marketplace. Everything else is optional; `currency` falls back to your account
currency and `status` to `active`.

```bash
curl -X POST https://ydomain.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "example",
    "extension": "org",
    "description": "A calm, brandable name for a lighting or wellness brand.",
    "price": 7250,
    "offer_from": 3500,
    "currency": "EUR",
    "status": "active",
    "categories": ["tech", "short"]
  }'
```

| Field | Rules |
| --- | --- |
| `name` | Required, max 63, letters, digits and hyphens |
| `extension` | Required, max 31; `co.uk` is fine |
| `description` | Optional, max 5000 |
| `status` | Optional, any status except `sold` |
| `price`, `sale_price`, `offer_from` | Optional numbers, 0–99,999,999 |
| `sale_price` | Must be lower than `price` |
| `sale_ends_at` | Optional date in the future |
| `currency` | Optional, three letters, a supported currency |
| `has_website` | Optional boolean |
| `redirect` | Optional `https` URL |
| `categories` | Optional, up to 5 category slugs |

`201 Created`:

```json
{
  "data": {
    "id": "01920f2b-51aa-7c14-9e02-6b3d8f1c4e77",
    "name": "example",
    "extension": "org",
    "domain": "example.org",
    "status": "active",
    "pricing": {
      "price": 7250,
      "effective_price": 7250,
      "offer_from": 3500,
      "currency": "EUR",
      "accepts_offers": true
    },
    "categories": ["short", "tech"],
    "url": "https://ydomain.com/domains/example.org",
    "created_at": "2026-09-17T08:12:03+00:00"
  }
}
```

A name that is already listed gives `422`:

```json
{
  "message": "That domain is already listed.",
  "errors": { "name": ["That domain is already listed."] }
}
```

This also fires the `domain.created` webhook.

## Update a domain

Send only what changes. Leaving `categories` out keeps the current ones;
sending `[]` clears them.

```bash
curl -X PATCH https://ydomain.com/api/v1/domains/example.org \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"price": 6500, "sale_price": 5900, "sale_ends_at": "2026-12-31T23:59:59+00:00"}'
```

```json
{
  "data": {
    "domain": "example.org",
    "pricing": {
      "price": 6500,
      "sale_price": 5900,
      "sale_ends_at": "2026-12-31T23:59:59+00:00",
      "effective_price": 5900,
      "currency": "EUR"
    },
    "updated_at": "2026-09-17T08:20:44+00:00"
  }
}
```

Setting `"status": "sold"` stamps the sale date and fires `domain.sold`. Every
other change fires `domain.updated`.

## Delete a domain

```bash
curl -X DELETE https://ydomain.com/api/v1/domains/example.org \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```http
HTTP/1.1 204 No Content
```

The listing is soft deleted: it disappears from the marketplace and from the
API, and its leads are kept. Fires `domain.deleted`.