# Galon Domains

> Check and quote domain names in USD with one API key; buy, renew and manage DNS from the console.

## Before you start

- A Galon account, a project and a key with `domain:lookup`, `domain:quote` and `job:read`.
- Buying a domain is done by a person in the console, on a **live** project, paid by card on a secure payment page; a domain is never paid from the prepaid balance. An API key cannot buy.

## Quickstart

Every example reads `GALON_API_BASE` (`https://api.galon.ai/v1`) and `GALON_API_KEY` from the environment and prints the HTTP status and the JSON body.

**1. Set your key.** Export the base URL and your key.

**curl**

```bash
export GALON_API_BASE="https://api.galon.ai/v1"
export GALON_API_KEY="gln_..."
```

**2. Check a name.** Lookups are asynchronous jobs: `202` with `job.id`.

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/jobs" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: quickstart-lookup-0001" \
  -H "Content-Type: application/json" \
  -d '{"type": "domain.lookup", "input": {"domain": "acme-quickstart.com"}}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/jobs",
    data=json.dumps({"type": "domain.lookup", "input": {"domain": "acme-quickstart.com"}}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Idempotency-Key": "quickstart-lookup-0001",
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/jobs`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-lookup-0001", "Content-Type": "application/json" },
  body: JSON.stringify({type: "domain.lookup", input: {domain: "acme-quickstart.com"}}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "check_domain", "arguments": {"idempotency_key": "quickstart-lookup-0001", "domain": "acme-quickstart.com"}}}' \
  -w '\n%{http_code}\n'
```

**3. Read the answer.** Repeat until the job is final: `result.available`, `result.sale_price` (`amount_minor`, `currency: USD`).

**curl**

```bash
curl -sS -X GET "$GALON_API_BASE/jobs/${GALON_JOB_ID}" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/jobs/" + os.environ["GALON_JOB_ID"],
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"]},
    method="GET",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/jobs/${process.env.GALON_JOB_ID}`, {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}` },
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_job", "arguments": {"id": "'"$GALON_JOB_ID"'"}}}' \
  -w '\n%{http_code}\n'
```

**4. Get a quote.** `operation`: `create` or `renew`; `period`: `1` (one year at a time). The final job carries `result.domain_quote` (`id`, price, `expires_at`).

**curl**

```bash
curl -sS -X POST "$GALON_API_BASE/jobs" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Idempotency-Key: quickstart-quote-0001" \
  -H "Content-Type: application/json" \
  -d '{"type": "domain.quote", "input": {"domain": "acme-quickstart.com", "operation": "create", "period": 1}}' \
  -w '\n%{http_code}\n'
```

**Python 3 (standard library)**

```python
import json, os, urllib.error, urllib.request

req = urllib.request.Request(
    os.environ["GALON_API_BASE"] + "/jobs",
    data=json.dumps({"type": "domain.quote", "input": {"domain": "acme-quickstart.com", "operation": "create", "period": 1}}).encode(),
    headers={"Authorization": "Bearer " + os.environ["GALON_API_KEY"],
             "Idempotency-Key": "quickstart-quote-0001",
             "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(req) as res:
        print(res.status, json.load(res))
except urllib.error.HTTPError as err:  # the error body carries detail.code and detail.next_action
    print(err.code, json.load(err))
```

**Node.js 18+ (fetch)**

```js
const res = await fetch(`${process.env.GALON_API_BASE}/jobs`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GALON_API_KEY}`, "Idempotency-Key": "quickstart-quote-0001", "Content-Type": "application/json" },
  body: JSON.stringify({type: "domain.quote", input: {domain: "acme-quickstart.com", operation: "create", period: 1}}),
});
console.log(res.status, JSON.stringify(await res.json()));
```

**MCP (JSON-RPC over HTTP)**

```bash
curl -sS -X POST "$GALON_API_BASE/mcp" \
  -H "Authorization: Bearer $GALON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "quote_domain", "arguments": {"idempotency_key": "quickstart-quote-0001", "domain": "acme-quickstart.com", "operation": "create", "period": 1}}}' \
  -w '\n%{http_code}\n'
