Skip to the products
LCPanelLicence Center Panel

The REST API

API v1: getting a key, the Authorization header, scopes, every route, rate limits, error codes, and curl, JavaScript and PHP examples.

Reference Updated 6 Nov 2026 34 / 36

AIODomain has a JSON API, version 1, for scripts, apps and other websites. Anyone can search listings, read categories, extensions and recent sales without a key. A member with an API key can also read their own account and watchlist and create and update their own listings. This chapter lists every route, the headers, the scopes, the limits and the errors, with examples you can paste into a terminal.

1. Basics

ItemValue
Base addresshttps://market.example.com/api/v1/<route>
FormatJSON in the answer. A request body may be form fields, JSON, or a query string.
IndexGET /api/v1 lists every route with its method and scope.
Documentation page/api-docs on the site shows the same list with the owner's limits.
AnswersAlways {"ok": true, ...} or {"ok": false, "error": "text"}.
Browser useCORS is open (Access-Control-Allow-Origin: *) and the headers Authorization, X-API-Key and Content-Type are allowed, so a web page can call the public routes. Never put a key in a public web page.
VersionOnly v1 exists. /api/anything-else answers 404 Use /api/v1/....

2. Get a key

  1. Sign in, confirm your e-mail, and open API Keys in the member menu.
  2. Under Make a key fill in Name (where it will be used), What may it do? (tick the scopes), Only from these addresses (optional IP addresses, separated by commas) and Lasts (until I revoke it, 30 days, 90 days or one year). Press Make the key.
  3. Copy the key now. It looks like ad_3f9a1c0e5b7d_ followed by 40 characters. The marketplace keeps only a fingerprint and cannot show it again.

Each member can hold up to 5 keys (the owner may change that), and can make up to 10 keys an hour. Revoke stops a key at once and Enable brings it back; Delete removes it. Staff see every key under Settings → API Keys, with scopes, last use and status, and can revoke any of them. See Settings.

3. Send the key

Send it in a header (preferred):

Authorization: Bearer ad_3f9a1c0e5b7d_9c1e...

or as X-API-Key: <key>, or as a field api_key in the query string or body. The header forms keep the key out of server logs. A wrong key answers 401 Invalid API key. A key that is revoked, expired or tied to other IP addresses is refused (This key may not be used from 203.0.113.7, 403). The account behind a key must be active.

4. Scopes

ScopeMeaning
readSearch, listings, categories and sales, with the higher limit of a key.
listingsCreate and update your own listings, read your listing list.
profileYour account details, watchlist and notifications.

A route that needs a scope the key does not hold answers 403 This key lacks the "listings" scope; without any key, 401 This route needs an API key with the "listings" scope.

5. Limits and errors

LimitDefaultSetting
Calls per minute without a key30, per IP addressCalls per minute without a key
Calls per minute with a key120, per key (a key can carry its own number)Calls per minute with a key
Public routes without a keyallowedPublic API without a key; when off, every call needs a key
Keys per member5Keys per member

These are on Settings → General Settings → Security. Every call is written to the API log with its status and duration; the daily housekeeping job deletes entries older than 60 days.

HTTP codeMeaning
200Done.
400The route refused the input; read error (for example Please give a Buy Now price of at least $1).
401No key, or an invalid key, where one is needed.
403Wrong scope, wrong IP address, or the account is not active.
404Unknown route or version.
405Wrong method (Use GET for this route).
429Rate limit reached. Wait a minute.

Since 1.9.0 there are also routes for your own listings, offers, orders, portfolio, membership and webhooks, with the scopes trade, portfolio and webhooks: see the chapter Webhooks and the wider API.

6. The public routes

All are GET and need no key (at the lower limit).

GET /api/v1/domains

Searches active listings. Parameters:

ParameterMeaning
qKeyword. match changes how it is read: contains (default), starts, ends, exact, keyword (any of the words).
tldOne extension or a comma list: com,io.
typefixed (or buy_now), offer (or make_offer), fixed_offer.
price_min, price_maxIn the marketplace's default currency.
len_min, len_maxLength of the name before the extension.
categoryA category number or address.
verified, featured, premium1 to require it.
hyphen, digits0 for none, 1 for some.
age_min, listed, tag, sellerDomain age in years; listed within 1, 7, 30 or 90 days; a tag; a seller number or profile address.
sortrelevance, newest, price_asc, price_desc, popular, views, ending, length, alpha, age.
page, perPage number; page size 1 to 100 (24 by default).

Answer: ok, total, page, pages and data, a list of listings:

