# REST API

Base URL: `https://domains.ingram.tech/api/v1`

The authoritative reference is generated from the same schemas that validate
every request, so it cannot drift from behaviour:

- **Swagger UI**: [`/api/v1/docs`](https://domains.ingram.tech/api/v1/docs)
- **OpenAPI 3.1**: [`/api/v1/openapi.json`](https://domains.ingram.tech/api/v1/openapi.json)

Authentication is `Authorization: Bearer ingram_live_…` (see
[Authentication](/docs/authentication)); errors use the envelope and codes in
[Errors & idempotency](/docs/errors); every mutation accepts
`Idempotency-Key`.

## Endpoint map

| Method & path | Auth | What it does |
|---|---|---|
| `GET /check?q=…` | public | Availability + retail price for a name or domain |
| `GET /suggest?q=…` | public | Related-name suggestions (names only) |
| `GET /tlds` | public | Register / renew / transfer / trade EUR prices per TLD |
| `POST /accounts` | public | Programmatic signup → user + workspace + token (optional `prefund`) |
| `GET /domains` | read | List the workspace portfolio, with each domain's cached registry snapshot (status, expiry, auto-renew, DNSSEC, nameservers, lock) and `syncedAt` |
| `GET /domains/{name}` | read | Registry details: status, dates, nameservers, locks — plus `renewal` (next charge date, price, term state) |
| `POST /domains` | write | Register — `domain`, `duration`, `confirm_price`, optional payment |
| `POST /domains/{name}/renew` | write | Renew — `duration`, `confirm_price`, optional payment |
| `POST /domains/{name}/transfer` | write | Transfer in — `auth_code`, `confirm_price`, optional payment |
| `DELETE /domains/{name}` | write | Delete / schedule release |
| `PATCH /domains/{name}/settings` | write | Toggle `auto_renew`, `registrar_lock`, `whois_privacy`, `dnssec` (auto-renew is billed; see Conventions) |
| `POST /domains/{name}/auth-code` | write | Email the EPP/auth code to the registrant |
| `GET /domains/{name}/zone` | read | List DNS records (hosted zones only) |
| `POST /domains/{name}/zone` | write | Create a DNS record |
| `DELETE /domains/{name}/zone` | write | Delete a DNS record (by subdomain+type+value) |

## Conventions

- **Prices** are EUR retail; spending requires `confirm_price`
  ([Payments](/docs/payments)).
- **Auto-renew is billed from your wallet** about 30 days before expiry, at
  the renewal price. Unpaid by 10 days before expiry, the domain is left to
  expire. Turning it off before the charge costs nothing; after the charge
  the renewal stands, and `PATCH …/settings` returns `renewed_until`.
  A renewal of a term already being bought answers `409 renewal_in_progress`.
- **`GET /domains/{name}` tells you when you'll be charged.** Its `renewal`
  object carries `auto_renew`, `expires_at`, `billed_until` (what you've paid
  for), `next_charge_at`, `price`, and `term` — the current renewal's state
  with `reason` and, when the wallet is short, `shortfall` in EUR. See
  [Payments](/docs/payments#auto-renew).
- **Registry mutations are async** — a success with registry status
  `Pending` completes at the registry moments-to-days later, depending on
  the operation.
- **Names** are lowercased; IDN domains use their punycode (`xn--…`) form.
- Responses are `application/json`; list endpoints send
  `Cache-Control: private, no-store`.