```

## Concepts

**Prices before any charge.** Every price is quoted in USD before any charge. A quote expires (`expires_at`); a purchase or a paid change uses a valid quote.

**Sealed approvals.** A paid change sent with `POST /v1/domain-actions` is sealed for 30 minutes to its exact operation and quote; an authorisation (EPP) code is write-only: never returned, never logged.

**Portfolio.** `GET /v1/domain-portfolio`, `/v1/domain-orders` and `/v1/domain-notices` list your domains, orders and expiry notices.

**DNS.** Records of a domain bought at Galon are changed with a `domain.dns.apply` action (`add`, `remove` or `replace`, up to 100 records).

## API reference

Derived from the OpenAPI 3.1 contract at each request: every operation of Galon Domains you can reach today, with its full page (parameters, bodies, responses, examples). Base URL: the public API endpoint, `$GALON_API_BASE`.

| Method | Path | Summary |
|---|---|---|
| GET | [`/v1/projects/{project_id}/domains`](/cloud/docs/api/projects-project_id-domains) | List the domain portfolio from the console |
| GET | [`/v1/projects/{project_id}/domain-quotes/{quote_id}`](/cloud/docs/api/projects-project_id-domain-quotes-quote_id) | Re-read a domain quote from the console |
| GET | [`/v1/projects/{project_id}/domain-orders`](/cloud/docs/api/projects-project_id-domain-orders) | List domain orders from the console |
| GET | [`/v1/projects/{project_id}/domain-notices`](/cloud/docs/api/projects-project_id-domain-notices) | List expiry notices from the console |
| POST | [`/v1/projects/{project_id}/domain-notices/{notice_id}`](/cloud/docs/api/projects-project_id-domain-notices-notice_id) | Mark an expiry notice |
| POST | [`/v1/projects/{project_id}/domain-orders/{order_id}/refund-requests`](/cloud/docs/api/projects-project_id-domain-orders-order_id-refund-requests) | Request a refund review |
| POST | [`/v1/projects/{project_id}/domains/lookup`](/cloud/docs/api/projects-project_id-domains-lookup) | Check a domain from the console |
| POST | [`/v1/projects/{project_id}/domains/query`](/cloud/docs/api/projects-project_id-domains-query) | Request a quote, the status or the DNS from the console |
| POST | [`/v1/projects/{project_id}/domains/actions`](/cloud/docs/api/projects-project_id-domains-actions) | Confirm an exact domain action from the console |
| GET | [`/v1/domain-portfolio`](/cloud/docs/api/domain-portfolio) | List the portfolio of the key's project |
| GET | [`/v1/domain-quotes/{quote_id}`](/cloud/docs/api/domain-quotes-quote_id) | Re-read a quote of the key's project |
| GET | [`/v1/domain-orders`](/cloud/docs/api/domain-orders) | List orders of the key's project |
| POST | [`/v1/projects/{project_id}/domain-transfers/check`](/cloud/docs/api/projects-project_id-domain-transfers-check) | Check eligibility for an inbound transfer |
| GET | [`/v1/projects/{project_id}/domain-transfers`](/cloud/docs/api/projects-project_id-domain-transfers) | Track inbound transfers |
| POST | [`/v1/projects/{project_id}/domain-transfers`](/cloud/docs/api/projects-project_id-domain-transfers) | Request an inbound transfer |
| GET | [`/v1/projects/{project_id}/domains/{domain}/email-verification`](/cloud/docs/api/projects-project_id-domains-domain-email-verification) | Get the holder's email verification |
| POST | [`/v1/projects/{project_id}/domains/{domain}/transfer-out`](/cloud/docs/api/projects-project_id-domains-domain-transfer-out) | Prepare an outbound transfer |
| GET | [`/v1/projects/{project_id}/domains/{domain}/renewal`](/cloud/docs/api/projects-project_id-domains-domain-renewal) | Get a domain's renewal |
| PUT | [`/v1/projects/{project_id}/domains/{domain}/auto-renew`](/cloud/docs/api/projects-project_id-domains-domain-auto-renew) | Turn automatic renewal on or off |
| POST | [`/v1/projects/{project_id}/domains/{domain}/renewals`](/cloud/docs/api/projects-project_id-domains-domain-renewals) | Renew now |
| GET | [`/v1/projects/{project_id}/dns/zones`](/cloud/docs/api/projects-project_id-dns-zones) | List DNS zones hosted by Galon |
| POST | [`/v1/projects/{project_id}/dns/zones`](/cloud/docs/api/projects-project_id-dns-zones) | Create a DNS zone for a domain bought elsewhere |
| DELETE | [`/v1/projects/{project_id}/dns/zones/{domain}`](/cloud/docs/api/projects-project_id-dns-zones-domain) | Delete a DNS zone |

## Errors

Every error is JSON: `{"detail": {"code", "message", "next_action"}}`. `next_action.code` is stable, `next_action.hint` says what to do next, and `console_url` is added when a person must act. The codes below are those this service returns.

| Status | Code | When | next_action |
|---|---|---|---|
| 401 | `api_key_missing` | No `Authorization: Bearer` header. | `use_valid_api_key` |
| 403 | `scope_missing` | The key lacks the scope of this job type. | `add_missing_scope` |
| 400 | `idempotency_key_invalid` | Missing key, or not 8 to 200 characters. | `fix_request` |
| 409 | `idempotency_conflict` | Same key, different request. | `resolve_conflict` |
| 422 | `job_invalid` | The job `input` does not match its type. | `fix_request` |
| 403 | `approval_required` | `domain.purchase` sent with an API key: buying is done in the console. | `request_human_approval` |
| 422 | `domain_action_invalid` | A malformed action, an expired quote, or a type not allowed here. | `fix_request` |
| 404 | `domain_quote_not_found` | No quote with this id for this key. | `check_resource_id` |
| 404 | `domain_not_found` | This domain is not in the project. | `check_resource_id` |
| 409 | `domain_unavailable` | The name is already held. | `resolve_conflict` |
| 503 | `domain_vault_unavailable` | Temporary: retry with the same Idempotency-Key. | `retry_later` |

| next_action | What to do |
|---|---|
| `use_valid_api_key` | Send a valid Galon API key as 'Authorization: Bearer <key>'. If the key was revoked or has expired, create a new one in the console and retry with it. |
| `add_missing_scope` | This key does not have the scope this call needs. Create a key with that scope in the console, then retry the same call with the new key. |
| `fix_request` | The request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged. |
| `resolve_conflict` | The request conflicts with the resource state or with an earlier request under the same Idempotency-Key. Read the resource first; for a new intent, use a new Idempotency-Key. |
| `request_human_approval` | This action needs a person's approval. With an app connected by OAuth, ask for it with the MCP tool request_approval (POST /v1/approvals), give the person the console_url it returns, then wait. |
| `check_resource_id` | Nothing with this id is visible to this key. List the resources to get a valid id, and check that the key belongs to the right project and environment (test or live). |
| `retry_later` | Temporary error on Galon's side. Retry with exponential backoff and the same Idempotency-Key; if it lasts, contact support with the X-Request-Id header. |

## Limits, free tier and pricing

Read from the platform code each time this page is served.

| Limit | Value |
|---|---|
| DNS zones hosted by Galon per project | **50** |
| Lock after a purchase or a transfer (transfer out) | **60 days** |

Prices are quoted per name and operation, in US dollars, before any charge. The free plan includes no domain registration.

## FAQ

**Can my agent buy a domain?**

No API key can buy. A person buys in the console; an app connected with OAuth can ask a person for approval.

**Is there a free domain?**

No. The free plan includes no domain registration.

**How is the price set?**

Each quote gives the exact price in USD, valid until its `expires_at`.

**How is a domain paid?**

By card, on a secure payment page in the console; never from the prepaid balance. If the registration fails, the card is refunded automatically.

**How is a domain renewed?**

Renewal is manual, on request: **Renew now** on the domain page, paid by card, one year at a time.

**Can I transfer a domain to Galon?**

Not online yet. You can transfer a domain out: ask for its authorisation code.

## More

- [Authentication](/cloud/docs/platform/authentication)
- [Projects: live and test](/cloud/docs/platform/environments)
- [Prepaid balance](/cloud/docs/platform/balance)
- [Quotas and rate limits](/cloud/docs/platform/quotas)
- [Terms of Service](/legal/terms-of-service)
- [Acceptable Use Policy](/legal/acceptable-use-policy)
- [Privacy Policy](/legal/privacy-policy)
- [Refunds and prepaid balance](/legal/prepaid-balance-and-refund-policy)
- [Legal Notice](/legal/legal-notice)
- [All legal documents](/legal)