{
  "ok": true, "total": 12, "page": 1, "pages": 6,
  "data": [{
    "id": 14, "domain": "fitforge.co", "tld": "co",
    "url": "https://market.example.com/domain/fitforge.co",
    "listing_type": "fixed_offer", "price": 1500, "min_offer": 500,
    "asking_price": null, "currency": "USD",
    "verified": true, "featured": false, "premium": false,
    "length": 8, "listed_at": "2026-11-02 19:42:11"
  }]
}

price, min_offer and asking_price are null when the listing has none.

GET /api/v1/domain/<name>

One active listing, with more fields: title, description, category, tags (a list), registrar, registered_at, domain_age_years, views and watchers. An unknown or non-public name answers 400 No active listing for <name>.

GET /api/v1/availability?domain=<name>

Is the name listed here, registered elsewhere or free? data.status is listed (with the listing), taken (registered, not for sale here), available (looks free to register) or unknown. An invalid name answers 400 with the reason. The answer for names that are not listed comes from a DNS and RDAP check, so it takes a moment.

GET /api/v1/extensions

Every enabled extension: tld, name, popular (1 or 0) and listings (live listings).

GET /api/v1/categories

Every active category: id, name, slug, parent_id and listings.

GET /api/v1/sales?limit=20

Recent public sales: domain, tld, price, currency, sold_at and venue. limit is 1 to 100.

7. The member routes

These need a key with the scope shown.

RouteMethodScopeWhat it does
/api/v1/meGETprofileThe account behind the key: id, username, email, type, name, country, kyc_status, seller_verified, created_at.
/api/v1/me/listingsGETlistingsYour listings. Parameters status (active, draft, pending, paused, rejected, sold, expired), q (name contains), page (100 per page). Each row has the public fields plus status, is_verified, views, watchers, inquiries.
/api/v1/me/listings/createPOSTlistingsCreates a listing.
/api/v1/me/listings/updatePOSTlistingsUpdates one of your listings.
/api/v1/me/watchlistGETprofileThe domains you watch.
/api/v1/me/notificationsGETprofileYour newest 50 notifications: id, kind, title, body, link, seen, at.

Create a listing

Fields: name (required), listing_type (fixed, offer or fixed_offer), price, min_offer, asking_price, auto_accept_price, title, description, category_id, tags (comma list), keywords, language (two letters) and submit (1 to send it for approval or to publish it at once if it is verified). The same rules apply as in the seller area: a confirmed e-mail, a valid name, the price range, no links in the description, the licence's listing limit. Prices are in the marketplace's default currency. The answer is the new listing with its status. A new listing is a draft until its ownership is verified; start the verification in the seller area (see Verifying ownership).

Update a listing

Send id (a listing of yours) and the fields to change; fields you leave out keep their value. A sold listing cannot be changed. A lower Buy Now price notifies watchers, as in the seller area.

8. Examples

Search:

curl "https://market.example.com/api/v1/domains?q=shop&tld=com,io&price_max=2000&verified=1&sort=price_asc&per=10"

One listing, and availability:

curl "https://market.example.com/api/v1/domain/fitforge.co"
curl "https://market.example.com/api/v1/availability?domain=example.org"

Your account and your drafts:

curl -H "Authorization: Bearer YOUR_KEY" "https://market.example.com/api/v1/me"
curl -H "Authorization: Bearer YOUR_KEY" "https://market.example.com/api/v1/me/listings?status=draft"

Create a listing with JSON:

curl -X POST "https://market.example.com/api/v1/me/listings/create" \
  -H "Authorization: Bearer YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name":"mybrand.com","listing_type":"fixed_offer","price":2500,"min_offer":800,
       "title":"Short brandable name","description":"A clean two-word name.","tags":"brand,short","submit":1}'

Change the price:

curl -X POST "https://market.example.com/api/v1/me/listings/update" \
  -H "Authorization: Bearer YOUR_KEY" -d "id=42" -d "price=2200"

From JavaScript (public route):

fetch('https://market.example.com/api/v1/domains?q=cloud&per=5')
  .then(r => r.json())
  .then(j => j.data.forEach(d => console.log(d.domain, d.price)));

From PHP:

$ch = curl_init('https://market.example.com/api/v1/me');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $key]]);
$me = json_decode(curl_exec($ch), true);

9. Good habits

  • Cache search answers on your side for a minute or two; they change slowly and you save your limit.
  • Keep the key in server code or a secret store, not in a web page, an app bundle or a repository. Use Only from these addresses for a server with a fixed address, and a short Lasts for tests.
  • Make one key per use, with a name, so you can revoke one without breaking the others.
  • Check ok before reading data, and handle 429 by waiting a minute.
  • Staff: watch Settings → API Keys for the busiest routes and the newest errors. A key that suddenly makes thousands of calls is a reason to revoke it.

Plugins can add routes and scopes to the API in later releases; the live list at /api/v1 always shows what is available on your marketplace.

Was this helpful?
Share this chapter