FreeNS — Бесплатный DNS

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

Все запросы к API требуют аутентификации. Передавайте ваш API-ключ одним из способов:

Заголовок X-API-Key

curl -H "X-API-Key: fns_ваш_ключ" \
  https://freens.ru/api/v1/domains

Bearer-токен

curl -H "Authorization: Bearer fns_ваш_ключ" \
  https://freens.ru/api/v1/domains

API-ключ можно создать на странице API-ключи. Ключ показывается только один раз при создании — сохраните его.

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

Все ответы возвращаются в формате JSON. При ошибке возвращается объект с полем error:

{"error": "Domain not found"}

Домены

GET /api/v1/domains Список ваших доменов

curl -H "X-API-Key: fns_..." https://freens.ru/api/v1/domains

Пример ответа

{
  "domains": [
    {
      "id": 1,
      "user_id": 1,
      "name": "example.com",
      "is_active": true,
      "serial": 3,
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T14:30:00Z"
    }
  ]
}

POST /api/v1/domains Добавить домен

curl -X POST -H "X-API-Key: fns_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}' \
  https://freens.ru/api/v1/domains

Пример ответа (201)

{
  "domain": {
    "id": 2,
    "user_id": 1,
    "name": "example.com",
    "is_active": true,
    "serial": 1,
    "created_at": "2026-02-18T12:00:00Z",
    "updated_at": "2026-02-18T12:00:00Z"
  }
}

GET /api/v1/domains/{id} Домен и его записи

curl -H "X-API-Key: fns_..." https://freens.ru/api/v1/domains/1

DELETE /api/v1/domains/{id} Удалить домен

curl -X DELETE -H "X-API-Key: fns_..." \
  https://freens.ru/api/v1/domains/1

DNS-записи

Поддерживаемые типы: A, AAAA, CNAME, MX, TXT, NS, SRV

GET /api/v1/domains/{id}/records Список записей

curl -H "X-API-Key: fns_..." \
  https://freens.ru/api/v1/domains/1/records

Пример ответа

{
  "records": [
    {
      "id": 1,
      "domain_id": 1,
      "name": "@",
      "type": "A",
      "content": "93.184.216.34",
      "ttl": 3600,
      "created_at": "2026-01-15T12:00:00Z",
      "updated_at": "2026-01-15T12:00:00Z"
    },
    {
      "id": 2,
      "domain_id": 1,
      "name": "@",
      "type": "MX",
      "content": "mail.example.com",
      "ttl": 3600,
      "priority": 10,
      "created_at": "2026-01-15T12:05:00Z",
      "updated_at": "2026-01-15T12:05:00Z"
    }
  ]
}

POST /api/v1/domains/{id}/records Создать запись

curl -X POST -H "X-API-Key: fns_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "@", "type": "A", "content": "93.184.216.34", "ttl": 3600}' \
  https://freens.ru/api/v1/domains/1/records

Поля запроса

Поле	Тип	Обязательное	Описание
`name`	string	нет	Имя записи. По умолчанию `@` (корень домена)
`type`	string	да	A, AAAA, CNAME, MX, TXT, NS, SRV
`content`	string	да	Значение записи (IP, домен и т.д.)
`ttl`	number	нет	TTL в секундах, 60–86400. По умолчанию 3600
`priority`	number	нет	Приоритет (для MX и SRV)

PUT /api/v1/domains/{id}/records/{recordId} Обновить запись

curl -X PUT -H "X-API-Key: fns_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "1.2.3.4"}' \
  https://freens.ru/api/v1/domains/1/records/1

Можно передать только изменяемые поля — остальные сохранятся.

DELETE /api/v1/domains/{id}/records/{recordId} Удалить запись

curl -X DELETE -H "X-API-Key: fns_..." \
  https://freens.ru/api/v1/domains/1/records/1

Dynamic DNS (DDNS)

FreeNS поддерживает DynDNS-совместимый протокол. Работает с большинством DDNS-клиентов (ddclient, Fritz!Box, роутеры и т.д.).

GET /nic/update?hostname=...&myip=... Обновить IP

Аутентификация через HTTP Basic Auth. Логин — префикс DDNS-токена, пароль — полный токен.

curl -u "префикс_токена:полный_токен" \
  "https://freens.ru/nic/update?hostname=sub.example.com&myip=1.2.3.4"

Коды ответов

Ответ	Описание
`good 1.2.3.4`	IP успешно обновлён
`nochg 1.2.3.4`	IP не изменился
`nohost`	Запись не найдена
`badauth`	Неверная аутентификация
`notfqdn`	Некорректное имя хоста
`badip`	Некорректный IP-адрес

Настройка ddclient

protocol=dyndns2
server=https://freens.ru
login=префикс_токена
password='полный_токен'
sub.example.com

Коды ошибок HTTP

Код	Описание
`200`	Успешный запрос
`201`	Ресурс создан
`400`	Некорректный запрос (невалидные данные)
`401`	Аутентификация не пройдена
`403`	Доступ запрещён (лимит исчерпан)
`404`	Ресурс не найден
`409`	Конфликт (домен уже существует)
`500`	Внутренняя ошибка сервера

Документация API