Quickstart
Quickstart
Section titled “Quickstart”To let an agent register a domain, create and fund an AiVikings.ai account, verify the account email, create an API token, check availability and price, then submit one approved registration request. After registration, read the domain back and set the full nameserver delegation or managed DNS only when the intended configuration is clear.
This guide uses the REST API. If your agent speaks MCP, you can instead connect it to the MCP server.
Create an account
Section titled “Create an account”Create an AiVikings.ai account to get an API token and connect your agent through MCP, REST, or the ChatGPT connector. This is an account dashboard step, not a documented public API endpoint.
For MCP, connect your client first and say: “Show me which AiVikings.ai account is connected.” The get_current_user tool is read-only and returns the authenticated account information.
Verify the account email
Section titled “Verify the account email”Complete the verification message sent to the account email address before asking an agent to make paid changes. Registrant verification can also be required after a domain registration, depending on the registry. Keep the account and registrant inboxes available to the people responsible for those approvals.
There is no documented REST endpoint in these docs for sending or completing account email verification. Do not try to construct one from an agent prompt. For MCP, ask: “Show my account details and tell me whether anything needs my attention.” Then finish any email task in the AiVikings.ai account flow.
Add account balance
Section titled “Add account balance”Add balance in your AiVikings.ai account before registering a domain. Registration is charged to the account that authorizes the request. The API does not provide a documented top-up endpoint, so add funds in the dashboard rather than creating an unsupported HTTP request.
Before a paid operation, use MCP to ask: “What is my prepaid balance in USD?” The read-only get_prepaid_balance tool accepts an optional currency and returns the balance for the requested wallet. Do not treat a balance check as an approval to spend it.
Create an API token
Section titled “Create an API token”Create an API token in your account, store it as an environment variable, and send it only in the bearer authorization header.
export AIVIKINGS_TOKEN="YOUR_API_TOKEN"The API token is a dashboard credential, not a REST resource documented here. Do not commit it, send it to a browser, or paste it into an MCP configuration. MCP clients complete OAuth instead, so the user authorizes the account in the browser and the client manages the resulting tokens.
Check availability
Section titled “Check availability”Send one or more names to POST /domains/check before registering. The request accepts up to 200 names and an optional currency. The response contains a domains array. Each item includes the requested domain, an availability result, and related domain facts. Availability can be uncertain, so continue only when the returned result is positive and your own policy approves the candidate.
curl --fail-with-body https://api.aivikings.ai/v1/domains/check \ -H "Authorization: Bearer $AIVIKINGS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"domains":["your-approved-domain.tld"],"currency":"USD"}'{ "domains": [ { "domain": "your-approved-domain.tld", "available": true, "long_domain": false } ]}Only continue when the returned item is available and your application has approved the name and price. For MCP, say: “Check whether your-approved-domain.tld is available in USD. Do not register it.” The read-only check_single_domain_availability tool accepts domain and an optional currency, then returns a one-item domains array with availability, pricing, premium status, and provider information.
Get a price quote
Section titled “Get a price quote”Use the public Pricing API to quote one exact domain. It does not require an account token and it does not reserve the name. A successful quote depends on the exact domain and current response, so do not manufacture a price from a catalog entry or an old result.
curl --include 'https://api.aivikings.ai/pricing/v1/quote?domain=your-approved-domain.tld'The live API can return this real unavailable result:
{ "error": "domain_unavailable", "message": "The domain is not available for registration."}If the domain is unavailable, stop and choose another candidate. For MCP, say: “Get the full USD price schedule for your-approved-domain.tld. Do not register it.” The get_domain_pricing tool accepts domain and optional currency; it returns registration, renewal, transfer, per-year registration prices, minimum and maximum registration years, and premium status.
Register the domain
Section titled “Register the domain”Submit the checked name to POST /domains only after you have approved the exact candidate, term, current price, premium decision, contact, and account balance. Registration is one domain per request. The request below uses the documented minimal fields and explicitly refuses premium registration.
curl --fail-with-body https://api.aivikings.ai/v1/domains \ -H "Authorization: Bearer $AIVIKINGS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"domain":"your-approved-domain.tld","period_years":1,"allow_premium":false}'{ "domain": "your-approved-domain.tld", "status": "...", "expiry": "...", "nameservers": ["..."], "period_years": 1}This shows the documented response fields, not fixed field values. Do not retry this paid request blindly after a timeout or connection failure. Read the domain state first, because the outcome may be unknown.
For MCP, say: “Register your-approved-domain.tld for one year only if it is available, the current USD price is approved, and it is not premium. Ask for confirmation before spending.” The register_domain tool requires domain and period_years. It also supports optional contact_handle, nameservers, currency, and allow_premium. It returns the created domain record, including status and expiry once provisioned.
Read the registration back
Section titled “Read the registration back”Use the single-domain status endpoint after a registration request or an uncertain network outcome. The REST path is GET /domains/{domain}. The documented status response includes domain, status, expiry, nameservers, and period_years.
curl --fail-with-body https://api.aivikings.ai/v1/domains/your-approved-domain.tld \ -H "Authorization: Bearer $AIVIKINGS_TOKEN"{ "domain": "your-approved-domain.tld", "status": "...", "expiry": "...", "nameservers": ["..."], "period_years": 1}For MCP, say: “Show the status, expiry, nameservers, and registrant verification state for your-approved-domain.tld.” The read-only get_domain_status tool returns those details, including registrant verification status and date.
Set DNS delegation
Section titled “Set DNS delegation”Choose one full nameserver set. Use ns1.aivikings-dns.com, ns2.aivikings-dns.com, ns3.aivikings-dns.com, and ns4.aivikings-dns.com when AiVikings.ai managed DNS should control the domain. Use custom nameservers only when another DNS provider will control the zone. Replacing nameservers changes the whole delegation, not one DNS record.
curl --fail-with-body --request PATCH https://api.aivikings.ai/v1/domains/your-approved-domain.tld \ -H "Authorization: Bearer $AIVIKINGS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"nameservers":["ns1.aivikings-dns.com","ns2.aivikings-dns.com","ns3.aivikings-dns.com","ns4.aivikings-dns.com"]}'Read the domain again with the preceding GET /domains/{domain} request and confirm that the returned nameservers array matches the full set you sent. For MCP, say: “Replace the nameservers for your-approved-domain.tld with the four AiVikings.ai standard nameservers, then show me the resulting nameserver set.” The update_nameservers tool requires domain and a full nameservers array and returns the updated nameserver set.
Read the REST operations reference before adding contacts, custom nameservers, premium purchases, renewals, or DNS changes. For managed DNS record operations, use the MCP tools reference, which lists the supported record inputs and returns.