Справочник API

Аутентификация

Все API-запросы требуют аутентификации с помощью API-ключа. Передавайте ключ в заголовке Authorization как Bearer-токен. API-ключ должен начинаться с префикса nxd_.

Authorization: Bearer nxd_your_api_key_here

API работает без сохранения состояния – каждый запрос аутентифицируется независимо. Сессии и cookies не используются.

Храните API-ключ в секрете. Не передавайте его в клиентском коде, публичных репозиториях или URL-адресах. Если ключ скомпрометирован, немедленно отзовите его и создайте новый.

Ошибки аутентификации

Формат ответа

Все ответы возвращаются в формате JSON. Успешные ответы имеют следующую структуру:

Единичный ресурс

{
    "status": "success",
    "data": {
        "id": 42,
        "public_id": "xK9mP2",
        "name": "example.com",
        ...
    }
}

Список с пагинацией

{
    "status": "success",
    "data": [ ... ],
    "meta": {
        "total": 150,
        "page": 1,
        "per_page": 25,
        "last_page": 6
    }
}

Ответ с ошибкой

{
    "status": "error",
    "error": {
        "code": "validation_error",
        "message": "Validation failed.",
        "details": {
            "name": ["Domain name is required."]
        }
    }
}

Публичные ID

Каждый ресурс идентифицируется непрозрачным id (например, xK9mQ2), который используется в URL-путях. Числовые ID из базы данных никогда не раскрываются и не принимаются.

Пагинация

Эндпоинты списков, возвращающие постраничные результаты, принимают следующие параметры запроса:

Зоны

Управление DNS-зонами. Требуется zones.read для операций чтения и zones.write для операций записи.

GET /v1/zones

Список всех зон аутентифицированного пользователя.

Параметры запроса

• search – фильтрация зон по имени
• page, per_page – пагинация

Поля ответа

id, name, type (master или slave), status, ns_group, created_at, updated_at

GET /v1/zones/{id}

Получение подробной информации о конкретной зоне, включая SOA-данные, серверы имён и количество записей.

Дополнительные поля ответа

records_count, soa (primary_ns, admin_email, serial, refresh, retry, expire, minimum), nameservers (массив), ns_group (id, slug, name)

POST /v1/zones

Создание новой DNS-зоны. Создание зоны заблокировано при наличии просроченных счетов.

Тело запроса (JSON)

{
    "name": "example.com",
    "type": "master",
    "ns_group_id": 1,
    "master_ip": ""
}

• name (обязательно) – доменное имя
• type – "master" (по умолчанию) или "slave"
• ns_group – группа NS для назначения зоны (необязательно, используется группа по умолчанию)
• master_ip – обязательно для slave-зон; должен быть валидным IP-адресом

Возвращает 201 Created с объектом зоны.

DELETE /v1/zones/{id}

Удаление зоны и всех её записей.

Возвращает 204 No Content при успехе.

GET /v1/zones/{id}/export

Экспорт зоны в формате BIND или в структурированном JSON.

Параметры запроса

• format – "bind" (по умолчанию) возвращает текст зонного файла BIND; "json" возвращает структурированный массив записей с полями name, type, content и ttl

Записи

Управление DNS-записями в зоне. Все эндпоинты записей вложены в зону. Требуется records.read для операций чтения и records.write для операций записи.

GET /v1/zones/{zoneId}/records

Список всех записей в зоне.

Параметры запроса

• type – фильтрация по типу записи (например, A, CNAME, MX)
• name – фильтрация по имени записи (поиск подстроки)
• search – поиск по имени и содержимому

Поля ответа

id, name, type, content, ttl, disabled, fields (специфичные для типа поля)

GET /v1/zones/{zoneId}/records/{recordId}

Получение одной записи по её ID.

POST /v1/zones/{zoneId}/records

Создание новой DNS-записи.

Тело запроса (JSON)

{
    "type": "A",
    "name": "www",
    "ttl": 3600,
    "content": "93.184.216.34"
}

• type (обязательно) – тип записи (A, AAAA, CNAME, MX, TXT, SRV, CAA, NS, PTR, ALIAS, DNAME, DS, TLSA)
• name – имя записи относительно зоны (по умолчанию: @ – вершина зоны)
• ttl – время жизни в секундах (по умолчанию: 3600)
• content – значение записи (IP для A/AAAA, имя хоста для CNAME/NS/PTR, текст для TXT, почтовый сервер для MX)

