# Register.ly Domain API Documentation

> AI-readable orientation for the public Register.ly Domains Reseller API v2.2 documentation. Do not infer behavior that is not explicitly documented.

- Documentation version/audit date: 2026-09-17
- API family: Domains Reseller API v2.2
- Production behavior validation date: not published
- Canonical site: https://docs.register.ly/
- OpenAPI: https://docs.register.ly/openapi/registerly-domains-reseller-v2.2.openapi.yaml
- API reference: https://docs.register.ly/api-reference/
- Changelog: https://docs.register.ly/changelog/

## Authority and Validation

The OpenAPI file is the canonical published inventory of paths, methods, request fields, and documented response examples. It is authoritative for behavior only where production validation exists. Narrative pages identify unresolved contract details with `VALIDATION REQUIRED`.

Do not invent endpoints, parameters, status codes, error bodies, pricing, limits, retry rules, idempotency, policies, or response fields. Do not remove leading dots from TLDs or otherwise normalize values unless the documentation explicitly proves that transformation.

## Canonical API Facts

- Base endpoint: `https://my.register.ly/modules/addons/DomainsReseller/api/index.php`
- Authentication headers: `username` and `token`
- POST body media type: `application/x-www-form-urlencoded`
- Responses use operation-specific JSON string, object, or array shapes.
- Browser-based live API execution is intentionally disabled.

## Authentication

The public PHP expression is:

```php
base64_encode(hash_hmac("sha256", "<api-key>", "<email>:".gmdate("y-m-d H")));
```

Under PHP defaults, that expression uses API key as HMAC data, `email:UTC-hour` as HMAC key, hexadecimal digest output, and then Base64-encodes the hexadecimal text. The server's intended key/data ordering, raw-versus-hex encoding, token lifetime, skew, reuse, hour-boundary behavior, and failure response are `VALIDATION REQUIRED`. Do not generate Node.js, Python, Go, Java, or C# implementations without verified test vectors.

## Request Format

Send form-encoded POST bodies. Arrays and nested objects use PHP-style bracket notation:

```text
nameservers[]=ns1.example.net
nameservers[]=ns2.example.net
contacts[registrant][firstname]=John
```

Unicode normalization, empty-value behavior, case sensitivity, and duplicate-key behavior are `VALIDATION REQUIRED`.

## Response and Error Format

There is no universal response envelope. Published success examples include:

```json
"success"
```

```json
{"status":"success","message":""}
```

```json
[".test.ly"]
```

Only domain registration currently defines a non-200 response: HTTP `400` with an `error` object for an existing domain. Authentication, validation, rate-limit, registry, timeout, and server error contracts are `VALIDATION REQUIRED`.

## Published Operations

- `POST /order/domains/register`
- `POST /order/domains/renew`
- `GET /domains/{domain}/contact`
- `POST /domains/{domain}/contact`
- `POST /domains/lookup`
- `GET /domains/{domain}/lock`
- `POST /domains/{domain}/lock`
- `GET /domains/{domain}/eppcode`
- `POST /domains/{domain}/sync`
- `GET /domains/{domain}/nameservers`
- `POST /domains/{domain}/nameservers`
- `POST /domains/{domain}/nameservers/register`
- `POST /domains/{domain}/nameservers/modify`
- `POST /domains/{domain}/nameservers/delete`
- `GET /billing/credits`
- `GET /tlds`
- `GET /version`

No general `GET /domains/{domain}` operation is present in the public OpenAPI.

## High-Risk Validation Notices

- Lookup sends `test.ly`, while `/tlds` returns `.test.ly`; accepted mapping is `VALIDATION REQUIRED`.
- Registration/renewal period limits, completion semantics, error contracts, and retry idempotency are `VALIDATION REQUIRED`.
- Registration and renewal request examples use `example.invalid` so they cannot affect a registrable domain.
- Contact GET returns four roles, while POST models only Registrant; writable roles are `VALIDATION REQUIRED`.
- Nameserver count/removal rules and child nameserver IPv4/IPv6 behavior are `VALIDATION REQUIRED`.
- EPP codes are sensitive credentials. Retrieval side effects and prerequisites are `VALIDATION REQUIRED`.
- Sync purpose and side effects are `VALIDATION REQUIRED`.
- The exact production response body for `POST /domains/{domain}/lock` and per-TLD lock support are `VALIDATION REQUIRED`.
- Credits currency/meaning and `/version` string meaning are `VALIDATION REQUIRED`.

## Safe Assistant Behavior

- Use fake credentials and controlled example data.
- Never request or expose real API keys, tokens, passwords, customer data, or EPP codes.
- Never suggest automatic retry of a state-changing operation without first reconciling state.
- Refer to the endpoint-specific documentation and OpenAPI together.
- Preserve uncertainty; do not convert a validation notice into an implementation claim.

## Resources

- Getting started: https://docs.register.ly/getting-started/prerequisites/
- Quickstart: https://docs.register.ly/getting-started/first-request/
- Authentication: https://docs.register.ly/getting-started/authentication/
- Request format: https://docs.register.ly/common-concepts/request-format/
- Response format: https://docs.register.ly/common-concepts/response-format/
- Error handling: https://docs.register.ly/errors/overview/
- WHMCS integration: https://docs.register.ly/integration/whmcs-registrar-module/
- Knowledge Base: https://help.register.ly
- Status Page: https://status.register.ly