REST API
Base address https://nymwell.com/api/v1. JSON in and out. Every response has an x-request-id header; quote it when you ask for help.
Authentication
| Endpoints | Send |
|---|---|
| Search, suggestions, ending info, screening, status | Nothing |
| Everything on an account | An agent key: X-Nymwell-Key: nw_ (or Authorization: Bearer nw_) |
A signed-in owner creates agent keys in AI Agents or with POST /api/v1/api-keys, with scopes (domains:read, dns:read, quotes:create, orders:create, actions:prepare, actions:read), an optional domain allowlist and an expiry of up to 90 days. MCP clients sign in with OAuth instead; see MCP and sign-in.
Public endpoints
Rate limited to 30 searches a minute per client; past that the answer is 429 with retry_after_seconds.
| Request | Answers |
|---|---|
GET /api/v1/status | What is live: registrar, payments, sign-in |
GET /api/v1/domains/search?domain=example.com | One exact name, from the registrar |
GET /api/v1/domains/search?q=example&tlds=com,ai,io | One name across up to 20 endings |
GET /api/v1/domains/suggest?q=coffee+roaster | Names the registrar can sell now |
GET /api/v1/domains/tld-info?tlds=ai,io | Registration, renewal and transfer prices and rules per ending |
GET /api/v1/domains/screen?q=example | Public-record screen (RDAP and DNS). Not availability. |
curl "https://nymwell.com/api/v1/domains/search?q=yourbrandlab&tlds=com,dev"{
"results": [
{"domain": "yourbrandlab.com", "available": false, "tier": null, "reason": "domain_unavailable", "buy_url": null},
{"domain": "yourbrandlab.dev", "available": true, "tier": "standard", "price_minor": 1649, "price_display": "US$16.49",
"renewal_minor": 2529, "renewal_display": "US$25.29", "reason": null, "buy_url": "https://nymwell.com/buy?domain=yourbrandlab.dev"}
],
"suggestions": [],
"currency": "USD",
"source": "namecom:live"
}Prices are integers in cents (price_minor) and display strings. The first price is the first term at the ending's minimum length; renewal_* is what renewing for that length costs. suggestions offers priced alternatives when names are taken.
Buy links
GET https://nymwell.com/buy?domain=example.com (add &lang=zh-tw for Traditional Chinese). A signed-out person goes through Google sign-in; then the console opens on that name with its price, and they pay on Stripe Checkout. No key is involved.
Account endpoints
The same actions as the MCP tools. Each mutation that waits on a person or the registrar returns a workflow object (see Statuses and errors).
| Request | Does |
|---|---|
POST /api/v1/quotes {"domain", "action": "register"/"renew"/"transfer", "years", "currency": "USD"} | Locks a price for 40 minutes |
POST /api/v1/orders {"quote_ | Starts paying: returns the order with checkout_ for the person |
GET /api/v1/orders?id= | Where an order is, with workflow |
GET /api/v1/domains | Domains in the workspace |
GET /api/v1/domains/detail?domain= | Live state from the registrar |
GET /api/v1/dns/records?domain= | DNS records |
POST /api/v1/dns/change-sets | Prepares DNS creates, updates and deletes for approval |
GET /api/v1/approvals | Changes waiting for a person, each with workflow |
POST /api/v1/domains/settings, /nameservers, /contacts, /auth-code, /cancel, /services | Prepares a domain change for approval |
The full contract, with every field: https://nymwell.com/openapi.json
Errors
Errors are JSON with an error code and the matching HTTP status, for example {"error": "quote_expired", "next": "Call get_quote again."}. Every code is in Statuses and errors.