Поля для конкретных типов

• MX: priority (по умолчанию: 10)
• SRV: поля priority, weight, port
• CAA: flags (по умолчанию: 0), tag (по умолчанию: "issue")
• DS: поля keytag, algorithm, digest_type
• TLSA: поля usage, selector, matching_type

Возвращает 201 Created с объектом записи.

PUT /v1/zones/{zoneId}/records/{recordId}

Обновление существующей записи. Укажите только поля, которые хотите изменить; остальные сохранят текущие значения.

{
    "content": "93.184.216.35",
    "ttl": 7200
}

Возвращает 200 OK с обновлённым объектом записи. Примечание: ID записи может измениться после обновления, так как он вычисляется из имени, типа и содержимого записи.

DELETE /v1/zones/{zoneId}/records/{recordId}

Удаление записи из зоны.

Возвращает 204 No Content при успехе.

DNSSEC

Управление DNSSEC для ваших зон. Требуется zones.read для просмотра статуса и zones.write для включения или отключения.

GET /v1/zones/{id}/dnssec

Получение статуса DNSSEC для зоны, включая ключи и DS-записи.

Поля ответа

enabled (boolean), keys (массив DNSKEY-записей), ds_records (массив DS-записей для установки у регистратора)

POST /v1/zones/{id}/dnssec/enable

Включение DNSSEC для зоны. Ключи подписи генерируются автоматически.

Возвращает статус DNSSEC с сгенерированными ключами и DS-записями.

POST /v1/zones/{id}/dnssec/disable

Отключение DNSSEC для зоны. Удаляет все ключи подписи.

Возвращает {"enabled": false, "keys": [], "ds_records": []}.

NS-группы

Список доступных групп DNS-серверов. Используйте id группы как ns_group при создании зоны. Эндпоинт доступен по любому действующему API-ключу.

GET /v1/ns-groups

Список активных групп DNS-серверов.

Поля ответа для каждой группы

id, name, slug

Аккаунт

Просмотр информации об аккаунте и управление API-ключами.

GET /v1/account

Получение информации о текущем аккаунте, включая данные подписки.

Поля ответа

Поля id (UUID), email, name, role, status, language, timezone, created_at.

subscription – объект с полями plan, billing_cycle, status, current_period_start, current_period_end (или null при отсутствии подписки)

GET /v1/account/api-keys

Список всех API-ключей аутентифицированного пользователя.

Поля ответа для каждого ключа

id, name, key_prefix (первые 8 символов), permissions (массив), last_used_at, expires_at, created_at

POST /v1/account/api-keys

Создание нового API-ключа.

Тело запроса (JSON)

{
    "name": "CI/CD Pipeline",
    "permissions": ["zones.read", "records.read", "records.write"],
    "expires_at": "2027-01-01"
}

• name (обязательно) – понятное имя (максимум 255 символов)
• permissions (обязательно) – массив разрешений (минимум одно): zones.read, zones.write, records.read, records.write, webhooks.read, webhooks.write
• expires_at – необязательная дата истечения (ISO 8601 или YYYY-MM-DD); должна быть в будущем

Ответ содержит полный API-ключ в поле key. Это единственный раз, когда полный ключ возвращается. Сохраните его в надёжном месте.

Возвращает 201 Created с данными ключа, включая полное значение key.

DELETE /v1/account/api-keys/{id}

Отзыв (безвозвратное удаление) API-ключа.

Возвращает 204 No Content при успехе.

Биллинг

Просмотр подписки, тарифных планов и счетов. Эти эндпоинты доступны только для чтения.

GET /v1/billing/subscription

Получение данных текущей подписки. Возвращает null при отсутствии активной подписки.

Поля ответа

Поля id, plan, billing_cycle, status, current_period_start, current_period_end, created_at.

GET /v1/billing/plans

Список всех доступных тарифных планов с ценами и функциями.

Поля ответа для каждого плана

id, name, slug, description, price_monthly, price_yearly, currency, max_domains, max_records, features (массив)

