canonical: https://jentic.com/apis/azure.com/topleveldomains-api-client

# Microsoft Azure TopLevelDomains API Client

Jentic publishes the only available OpenAPI specification for TopLevelDomains API Client, keeping it validated and agent-ready. The TopLevelDomains API Client is part of the Azure App Service Domain Registration provider and exposes a read-only catalog of top-level domains (such as .com, .net, .org) that Azure customers can register through Microsoft.DomainRegistration. Agents can list every supported TLD, fetch detail for a specific TLD by name, and retrieve the legal agreements a buyer must accept before purchasing a domain in that TLD. Authentication uses Azure Active Directory OAuth 2.0 against the Azure Resource Manager endpoint at management.azure.com.

## For AI agents

Lists Azure-supported top-level domains and retrieves the legal agreements required to register a domain under each TLD via Azure Resource Manager.

## Scope

Does not register, renew, or transfer domains, and does not manage DNS records - use the App Service Domains and Azure DNS APIs for those operations; this client only lists TLDs and their registration agreements.

## Capabilities

- List every top-level domain that Azure App Service Domains supports for registration in a given subscription
- Fetch metadata for a specific top-level domain by name (e.g., com, net, org) before initiating a domain purchase
- Retrieve the registration agreements (privacy, transfer-lock, ICANN consent) a buyer must accept for a chosen TLD
- Filter agreements by includePrivacy and forTransfer flags to surface the exact terms presented at checkout
- Discover which TLDs are available under a subscription before calling the App Service Domains purchase endpoint

## Use cases

### TLD discovery before domain purchase

Before issuing a domain purchase request through Azure App Service Domains, an automation needs to confirm that the TLD the user typed is supported. Calling the topLevelDomains list endpoint returns the full catalog of registerable TLDs for the subscription so the workflow can validate input, surface a dropdown, and avoid a downstream 400 from the purchase API. The endpoint is read-only and idempotent, so it is safe to call on every checkout render.

Example prompt: List every top-level domain available under subscription 11111111-1111-1111-1111-111111111111 and return only those whose privacy flag is true.

### Surfacing registration agreements at checkout

ICANN and Azure App Service require the buyer to accept TLD-specific legal agreements (privacy, registrant transfer, registrar terms) before a domain purchase succeeds. The listAgreements endpoint returns the exact agreement text, link, and identifier for the chosen TLD so a checkout flow can render the consent screen and capture acceptance. Agreement content varies per TLD, so this must be fetched at the moment of purchase rather than cached statically.

Example prompt: Call listAgreements for the com TLD with includePrivacy=true and forTransfer=false, then return the agreement keys and content URLs for display to the buyer.

### TLD metadata lookup

Some catalog and admin tools need to resolve a single TLD by name (for example, to display its display name, privacy support, or registration constraints) without fetching the entire catalog. The get-by-name endpoint returns the topLevelDomain resource for one TLD and is the cheapest call when the TLD is already known. It is commonly used to drive conditional UI such as showing or hiding a privacy checkbox.

Example prompt: Get the topLevelDomain resource named net under the current subscription and return whether privacy registration is supported.

### Agent-driven domain purchase pipeline

An AI agent registering a domain on behalf of a user needs to chain three Azure calls: list TLDs to validate input, fetch agreements for the selected TLD, and pass accepted agreement keys to the App Service Domains purchase endpoint. Through Jentic the agent searches once for an Azure domain registration operation, loads the input schema for each step, and executes them with a scoped Azure AD token from the vault, with no Azure SDK install or token refresh code in the agent.

Example prompt: Search Jentic for 'list Azure top level domains', execute the operation with subscriptionId=SUB123, then for the user-selected TLD call listAgreements with includePrivacy=true and return the agreement keys to the orchestrator.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.DomainRegistration/topLevelDomains | List all top-level domains supported for registration |
| GET | /subscriptions/{subscriptionId}/providers/Microsoft.DomainRegistration/topLevelDomains/{name} | Get a single top-level domain by name |
| POST | /subscriptions/{subscriptionId}/providers/Microsoft.DomainRegistration/topLevelDomains/{name}/listAgreements | List legal agreements that must be accepted for a TLD |

