# 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` | read | Register / renew / transfer EUR prices per TLD |
| `POST /accounts` | public | Programmatic signup → user + workspace + token (optional `prefund`) |
| `GET /domains` | read | List the workspace portfolio |
| `GET /domains/{name}` | read | Registry details: status, dates, nameservers, locks |
| `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` |
| `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)).
- **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`.