# Guide for AI agents

> The brief an AI coding agent follows to build a DNA Rest API integration: what to read, the rules that prevent costly mistakes, and how to test before going live.

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](https://www.domainnameapi.com/docs/).

## 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](https://www.domainnameapi.com/api-integration)) and let them decide before you write code.

Answer in the language the user writes in.

## Read only what you need

1. Fetch [`/llms.txt`](https://www.domainnameapi.com/docs/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](https://www.domainnameapi.com/docs/getting-started/), [Authentication](https://www.domainnameapi.com/docs/getting-started/authentication/), [Errors](https://www.domainnameapi.com/docs/getting-started/errors/) |
| Check availability and price | [Check availability](https://www.domainnameapi.com/docs/domains/availability/), [TLD catalogue](https://www.domainnameapi.com/docs/catalogue/) |
| Register a domain | [Register](https://www.domainnameapi.com/docs/domains/register/), [Contacts](https://www.domainnameapi.com/docs/contacts/) |
| Renew, transfer, restore | [Renew](https://www.domainnameapi.com/docs/domains/renew/), [Transfer](https://www.domainnameapi.com/docs/domains/transfer/), [Restore](https://www.domainnameapi.com/docs/domains/restore/) |
| Name servers, DNSSEC | [Name servers & DNSSEC](https://www.domainnameapi.com/docs/name-servers/) |
| DNS records | [DNS records](https://www.domainnameapi.com/docs/dns-records/) |
| SSL certificates | [SSL certificates](https://www.domainnameapi.com/docs/ssl/) — the order of calls matters |
| Hosting | [Hosting](https://www.domainnameapi.com/docs/hosting/) |
| One extension's rules | `/tlds/{name}.md`, for example [`.com.tr`](https://www.domainnameapi.com/docs/tlds/com.tr/) |
| Every error code | [Error codes](https://www.domainnameapi.com/docs/reference/errors/) |

3. If you can take a large file in one go, [`/llms-full.txt`](https://www.domainnameapi.com/docs/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.

## Rules that prevent costly mistakes

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](https://www.domainnameapi.com/docs/domains/info/)). Some error codes must never be retried at all — see [Never retry these five](https://www.domainnameapi.com/docs/reference/errors/).
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](https://www.domainnameapi.com/docs/getting-started/#before-you-write-any-code).

## 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 `.tr` are in the [`.tr` worked example](https://www.domainnameapi.com/docs/domains/#worked-example-tr-domains).
- 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

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

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.
