← Cloudflare Registrar / registrar

Registrar API

Pomocí Cloudflare Registrar API můžete vyhledávat doménová jména, zjišťovat dostupnost a cenu v reálném čase a programově registrovat podporované domény.

Tento návod popisuje beta postup pomocí Cloudflare API a curl. Tytéž koncové body najdete v oficiální referenci Cloudflare API a ve výchozím nastavení i přes Cloudflare MCP, takže je lze bez dalších úprav použít ve skriptech, backendových službách, CI pipeline i nástrojích řízených agenty.

Než začnete

Než odešlete první požadavek API, ujistěte se, že máte:

ID účtu Cloudflare.
Token API s oprávněním k zápisu pro Registrar. Vytvořte jej na https://dash.cloudflare.com/<ACCOUNT_ID>/api-tokens.
Fakturační profil s platnou výchozí platební metodou. Fakturaci spravujte na https://dash.cloudflare.com/<ACCOUNT_ID>/billing/payment-info.
Výchozí kontakt na držitele domény nastavený u účtu a odsouhlasení smlouvy Domain Registration Agreement na stránce registrací: https://dash.cloudflare.com/<ACCOUNT_ID>/domains/registrations.

Nápovědu k souvisejícímu nastavení najdete zde:

Najděte své ID účtu
Vytvořte token API
Volání API
[Dokumentace API Registrar] (/api/resources/registrar)

Nastavení ověřování

Požadavky Cloudflare API používají ověřování pomocí bearer tokenu.

V terminálu si definujte proměnné prostředí pro ID účtu a API token:

export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"

Všechny požadavky v tomto průvodci používají základní URL adresu API Cloudflare v4:

https://api.cloudflare.com/client/v4/

Beta postup

Postup v beta verzi má tři základní kroky:

Vyhledejte vhodné názvy domén.
Zkontrolujte dostupnost a cenu požadované domény v reálném čase.
Zaregistrujte doménu.

Vyhledávání je vhodné pro průzkum možností, ale není autoritativním zdrojem dat. Vždy zavolejte Check endpoint bezprostředně před registrací, čímž snížíte pravděpodobnost chyby během registrace.

Příklady promptů pro agenty

Pokud používáte Cloudflare MCP nebo jiný workflow řízený agentem, prompt může být tak jednoduchý jako:

Search for domains for a coffee shop based in Evergreen, Colorado.
Find 5 available .com or .dev domains for an AI expense tracker.
Check whether example.com is available and show me the current price.
Check these domains and tell me which ones are registrable right now: example.com, example.dev, example.cafe
Register example.com on my Cloudflare account.

1. Vyhledejte domény

Pomocí endpointu Search vygenerujete návrhy doménových jmen na základě klíčového slova, fráze nebo části doménového jména.

Výsledky vyhledávání:

Jsou rychlé a určené pro průzkum.
Vycházejí z dat v mezipaměti.
Uvádějte pouze přípony podporované beta verzí API.

curl --request GET \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/domain-search?q=acme%20corp&limit=3" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Příklad odpovědi:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "acmecorp.com",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "8.57",
          "renewal_cost": "8.57"
        }
      },
      {
        "name": "acmecorp.dev",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "10.11",
          "renewal_cost": "10.11"
        }
      },
      {
        "name": "acmecorp.app",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "11.00",
          "renewal_cost": "11.00"
        }
      }
    ]
  }
}

2. Zkontrolujte dostupnost a ceny v reálném čase

Pomocí endpointu Check zjistíte, zda je doména aktuálně dostupná k registraci, a získáte její aktuální cenu.

Zkontrolujte výsledky:

Dotazuje se přímo do registru.
Odráží aktuální stav registru.
Mělo by se použít bezprostředně před voláním registračního endpointu.
Odpovědi mohou obsahovat reason pole, pokud registrable je false.

Tento endpoint přijímá až 20 domén na jeden požadavek.

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/domain-check" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "domains": ["acmecorp.dev"]
  }'

Příklad odpovědi:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "acmecorp.dev",
        "registrable": true,
        "tier": "standard",
        "pricing": {
          "currency": "USD",
          "registration_cost": "10.11",
          "renewal_cost": "10.11"
        }
      }
    ]
  }
}

Pokud doménu nelze zaregistrovat přes API, odpověď obsahuje důvod. Například:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domains": [
      {
        "name": "mybrand.uk",
        "registrable": false,
        "reason": "extension_not_supported_via_api"
      }
    ]
  }
}

Běžné reason hodnoty zahrnují:

domain_unavailable
extension_not_supported_via_api
extension_not_supported
extension_disallows_registration

3. Zaregistrujte doménu

Pomocí endpointu Registration spustíte proces registrace domény.

Důležité:

Úspěšné registrace se účtují na výchozí platební profil.
Jakmile je registrace úspěšně dokončena, peníze za ni nelze vrátit.
Před voláním tohoto koncového bodu si vždy ověřte název domény a cenu.

Nejjednodušší požadavek vyžaduje pouze domain_name:

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "domain_name": "acmecorp.dev"
  }'

Účet musí mít nastavený výchozí kontakt registranta. Pokud nový kontakt nepošlete přímo v požadavku, API automaticky použije výchozí kontakt. Pokud chcete doménu zaregistrovat s jiným kontaktem, můžete jej uvést v požadavku.

Aktuální výchozí chování:

auto_renew má výchozí hodnotu false.
privacy_mode má výchozí hodnotu redaction, pokud to TLD podporuje, jinak off.
Platba se automaticky strhne z výchozí platební metody účtu.

Chcete-li pro jednu registraci přepsat výchozí kontakt registranta, uveďte ho přímo v požadavku:

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "domain_name": "acmecorp.dev",
    "contacts": {
      "registrant": {
        "email": "[email protected]",
        "phone": "+1.5555555555",
        "postal_info": {
          "name": "Ada Lovelace",
          "organization": "Example Inc",
          "address": {
            "street": "123 Main St",
            "city": "Austin",
            "state": "TX",
            "postal_code": "78701",
            "country_code": "US"
          }
        }
      }
    }
  }'

Příklad úspěšné odpovědi:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "state": "succeeded",
    "completed": true,
    "created_at": "2025-10-27T10:00:00Z",
    "updated_at": "2025-10-27T10:00:03Z",
    "context": {
      "registration": {
        "domain_name": "acmecorp.dev",
        "status": "active",
        "created_at": "2025-10-27T10:00:00Z",
        "expires_at": "2026-10-27T10:00:00Z",
        "auto_renew": false,
        "privacy_mode": "redaction",
        "locked": true
      }
    },
    "links": {
      "self": "/accounts/abc/registrar/registrations/acmecorp.dev/registration-status",
      "resource": "/accounts/abc/registrar/registrations/acmecorp.dev"
    }
  }
}

Zpracování odpovědí na registraci

Registrační endpoint ve výchozím nastavení čeká na odpověď až 10 sekund.

Můžete obdržet buď:

201 Created pokud se registrace dokončila v rámci čekací lhůty.
202 Accepted pokud registrace stále probíhá.

Chcete-li vynutit okamžité asynchronní chování, odešlete Prefer: respond-async.

Příklad asynchronního požadavku:

curl --request POST \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Prefer: respond-async" \
  --data '{
    "domain_name": "acmecorp.dev"
  }'

Příklad 202 Accepted odpověď:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "state": "in_progress",
    "completed": false,
    "created_at": "2025-10-27T10:00:00Z",
    "updated_at": "2025-10-27T10:00:10Z",
    "links": {
      "self": "/accounts/abc/registrar/registrations/acmecorp.dev/registration-status",
      "resource": "/accounts/abc/registrar/registrations/acmecorp.dev"
    }
  }
}

Kontrola stavu registrace

Pokud registrace stále probíhá, dotazujte se opakovaně na endpoint stavu, dokud workflow nedosáhne koncového stavu.

curl --request GET \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations/acmecorp.dev/registration-status" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Příklad odpovědi:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "state": "succeeded",
    "completed": true,
    "created_at": "2025-10-27T10:00:00Z",
    "updated_at": "2025-10-27T10:00:03Z",
    "context": {
      "registration": {
        "domain_name": "acmecorp.dev",
        "status": "active",
        "created_at": "2025-10-27T10:00:00Z",
        "expires_at": "2026-10-27T10:00:00Z",
        "auto_renew": false,
        "privacy_mode": "redaction",
        "locked": true
      }
    },
    "links": {
      "self": "/accounts/abc/registrar/registrations/acmecorp.dev/registration-status",
      "resource": "/accounts/abc/registrar/registrations/acmecorp.dev"
    }
  }
}

Mezi možné stavy postupu patří:

in_progress
succeeded
failed
action_required
blocked

Pokud workflow vrátí action_required, zastavte dotazování a zobrazte uživateli požadovanou akci.

Pokud workflow vrátí failed, zkontrolovat error.code a error.message před opakováním.

Získání registračního prostředku

Jakmile je registrace dokončena, načtěte prostředek registrace přímo:

curl --request GET \
  --url "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/registrar/registrations/acmecorp.dev" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Příklad odpovědi:

{
  "success": true,
  "errors": [],
  "messages": [],
  "result": {
    "domain_name": "acmecorp.dev",
    "status": "active",
    "created_at": "2025-10-27T10:00:00Z",
    "expires_at": "2026-10-27T10:00:00Z",
    "auto_renew": false,
    "privacy_mode": "redaction",
    "locked": true
  }
}

Omezení bety

Toto je první beta verze Registrar API.

Mezi aktuální omezení patří:

Prostřednictvím beta verze API je dostupná pouze část podporovaných přípon Cloudflare Registrar.
Výsledky vyhledávání jsou omezeny pouze na přípony podporované API.
Některé přípony podporované v dashboardu ještě nejsou k dispozici pro programovou registraci.
Pokud je to podporováno, premiové domény budou před registrací vyžadovat výslovné potvrzení poplatku.
Obnovení nelze prostřednictvím API zatím provádět.
Převody zatím nejsou přes API dostupné.
Aktualizace kontaktů zatím nejsou v API k dispozici.

Pokud zkontrolujete doménu, kterou Cloudflare podporuje v dashboardu, ale ještě ne v API, odpověď Check vrátí extension_not_supported_via_api.

Tyto základní funkce nástroje Registrar budou do API doplněny v budoucích verzích.

Až seznam podporovaných přípon domén vznikne, doplňte sem na něj odkaz.

Další kroky

Zkontrolujte Konvence ověřování a požadavků Cloudflare API.

Pokud vyvíjíte s beta verzí Registrar API, zejména pro automatizaci, agenty nebo multi-tenant platformní workflow, rádi uslyšíme vaši zpětnou vazbu.