# name.am — Full API Documentation

> Armenian domain registrar and marketplace. Register .AM domains and 200+ other extensions.

Base URL: `https://api.name.am`

All endpoints are public. Authentication is optional and only needed for user-specific features (cart, account).

---

## Check Domain Availability

Check availability and pricing for one or more domain names.

**Endpoint:** `POST /client/domains/check`
**Auth:** Optional
**Max:** 20 domains per request

### Request Body

JSON array of domain objects:

```json
[
  { "domain": "example", "tld": "am", "main": true },
  { "domain": "example", "tld": "com", "main": false }
]
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| domain | string | yes | Second-level domain name (without the TLD) |
| tld | string | yes | Top-level domain extension (e.g. "am", "com", "net", "org", "com.am") |
| main | boolean | no | Mark as the primary search domain |

**Supported compound TLDs:** com.am, co.am, org.am, net.am, com.ru, pp.ru, org.ru, net.ru

### Response

JSON array:

```json
[
  {
    "domain": "example.am",
    "available": true,
    "main": true,
    "premium": false,
    "tld": "am",
    "price": 5000,
    "priceRenew": 5000,
    "valid": true
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| domain | string | Full domain name |
| available | boolean | Whether the domain is available for registration |
| main | boolean | Echo of request field |
| premium | boolean | Whether the domain is a premium/marketplace listing |
| tld | string | TLD extension |
| price | number | Registration price in AMD (Armenian Dram) per year |
| priceRenew | number | Renewal price in AMD per year |
| valid | boolean | Whether the TLD is supported |

---

## Suggest Domains

Get AI-powered domain name suggestions based on a seed domain. Returns approximately 30 creative alternatives.

**Endpoint:** `POST /client/domains/suggest`
**Auth:** Optional
**Latency:** 5-10 seconds (uses AI generation)

### Request Body

JSON array with at least one domain:

```json
[
  { "domain": "myapp", "tld": "am", "main": true }
]
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| domain | string | yes | Seed domain name (without TLD) |
| tld | string | yes | TLD extension |
| main | boolean | no | Mark as the primary seed domain |

### Response

JSON array of suggested domains:

```json
[
  { "domain": "myapp.com", "tld": "com", "main": true },
  { "domain": "myapp-pro.am", "tld": "am", "main": false },
  { "domain": "getmyapp.io", "tld": "io", "main": false }
]
```

| Field | Type | Description |
|-------|------|-------------|
| domain | string | Suggested full domain name |
| tld | string | TLD extension |
| main | boolean | True if this is the original domain (when available) |

---

## Search Marketplace

Browse domains listed for sale on the name.am marketplace. Supports filtering by keyword, price range, and TLD.

**Endpoint:** `GET /client/marketplace`
**Auth:** Optional

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| keyword | string | — | Search keyword to filter domain names |
| minPrice | number | 0 | Minimum price in USD |
| maxPrice | number | 10000000 | Maximum price in USD |
| extensions | string[] | — | TLD extensions to filter by (repeat parameter for multiple: `extensions=am&extensions=com`) |
| minLength | number | 1 | Minimum domain name length |
| maxLength | number | 20 | Maximum domain name length |
| page | number | 1 | Page number |
| limit | number | 10 | Results per page |

### Response

Paginated JSON:

```json
{
  "docs": [
    {
      "domain": "tech.am",
      "lastBidPrice": 500,
      "minBidPrice": 250,
      "currency": "USD",
      "bin": false,
      "startAt": "2026-01-15T10:00:00Z",
      "endAt": "2026-01-21T10:00:00Z"
    }
  ],
  "totalDocs": 125,
  "limit": 10,
  "page": 1,
  "pages": 13,
  "hasNextPage": true,
  "hasPrevPage": false
}
```

| Field | Type | Description |
|-------|------|-------------|
| docs | array | Array of marketplace listings |
| docs[].domain | string | Full domain name |
| docs[].lastBidPrice | number | Current/last bid price in USD |
| docs[].minBidPrice | number | Minimum bid price in USD |
| docs[].currency | string | Currency code (always "USD") |
| docs[].bin | boolean | Buy-it-now available |
| docs[].startAt | string | Auction start date (ISO 8601) |
| docs[].endAt | string | Auction end date (ISO 8601) |
| totalDocs | number | Total matching listings |
| page | number | Current page |
| pages | number | Total pages |
| hasNextPage | boolean | Whether more pages exist |
| hasPrevPage | boolean | Whether previous pages exist |

---

## Quick AM Check

Quick availability check for .AM domains specifically. Lightweight alternative to the full check endpoint.

**Endpoint:** `GET /client/domain-ideas/:domain`
**Auth:** None

### URL Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| domain | string | Full domain name to check (e.g. "example.am") |

### Response

```json
{
  "available": true
}
```

| Field | Type | Description |
|-------|------|-------------|
| available | boolean | Whether the .AM domain is available |

---

## TLD Pricing

Get the full pricing list for all supported domain extensions.

**Endpoint:** `GET /client/products`
**Auth:** None

### Response

JSON array of TLD products:

```json
[
  {
    "name": "am",
    "type": "tld",
    "popular": true,
    "plans": [
      {
        "_id": "1_year_register",
        "behavior": "register",
        "duration": 1,
        "durationUnit": "year",
        "currency": "AMD",
        "currentPrice": 5000,
        "regularPrice": 5000
      },
      {
        "_id": "1_year_renew",
        "behavior": "renew",
        "duration": 1,
        "durationUnit": "year",
        "currency": "AMD",
        "currentPrice": 5000,
        "regularPrice": 5000
      },
      {
        "_id": "1_year_transfer",
        "behavior": "transfer",
        "duration": 1,
        "durationUnit": "year",
        "currency": "AMD",
        "currentPrice": 4000,
        "regularPrice": 4000
      }
    ]
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| name | string | TLD extension name (e.g. "am", "com", "net") |
| type | string | Product type (always "tld" for domains) |
| popular | boolean | Whether this TLD is marked as popular |
| special | boolean | Whether this TLD has a special promotion |
| plans | array | Pricing plans for different operations and durations |
| plans[].behavior | string | Operation type: "register", "renew", "transfer", or "reactivate" |
| plans[].duration | number | Duration value |
| plans[].durationUnit | string | Duration unit (e.g. "year") |
| plans[].currency | string | Currency code (always "AMD" — Armenian Dram) |
| plans[].currentPrice | number | Current price (may include active discounts) |
| plans[].regularPrice | number | Regular price without discounts |

---

## Notes

- All prices from the products endpoint are in **AMD (Armenian Dram)**. Marketplace prices are in **USD**.
- The check endpoint supports 200+ TLD extensions. Use the products endpoint to see all available TLDs.
- Domain names must follow standard rules: alphanumeric characters and hyphens, 1-63 characters, cannot start or end with a hyphen.
- Rate limiting may apply to automated requests.