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.
Start with the user’s brief
Section titled “Start with the user’s brief”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.
Read only what you need
Section titled “Read only what you need”- 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. - 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 |
- If you can take a large file in one go,
/llms-full.txtis 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.
Rules that prevent costly mistakes
Section titled “Rules that prevent costly mistakes”- Keep the key out of the code and out of the chat. Every request needs the
X-API-KEYand__resellerheaders. 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. - Build against the test environment. Make the base URL configuration, start with
https://ote.domainresellerapi.comand the user’s test API key, and switch tohttps://api.domainresellerapi.comonly when the user decides to go live. Each key works only at its own address. - 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.
- 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.
- Branch on
error.code, not on the HTTP status. Showmessageto people, logdetails. - 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. - Expect asynchronous outcomes. Transfers, SSL validation, hosting and some registrations finish later; each section says what to poll.
- Stay inside the rate limits. 5 requests per second per key, 2 per second for search; on HTTP 429 wait for
Retry-After. - Log what support needs. Send a unique
X-Correlation-IDper 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.
Test before you hand it over
Section titled “Test before you hand it over”- 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
.trare in the.trworked example. - DNS record endpoints do not work in the test environment (HTTP 500). Say so, and leave that part for a supervised production test.
Report back
Section titled “Report back”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.
The user wants it done, not coded
Section titled “The user wants it done, not coded”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.