---
title: REST API
description: Nymwell 的 REST API：公開查詢端點、購買連結，以及控制台與 MCP 共用的帳戶端點。
---

# REST API

基本位址 `https://nymwell.com/api/v1`，輸入與輸出都是 JSON。每個回應都有 `x-request-id` header，詢問問題時請附上。

## 驗證

| 端點 | 需要送出 |
| --- | --- |
| 查詢、建議、結尾資訊、初篩、狀態 | 不需要 |
| 所有帳戶相關操作 | Agent key：`X-Nymwell-Key: nw_live_…`（或 `Authorization: Bearer nw_live_…`） |

已登入的擁有者可在「AI Agents」或用 `POST /api/v1/api-keys` 建立 agent key，設定權限範圍（`domains:read`、`dns:read`、`quotes:create`、`orders:create`、`actions:prepare`、`actions:read`）、可選的網域允許清單與最長 90 天期限。MCP client 則改用 OAuth 登入，見 [MCP 與登入](https://nymwell.com/zh-tw/docs/mcp/)。

## 公開端點

每個 client 每分鐘最多 30 次查詢，超過會回 429 與 `retry_after_seconds`。

| 請求 | 回答 |
| --- | --- |
| `GET /api/v1/status` | 目前開放什麼：註冊商、金流、登入 |
| `GET /api/v1/domains/search?domain=example.com` | 單一網域，向註冊商即時查詢 |
| `GET /api/v1/domains/search?q=example&tlds=com,ai,io` | 同一名稱搭配最多 20 個結尾 |
| `GET /api/v1/domains/suggest?q=coffee+roaster` | 註冊商現在能賣的建議名稱 |
| `GET /api/v1/domains/tld-info?tlds=ai,io` | 各結尾的註冊、續約、轉入價格與規則 |
| `GET /api/v1/domains/screen?q=example` | 公開紀錄初篩（RDAP 與 DNS），不代表可註冊 |

```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"
}
```

價格以美分整數（`price_minor`）與顯示字串提供。第一個價格是該結尾最短年限的首期價格，`renewal_*` 是同樣年限的續約價格。網域已被註冊時，`suggestions` 會提供附價格的替代選項。

## 購買連結

`GET https://nymwell.com/buy?domain=example.com`（加 `&lang=zh-tw` 顯示繁體中文）。未登入的人會先用 Google 登入，接著控制台會打開該網域與價格，在 Stripe Checkout 付款。全程不需要 key。

## 帳戶端點

與 MCP 工具是同一組操作。需要等人、等付款或等註冊商的操作，都會回傳 `workflow` 物件（見[狀態與錯誤碼](https://nymwell.com/zh-tw/docs/reference/)）。

| 請求 | 作用 |
| --- | --- |
| `POST /api/v1/quotes` `{"domain", "action": "register"/"renew"/"transfer", "years", "currency": "USD"}` | 鎖定價格 40 分鐘 |
| `POST /api/v1/orders` `{"quote_id"}` | 開始付款：回傳附 `checkout_url` 的訂單，交給使用者 |
| `GET /api/v1/orders?id=` | 訂單進度，附 `workflow` |
| `GET /api/v1/domains` | 工作空間的網域 |
| `GET /api/v1/domains/detail?domain=` | 註冊商上的即時狀態 |
| `GET /api/v1/dns/records?domain=` | DNS 紀錄 |
| `POST /api/v1/dns/change-sets` | 準備 DNS 新增、修改、刪除，等待核准 |
| `GET /api/v1/approvals` | 等待本人核准的變更，各附 `workflow` |
| `POST /api/v1/domains/settings`、`/nameservers`、`/contacts`、`/auth-code`、`/cancel`、`/services` | 準備網域變更，等待核准 |
| `GET /api/v1/domains/https-forwarding?domain=` | HTTPS 轉址加購：價格、是否開啟、到期日，以及要顯示給使用者的完整條款（`consent`） |
| `POST /api/v1/domains/https-forwarding` `{"domain", "accept_charge": true}` | 已登入的擁有者或管理員開啟（以存檔卡片扣一年）；`{"enabled": false}` 停止續約 |

完整規格與所有欄位：https://nymwell.com/openapi.json

## 錯誤

錯誤以 JSON 回傳 `error` 代碼與對應的 HTTP 狀態，例如 `{"error": "quote_expired", "next": "Call get_quote again."}`。所有代碼見[狀態與錯誤碼](https://nymwell.com/zh-tw/docs/reference/)。