# ydomain developer documentation

Three separate things live here. They share one account and one set of
listings, and nothing else: you can use any of them without the others.

| | What it is | Start at |
| --- | --- | --- |
| **API** | An HTTP API you call. Manage listings, read and answer leads, manage endpoints. Needs an API key. | [Authentication](https://ydomain.com/docs/api/authentication) |
| **Webhooks** | Calls we make to you. A signed `POST` to a URL of yours whenever something changes. Needs no key. | [Events and deliveries](https://ydomain.com/docs/webhooks) |
| **Embeds** | Two script tags. Put a contact form, or the whole landing page, on a domain you own. Needs nothing at all. | [Scripts](https://ydomain.com/docs/embeds) |

Most integrations use two of the three: webhooks to hear that something
happened, the API to read the details and act.

## The API

- **Base URL:** `https://ydomain.com/api/v1`
- **Format:** JSON in, JSON out. Send `Accept: application/json`.
- **Authentication:** a bearer API key on every request.
- **Version:** `v1`. A breaking change gets a new prefix; fields are only ever added inside `v1`.

| Page | What is in it |
| --- | --- |
| [Authentication](https://ydomain.com/docs/api/authentication) | Keys, abilities, rate limits, pagination, errors |
| [Domains](https://ydomain.com/docs/api/domains) | List, read, create, update and delete listings |
| [Leads](https://ydomain.com/docs/api/leads) | Read enquiries, change status, reply to the buyer |
| [Webhook endpoints](https://ydomain.com/docs/api/webhooks) | Create and remove endpoints over the API |

### A first request

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

```json
{
  "data": {
    "id": "01920f1a-6c4e-7a51-9d0b-4c8f2b7e1a33",
    "name": "Renee de Vries",
    "email": "renee@example.com",
    "locale": "nl",
    "currency": "EUR",
    "abilities": ["domains:read", "leads:read"],
    "counts": {
      "domains": 148,
      "leads": 27
    }
  }
}
```

`GET /me` needs no ability beyond a valid key, so it is the quickest way to
check that a key works and to see what it is allowed to do.

### Conventions

- **Identifiers** are UUIDv7 strings. A listing can also be addressed by its
  full domain name, so `GET /domains/example.com` works as well as the id.
- **Timestamps** are ISO 8601 with an offset: `2026-02-14T09:31:07+00:00`.
- **Money** is a number plus a separate three-letter currency, never a
  formatted string. `4950` and `"EUR"`, not `"€4.950"`.
- **A single record** is returned under `data`. **A list** is returned under
  `data` with `links` and `meta` beside it.
- **Nothing is returned for a delete**: the status is `204` with an empty body.
- **Unknown fields in a request body are ignored**, so sending a whole object
  back after changing one field is safe.

## Webhooks

A webhook is the other direction: we `POST` to a URL of yours, signed, whenever
something happens on your account. Endpoints are set up under
**Settings → Webhooks** in the account area, or over the API.

Read [Events and deliveries](https://ydomain.com/docs/webhooks) for the list of events, the
body we send and how to verify the signature.

## Embeds

Two script tags, for a domain you already own: one puts the whole landing page
on it, the other puts only a contact form somewhere on your own page. No key,
no account setup, nothing to configure — the script works out which listing it
belongs to from the page it runs on.

Read [Scripts](https://ydomain.com/docs/embeds).

## Reading these docs as text

Every page is also served as Markdown, which is what you want if you are
feeding this to a model or a script:

- One page: `https://ydomain.com/docs/api/domains.md`
- Everything at once: `https://ydomain.com/docs/llms-full.txt`
- The index: `https://ydomain.com/llms.txt`