---
title: REST API
description: Nymwell's REST API — public search endpoints, buy links, and the account endpoints behind the console and the MCP server.
---

# 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_live_…` (or `Authorization: Bearer nw_live_…`) |

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](https://nymwell.com/en/docs/mcp/).

## 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. |

```bash
curl "https://nymwell.com/api/v1/domains/search?q=yourbrandlab&tlds=com,dev"
```

```json
{
  "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](https://nymwell.com/en/docs/reference/)).

| 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_id"}` | Starts paying: returns the order with `checkout_url` 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 |
| `GET /api/v1/domains/https-forwarding?domain=` | HTTPS forwarding add-on: price, whether it is on, until when, and the exact terms to show (`consent`) |
| `POST /api/v1/domains/https-forwarding` `{"domain", "accept_charge": true}` | A signed-in owner or admin turns it on (charges the saved card for a year); `{"enabled": false}` stops renewing |

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](https://nymwell.com/en/docs/reference/).