The REST API
API v1: getting a key, the Authorization header, scopes, every route, rate limits, error codes, and curl, JavaScript and PHP examples.
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
| Item | Value |
|---|---|
| Base address | https://market.example.com/api/v1/<route> |
| Format | JSON in the answer. A request body may be form fields, JSON, or a query string. |
| Index | GET /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. |
| Answers | Always {"ok": true, ...} or {"ok": false, "error": "text"}. |
| Browser use | CORS 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. |
| Version | Only v1 exists. /api/anything-else answers 404 Use /api/v1/.... |
2. Get a key
- Sign in, confirm your e-mail, and open API Keys in the member menu.
- 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.
- 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
| Scope | Meaning |
|---|---|
read | Search, listings, categories and sales, with the higher limit of a key. |
listings | Create and update your own listings, read your listing list. |
profile | Your 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
| Limit | Default | Setting |
|---|---|---|
| Calls per minute without a key | 30, per IP address | Calls per minute without a key |
| Calls per minute with a key | 120, per key (a key can carry its own number) | Calls per minute with a key |
| Public routes without a key | allowed | Public API without a key; when off, every call needs a key |
| Keys per member | 5 | Keys 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 code | Meaning |
|---|---|
| 200 | Done. |
| 400 | The route refused the input; read error (for example Please give a Buy Now price of at least $1). |
| 401 | No key, or an invalid key, where one is needed. |
| 403 | Wrong scope, wrong IP address, or the account is not active. |
| 404 | Unknown route or version. |
| 405 | Wrong method (Use GET for this route). |
| 429 | Rate 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:
| Parameter | Meaning |
|---|---|
q | Keyword. match changes how it is read: contains (default), starts, ends, exact, keyword (any of the words). |
tld | One extension or a comma list: com,io. |
type | fixed (or buy_now), offer (or make_offer), fixed_offer. |
price_min, price_max | In the marketplace's default currency. |
len_min, len_max | Length of the name before the extension. |
category | A category number or address. |
verified, featured, premium | 1 to require it. |
hyphen, digits | 0 for none, 1 for some. |
age_min, listed, tag, seller | Domain age in years; listed within 1, 7, 30 or 90 days; a tag; a seller number or profile address. |
sort | relevance, newest, price_asc, price_desc, popular, views, ending, length, alpha, age. |
page, per | Page 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.
| Route | Method | Scope | What it does |
|---|---|---|---|
/api/v1/me | GET | profile | The account behind the key: id, username, email, type, name, country, kyc_status, seller_verified, created_at. |
/api/v1/me/listings | GET | listings | Your 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/create | POST | listings | Creates a listing. |
/api/v1/me/listings/update | POST | listings | Updates one of your listings. |
/api/v1/me/watchlist | GET | profile | The domains you watch. |
/api/v1/me/notifications | GET | profile | Your 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
okbefore readingdata, 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.