CNF API · v1

Обзор

Версия 1 предоставляет операции DNS для зон, на которые вы заявили права через Управление DNS. Создавать и отзывать токены можно на странице Учётная запись → Ключи API.

Базовый URL и версии

https://api.c.nf/v1

Все эндпоинты находятся под /v1. Изменения с нарушением обратной совместимости получат путь с новой основной версией. Совместимые поля и эндпоинты могут добавляться в v1 и будут отмечаться в журнале изменений.

Аутентификация и области доступа

Каждый запрос, который читает или изменяет данные учётной записи, должен содержать Bearer-токен. Токены начинаются с cnf_, после которого идут 32 шестнадцатеричных символа.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

Токены хранятся в виде однонаправленных хешей, а полное значение показывается только при создании. Если токен потерян, отзовите его и создайте новый.

У каждого токена есть области доступа. Токен без настроенной области по умолчанию получает dns:read. Область записи также разрешает чтение.

При несоответствии возвращается 403 forbidden_scope с полями required_scopes и token_scopes для диагностики.

Изоляция пользователей

Bearer-токен однозначно соответствует одному user_id. Перед любым чтением или изменением каждый обработчик зоны проверяет подтверждённую заявку этого пользователя. Обхода через администратора, подмены пользователя или межпользовательского доступа нет.

Даже токен с * может работать только с зонами, подтверждёнными его собственным пользователем. При попытке использовать зону другой учётной записи возвращается 403 forbidden_zone.

Оболочка ответа

Успешный ответ

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

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

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

request_id присутствует в каждом ответе, его можно безопасно сохранять в журналах на стороне клиента.

Коды ошибок

Подтверждение зоны

Когда запрос POST /v1/dns/zones заявляет права на зону, сервер выбирает один из следующих вариантов:

1. Мгновенное подтверждение (method: "auto") — Используется, если на зону не заявила права другая учётная запись. Заявка подтверждается сразу. Записи становятся авторитетными только после того, как владелец направит делегирование NS у регистратора на возвращённые серверы имён.
2. Подтверждение TXT — Используется для оспариваемой заявки. Добавьте возвращённое значение TXT в _cnfdns-verify.<zone>, затем вызовите POST /v1/dns/zones/{zone}/verify.
3. Устаревшее подтверждение NS — В старых ожидающих заявках может использоваться verify_method: "ns". При подтверждении фактические ответы NS зоны сравниваются с ожидаемым набором серверов имён.

Подтверждение идемпотентно. Повторный запрос для подтверждённой заявки возвращает verified: true, не изменяя её.

Типы записей и ограничения

Поддерживаемые типы записей

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

Поле priority обязательно для MX и SRV и игнорируется для остальных типов. Значение ttl должно составлять от 60 до 2 592 000 секунд.

Эндпоинты

Публичные сервисы

Небольшие надёжные точки без учётной записи: время, адрес, страна, курсы валют и хеши.

Учётная запись

Кому принадлежит токен и что он позволяет.

DNS

Заявите домен, подтвердите контроль над ним и управляйте записями.

Учётные данные

Приватное хранилище учётных данных за одноимённым инструментом.

Файлы

Личное хранилище: список, загрузка, изменение, доступ по ссылке и удаление.

CDN

Кеширование на границе сети и трафик ваших общих файлов.

Пересылка SMS

Сообщения с телефона и ключи, которые их пропускают.

Статические сайты

Загрузите zip — получите сайт.

Развёртывания

Ваши развёрнутые формы, вебхуки и короткие ссылки.

Домены

Ваш портфель доменов и их регистрационные данные.

Пакеты

Публикуйте релизы и получайте их версии и число загрузок.

WHOIS

Регистрационные данные домена, кешируются и используются доменными инструментами.

Для ИИ-агентов

Направьте агента на /v1/ai — краткую справку, которую можно вставить прямо в промпт, — или на /v1/ai?format=json, где те же точки описаны как определения инструментов. /v1/openapi.json — полный контракт OpenAPI 3.1, /llms.txt — карта для сканеров. Все четыре формируются из той же таблицы маршрутов, что и эта страница, поэтому ни один из них не опишет несуществующую точку.

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

Поля запроса

Создание заявки на зону

Создание записи DNS

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

Примеры

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

Быстрый старт

1. Создайте ключ API с областью dns:write на странице Учётная запись → Ключи API и скопируйте его при показе.
2. Сохраните токен в защищённой переменной среды на своём компьютере.
3. Вызовите GET /v1/account/me, чтобы проверить токен и его области доступа.
4. Заявите права на зону. В ответе будет указано, требуется ли мгновенное подтверждение, подтверждение TXT или устаревшее подтверждение NS.
5. Если требуется DNS-доказательство, выполните возвращённые инструкции, затем вызовите эндпоинт подтверждения.
6. Создавайте, читайте, обновляйте и удаляйте записи только после подтверждения заявки.

Журнал изменений

v1.1.0 — управление зонами

• Добавлены заявки на зоны через API, включая мгновенное подтверждение и подтверждение TXT.
• Добавлены эндпоинты статуса одной зоны и идемпотентного подтверждения.
• Добавлен отзыв заявки без неявного удаления записей.
• В список зон добавлены фильтры подтверждённых, ожидающих и всех заявок.

v1.0.0 — первый выпуск

• Добавлена аутентификация по Bearer-токену и изоляция зон по пользователям.
• Добавлены области доступа для чтения и записи.
• Добавлены эндпоинты учётной записи, списка зон и управления записями.
• Добавлена единообразная оболочка ответа с идентификатором запроса.