Domain REST API operations and response checks

AiVikings.ai exposes domain registration and management through https://api.aivikings.ai/v1. Send a customer bearer token in the Authorization header for protected REST operations. Registration and renewal spend prepaid balance; using the API does not make the domain itself free.

How it works

Start with a read request. Keep the token in an environment variable, not in source control or a browser bundle.

curl --fail-with-body https://api.aivikings.ai/v1/domains \
  -H "Authorization: Bearer $AIVIKINGS_TOKEN"

The response has a domains array. An empty account can return {"domains":[]}. That is a schema example, not a captured customer account. Each populated record includes the domain and saved status; list records expose expires_at, while the individual status response uses expiry. Do not conflate those fields.

The nameserver operation is PATCH on the domain resource. Do not use an invented PUT /nameservers endpoint. The A-record convenience route is not the complete DNS record API; use the MCP tools reference for the broader DNS tool surface.

How do I check availability before registration?

Send up to 200 names in one REST availability request. The response contains one set of domain facts per result, including an availability value that may be unknown. Accept only a positive availability result for a purchase candidate. Missing prices and uncertain availability must remain explicit conditions in the application.

curl --fail-with-body https://api.aivikings.ai/v1/domains/check \
  -H "Authorization: Bearer $AIVIKINGS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"domains":["example.com"],"currency":"USD"}'

How do I register or renew through code?

After verifying the contact, quote and spending authority, use the registration or renewal route. The registration request accepts a period of 1-10 years at schema level; registry rules may constrain the actual allowed term. Registration is one domain per request. A portfolio workflow sends and records separate paid operations rather than assuming an atomic bulk purchase.

{"domain":"your-approved-domain.tld","period_years":1,"allow_premium":false}

This is a registration request shape with an intentional placeholder, not a name to purchase. The response contract includes domain, status, expiry, nameservers and period_years. Inspect the returned status and then read the holding back. An HTTP success alone is not evidence that DNS or hosting is ready.

What happens after a timeout?

An interrupted paid request has an unknown outcome. Read the account-owned domain state and correlate it with your durable operation record before retrying. This reference does not promise an idempotency header, atomic batch rollback or a sandbox. Those capabilities should only be relied on when the specific API contract documents them.

Use bounded backoff for transient read failures. For permission errors, correct the token scope or account context instead of retrying indefinitely. Keep tokens out of diagnostic logs and retain request identifiers only when the response actually supplies them.

When this is not the right fit

This reference is not a complete OpenAPI replacement. Consult the developer documentation for the current contract before generating a client.

Related: live pricing, authentication, DNS orchestration.