REST API
Base URL
Section titled “Base URL”https://api.aivikings.ai/v1
Use this API when your agent or application needs plain HTTPS access to AiVikings.ai domain operations. Authenticate every account request with a bearer token, check availability and price before registration, and use the operations reference for each endpoint contract.
The REST API is for applications that want deterministic request and response handling instead of an MCP client. It supports availability checks, registration, holdings, status, renewals, nameserver replacement, and an A-record convenience route. Your application owns customer identity, spending approval, durable operation records, and recovery after an uncertain paid request.
Pass your API token in the Authorization header: Authorization: Bearer YOUR_KEY.
Store the token in protected runtime configuration and send it from your server or worker. Do not expose it in client-side JavaScript, commit it to source control, or put it into an MCP configuration. Every protected request should carry the same header shape:
-H "Authorization: Bearer $AIVIKINGS_TOKEN"The token identifies the customer account for the request. Before a paid operation, confirm that your workflow has selected the correct account, contact, currency, and spending authority.
Core endpoints
Section titled “Core endpoints”POST /domains/check- check availabilityPOST /domains- register a domainGET /domains/{domain}- get current domain statusGET /domains- list your domainsPOST /domains/{domain}/renew- renewPATCH /domains/{domain}- replace nameserversGET /health- service health and current environment
Example request
Section titled “Example request”This complete availability request checks one name in USD. POST /domains/check accepts up to 200 names in its domains array and an optional currency.
curl --fail-with-body https://api.aivikings.ai/v1/domains/check \ -H "Authorization: Bearer $AIVIKINGS_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"domains":["my-agent-7f3.icu"],"currency":"USD"}'Example response
Section titled “Example response”{ "domains": [ { "domain": "my-agent-7f3.icu", "available": true, "long_domain": true } ]}The response is an object with a domains array. Each requested domain has its own availability result and may contain additional pricing or registration metadata.
Treat the response as the current fact for that request, not a reservation. A positive availability result can change before registration. A missing price or uncertain result is an unknown condition, not permission to use a fallback price or proceed with a purchase.
Registration flow
Section titled “Registration flow”After an approved availability and price check, register exactly one domain with POST /domains. The documented request requires domain and period_years; optional fields include contact and nameservers. The response contract includes domain, status, expiry, nameservers, and period_years.
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}'Use allow_premium: false unless your application has separately read and approved the exact premium price. Follow registration with GET /domains/{domain}. This lets you inspect current status, expiry, and nameservers instead of assuming that an HTTP success means DNS or registrant verification is complete.
Errors
Section titled “Errors”Handle non-success HTTP responses before using a response body. Real error responses from the live API are JSON and can use either error plus message or a detail value, depending on the endpoint. Preserve the HTTP status and response body with your workflow record, but never treat the body as proof that a paid action did or did not complete.
An unauthenticated protected request currently returns HTTP 401:
{ "error": "unauthorized", "message": "REST requests must include Authorization: Bearer <api key>."}An unknown REST route currently returns HTTP 404:
{ "detail": "Not Found"}The public Pricing API currently returns HTTP 422 for an invalid domain quote:
{ "error": "invalid_domain", "message": "The domain name is invalid."}For 401, correct the missing or invalid token instead of retrying repeatedly. For 404, correct the path or method. For an invalid quote, correct the candidate domain. A 502 or 503 from a dependent service is a temporary unknown result, not evidence that a domain is available or unavailable.
Retries and idempotency
Section titled “Retries and idempotency”The documented REST contract does not promise an idempotency header, atomic batch rollback, or a sandbox. Do not invent an idempotency key or assume a repeated POST /domains is harmless. If a paid registration or renewal request times out, loses its connection, or returns an uncertain outcome, read the account-owned domain state and correlate it with your durable operation record before considering another request.
Use bounded backoff for transient read failures. Keep read and paid stages separate: check availability and pricing first, record the approved candidate and amount, then make one registration request. Afterward, read the holding and verify the returned status. This protects against a retry becoming a duplicate purchase attempt.
Next steps
Section titled “Next steps”Read the REST operations reference for supported request fields, paths, and response contracts. Use the Pricing API when you need public catalog prices or a no-account quote. Use authentication for credential choices, domain registration basics for the lifecycle, and nameservers before replacing a delegation.