## Key resources

- **TopLevelDomains** — Read-only list and get operations for the catalog of TLDs Azure App Service supports for registration
- **Agreements** — Per-TLD legal and privacy agreements that must be accepted before a domain purchase request succeeds

## Why Jentic

- **Setup:** Wiring TopLevelDomains API Client by hand means setting up Azure AD OAuth 2.0 against management.azure.com, pinning the 2018-02-01 api-version, and handling ARM nextLink pagination and 429 back-off yourself just to read the registerable TLD catalogue. Through Jentic you install once, import TopLevelDomains API Client from the API Directory, store the Azure AD OAuth token once, and your agent calls it.
- **Permission scoping:** The subscription id and TLD name are URL path parameters (/subscriptions/{subscriptionId}/providers/Microsoft.DomainRegistration/topLevelDomains/{name}), and every operation here is read-only listing, get-by-name, and listing agreements. You choose the operations it may call, so you can limit the agent to those catalogue reads for one subscription and nothing else.
- **Credential handling:** Your Azure AD OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Azure supported top level domains' or 'get the registration agreements for a TLD', and Jentic returns the matching Microsoft.DomainRegistration operation with its input schema so the agent passes the subscription and TLD without reading the ARM reference.

## Related APIs

- **TrafficManagerManagementClient** — Routes traffic for the domains you register via the TopLevelDomains API
- **DnsManagementClient** — Hosts DNS zones for domains registered through Azure App Service Domains
- **Domains API Client** — Purchases and manages registered Azure App Service domains

## FAQ

### Why is there no official OpenAPI spec for TopLevelDomains API Client?

Microsoft Azure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call TopLevelDomains API Client via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer .

### What authentication does the TopLevelDomains API Client use?

The API uses Azure Active Directory OAuth 2.0 with the user_impersonation scope against https://login.microsoftonline.com/common/oauth2/authorize. Through Jentic, the Azure AD client secret stays encrypted in the vault and the agent receives a scoped bearer token at execution time, so the raw secret never enters agent context.

### Can I list every supported TLD in one call with the TopLevelDomains API Client?

Yes. A GET on /subscriptions/{subscriptionId}/providers/Microsoft.DomainRegistration/topLevelDomains returns all TLDs registerable through Azure App Service Domains under that subscription. Results are paginated via nextLink when the catalog grows beyond a single page.

### What are the rate limits for the TopLevelDomains API Client?

Calls go through Azure Resource Manager and are subject to the standard ARM throttling envelope (roughly 12,000 reads per hour per subscription per region). The exact limit is not declared in the spec; check the Retry-After header on a 429 response and back off accordingly.

### How do I retrieve the legal agreements for a TLD through Jentic?

Run pip install jentic, then call client.search('list Azure top level domain agreements'), client.load on the returned operation id (POST /subscriptions/{subscriptionId}/.../topLevelDomains/{name}/listAgreements), and client.execute with name='com', includePrivacy=true, forTransfer=false. Jentic returns the agreement keys you pass to the purchase endpoint.

### Is the TopLevelDomains API Client free to call?

The metadata endpoints (list TLDs, get TLD, list agreements) are free management-plane calls. Cost only applies when you proceed to the App Service Domains purchase endpoint and complete a domain registration, which is billed at the per-TLD registration price.

### Can I limit what my agent is allowed to do with the Microsoft Azure TopLevelDomains API Client?

Yes. Because Jentic One is self-hosted, you decide which of this API's operations the agent may call, and every operation here is read-only: listing top-level domains, getting a single TLD by name, and listing the registration agreements for a TLD. You can restrict the agent to only those catalogue reads for one subscription, since the subscription id and TLD name are URL path parameters you control. Your own rules govern which operations and credentials the agent may use, so it can browse the TLD catalogue without any ability to register, transfer, or manage domains.