Skip to content

Guide for AI agents

This page is written for an AI agent that a reseller has asked to build or change an integration with the DNA Rest API. People can read it too: it is the brief their agent follows. The reseller usually starts it by pasting one line from the home page.

Use what is already in the conversation and in the project before asking anything:

  • What is being built. A domain search box, registration in a storefront, renewals, transfers, DNS management, SSL or hosting sales, a sync of expiry dates, a billing-system module.
  • Where it runs. Read the codebase first: the language, the HTTP client already in use, where configuration and secrets live, and whether there is an existing integration to extend rather than replace.

Ask the user only for what you cannot find. If they run WHMCS, WiseCP, HostBill, Blesta, ClientExec or FOSSBilling, tell them a free ready-made module may already do the job (API integration) and let them decide before you write code.

Answer in the language the user writes in.

  1. Fetch /llms.txt. It states the facts every integration needs (base URL, headers, errors, rate limits, test environment) and lists every page with one line each.
  2. Fetch the Markdown of the pages your task touches — every page is at its own address plus .md:
Task Read
Any task Introduction, Authentication, Errors
Check availability and price Check availability, TLD catalogue
Register a domain Register, Contacts
Renew, transfer, restore Renew, Transfer, Restore
Name servers, DNSSEC Name servers & DNSSEC
DNS records DNS records
SSL certificates SSL certificates — the order of calls matters
Hosting Hosting
One extension’s rules /tlds/{name}.md, for example .com.tr
Every error code Error codes
  1. If you can take a large file in one go, /llms-full.txt is the whole guide, about 300 KB.

Do not guess an endpoint, a field name or an error code: if it is not in these pages, it does not exist.

  1. Keep the key out of the code and out of the chat. Every request needs the X-API-KEY and __reseller headers. Read both from the project’s configuration or secret store. Never hard-code them, never put them in browser or mobile code, and never ask the user to paste the key into the conversation — tell them where to put it.
  2. Build against the test environment. Make the base URL configuration, start with https://ote.domainresellerapi.com and the user’s test API key, and switch to https://api.domainresellerapi.com only when the user decides to go live. Each key works only at its own address.
  3. Paid calls cost real money in production. Registering, renewing, transferring, restoring and buying SSL or hosting debit the reseller’s balance. Do not run code that makes a paid call against production without the user’s explicit approval for that run.
  4. Never retry a paid call blindly. After a timeout or a network error, read the current state first (for a domain, its details). Some error codes must never be retried at all — see Never retry these five.
  5. Branch on error.code, not on the HTTP status. Show message to people, log details.
  6. Read the rules, do not hard-code them. Periods, prices, transfer rules and extra registry fields come from the TLD catalogue (GET /api/v1/products/tlds); cache it.
  7. Expect asynchronous outcomes. Transfers, SSL validation, hosting and some registrations finish later; each section says what to poll.
  8. Stay inside the rate limits. 5 requests per second per key, 2 per second for search; on HTTP 429 wait for Retry-After.
  9. Log what support needs. Send a unique X-Correlation-ID per request and log it, plus the transaction ID of every paid operation.

Before writing code, go through the four decisions in Before you write any code.

  • Run the integration against the test environment with the test key the user put in configuration. Registry operations there are simulated and the balance is not charged.
  • Cover each outcome your code branches on — success, a taken name, a validation error, a pending result — not just the happy path. Test values for .tr are in the .tr worked example.
  • DNS record endpoints do not work in the test environment (HTTP 500). Say so, and leave that part for a supervised production test.

Tell the user, briefly:

  • what you built and which endpoints it calls;
  • what you ran against the test environment and what came back;
  • what is untested and why;
  • what they must do to go live: the live API key, the base URL switch, and anything paid that should be watched on the first run.

If the user wants their domains, DNS or certificates handled now — not an integration in their code — use the dna command line tool and MCP server instead: fetch https://www.domainnameapi.com/cli/get-started.md and follow it.