Galon Cloud
Galon Cloud

Galon Domains

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

Markdown · API reference · OpenAPI

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

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

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)

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)

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)

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

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)

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)

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)

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

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)

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)

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)

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.

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

StatusCodeWhennext_action
401api_key_missingNo Authorization: Bearer header.use_valid_api_key
403scope_missingThe key lacks the scope of this job type.add_missing_scope
400idempotency_key_invalidMissing key, or not 8 to 200 characters.fix_request
409idempotency_conflictSame key, different request.resolve_conflict
422job_invalidThe job input does not match its type.fix_request
403approval_requireddomain.purchase sent with an API key: buying is done in the console.request_human_approval
422domain_action_invalidA malformed action, an expired quote, or a type not allowed here.fix_request
404domain_quote_not_foundNo quote with this id for this key.check_resource_id
404domain_not_foundThis domain is not in the project.check_resource_id
409domain_unavailableThe name is already held.resolve_conflict
503domain_vault_unavailableTemporary: retry with the same Idempotency-Key.retry_later
next_actionWhat to do
use_valid_api_keySend 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_scopeThis 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_requestThe request is invalid. Fix it as 'message' and 'field' say, using the OpenAPI contract, then send it again. Do not retry it unchanged.
resolve_conflictThe 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_approvalThis 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_idNothing 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_laterTemporary 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.

LimitValue
DNS zones hosted by Galon per project50
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