Before you start
- A Galon account, a project and a key with
domain:lookup,domain:quoteandjob: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.
| 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.