GET /v1/billing/invoices

Список счетов аутентифицированного пользователя, сначала новые.

Параметры запроса

• status – фильтрация по статусу (draft, issued, sent, void)
• page, per_page – пагинация

GET /v1/billing/invoices/{id}

Получение одного счёта по его <code>id</code>.

Поля ответа

Поля id, number, status, amount (итоговая сумма), net_amount (без налога), tax_amount, tax_rate, currency, issued_at, created_at. Денежные значения передаются строками с десятичной точкой.

Webhooks

Управление исходящими webhook-подписками для получения уведомлений об изменениях зон и записей в реальном времени. Требует webhooks.read для чтения и webhooks.write для создания, изменения и удаления.

GET /v1/webhooks

Список всех webhook-подписок аутентифицированного пользователя.

Поля ответа для каждой подписки

id, url, events (массив), description, is_active, failure_count, last_triggered_at, created_at

POST /v1/webhooks

Создание webhook-подписки.

Тело запроса (JSON)

{
    "url": "https://example.com/webhook",
    "events": ["zone.created", "record.created"],
    "description": "Production webhook"
}

• url (обязательно) – HTTPS-адрес, на который будут отправляться данные событий
• events (обязательно) – массив типов событий для подписки
• description – необязательная понятная метка

Ответ содержит secret для проверки подписи webhook (HMAC). Это единственный раз, когда secret возвращается. Сохраните его в надёжном месте.

Возвращает 201 Created с id и secret подписки.

GET /v1/webhooks/{id}

Получение одной webhook-подписки вместе с последними доставками.

PUT /v1/webhooks/{id}

Изменение webhook-подписки. Указывайте только те поля, которые нужно изменить.

Возвращает 200 OK с обновлённым объектом подписки.

DELETE /v1/webhooks/{id}

Удаление webhook-подписки.

Возвращает 204 No Content при успехе.

POST /v1/webhooks/{id}/test

Отправка тестового события на адрес webhook для проверки доступности.

Ставит в очередь тестовую доставку с данными "type": "test".

Доступные типы событий

Можно подписаться на любую комбинацию этих типов событий:

zone.created, zone.deleted, record.created, record.updated, record.deleted, dnssec.enabled, dnssec.disabled, zone.health.problem, zone.health.resolved

Коды ошибок

Все ошибки имеют единый формат со строковым code ошибки и понятным message.

Примеры кода

Все примеры используют curl. Замените nxd_your_api_key на ваш настоящий API-ключ.

Список зон

curl -s "https://api.nexdns.ru/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key"

Создание зоны

curl -s -X POST "https://api.nexdns.ru/v1/zones" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"name": "example.com"}'

Добавление A-записи

curl -s -X POST "https://api.nexdns.ru/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "A",
        "name": "www",
        "ttl": 3600,
        "content": "93.184.216.34"
    }'

Добавление MX-записи

curl -s -X POST "https://api.nexdns.ru/v1/zones/{zoneId}/records" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "type": "MX",
        "name": "@",
        "ttl": 3600,
        "content": "mail.example.com",
        "priority": 10
    }'

Обновление записи

curl -s -X PUT "https://api.nexdns.ru/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"content": "93.184.216.35", "ttl": 7200}'

Удаление записи

curl -s -X DELETE "https://api.nexdns.ru/v1/zones/{zoneId}/records/{recordId}" \
    -H "Authorization: Bearer nxd_your_api_key"

Экспорт зоны (формат BIND)

curl -s "https://api.nexdns.ru/v1/zones/{zoneId}/export" \
    -H "Authorization: Bearer nxd_your_api_key"

Включение DNSSEC

curl -s -X POST "https://api.nexdns.ru/v1/zones/{zoneId}/dnssec/enable" \
    -H "Authorization: Bearer nxd_your_api_key"

Создание API-ключа

curl -s -X POST "https://api.nexdns.ru/v1/account/api-keys" \
    -H "Authorization: Bearer nxd_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Read-only key",
        "permissions": ["zones.read", "records.read"],
        "expires_at": "2027-12-31"
    }'

Информация об аккаунте

curl -s "https://api.nexdns.ru/v1/account" \
    -H "Authorization: Bearer nxd_your_api_key"