Для разработчиков

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

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

Создать API-ключ →Скачать OpenAPI

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

Все запросы требуют API-ключа в заголовке Authorization. Ключ создаётся в личном кабинете на странице «API-ключи» и показывается один раз. Запрос без валидного ключа отклоняется с 401 invalid_api_key.

Базовый адрес всех эндпоинтов — https://htmlkin.ru/api/v1. В каждый запрос добавляй заголовок:

"Authorization: Bearer <api_key>"

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

Лимиты частоты

Частота запросов ограничена по тарифу — на аккаунт, общим счётчиком для всех его ключей. При превышении возвращается 429 rate_limit_exceeded с заголовком Retry-After.

Тариф	Лимит
Бесплатный	10 запросов в минуту, до 60 загрузок сайта в час вместе с личным кабинетом, обновление сайта — раз в минуту
Про	60 запросов в минуту
Бизнес	120 запросов в минуту

Эндпоинты

POST/api/v1/pages

Опубликовать страницу

Загружает HTML-файл или ZIP статического сайта и публикует его на собственном субдомене. Передаётся ровно одно из полей html_file и site_archive. По умолчанию присваивается случайный субдомен; можно задать свой в поле subdomain.

Тело запроса multipart/form-data

Поле	Тип	Обязательно	Описание
html_file	file	нет	Один HTML-файл; сохраняется как index.html. Ровно один источник контента.
site_archive	file	нет	ZIP статического сайта: входной страницей станет корневой index.html либо первый HTML-файл в корне архива. Распакованный сайт — до 200 МБ и в пределах свободного места в хранилище.
subdomain	string	нет	Желаемый субдомен ({subdomain}.htmlkin.ru), 3–63 символа a-z, 0-9, «-» (не по краям). Если занят — 409.
pin	string	нет	4-значный PIN (0000–9999) для защиты просмотра. На платных тарифах.
visibility	string	нет	Кому открыт сайт: public — всем, сайт индексируют поисковики; link — всем, у кого есть ссылка, без индексации; team — участникам команды аккаунта после входа, на тарифе «Бизнес»; private — только владельцу аккаунта после входа. По умолчанию — public.

Пример запроса

curl -X POST https://htmlkin.ru/api/v1/pages \
  -H "Authorization: Bearer $HTMLKIN_API_KEY" \
  -F "html_file=@index.html" \
  -F "subdomain=mypage"

Ответ 201

{
  "id": "abc123",
  "url": "https://mypage.htmlkin.ru",
  "expires_at": null,
  "created_at": "2026-06-14T07:00:00Z",
  "updated_at": "2026-06-14T07:00:00Z",
  "file_count": 1,
  "entry_path": "index.html",
  "visibility": "public"
}

PUT/api/v1/pages/{id}

Обновить страницу

Полностью заменяет сайт новым HTML или ZIP по тому же адресу и/или меняет PIN и видимость. URL страницы не меняется. Источник — не более одного из полей html_file и site_archive; можно передать только pin и/или visibility, если нужно лишь изменить защиту или видимость.

Тело запроса multipart/form-data

Поле	Тип	Обязательно	Описание
html_file	file	нет	Новый HTML-файл (опционально; не вместе с site_archive).
site_archive	file	нет	Новый полный ZIP сайта; все прежние файлы будут заменены.
pin	string	нет	4 цифры — установить/сменить PIN; пустая строка — снять PIN.
visibility	string	нет	Кому открыт сайт: public — всем, сайт индексируют поисковики; link — всем, у кого есть ссылка, без индексации; team — участникам команды аккаунта после входа, на тарифе «Бизнес»; private — только владельцу аккаунта после входа.

Пример запроса

curl -X PUT https://htmlkin.ru/api/v1/pages/abc123 \
  -H "Authorization: Bearer $HTMLKIN_API_KEY" \
  -F "html_file=@index.html"

Ответ 200

{
  "id": "abc123",
  "url": "https://mypage.htmlkin.ru",
  "expires_at": null,
  "created_at": "2026-06-14T07:00:00Z",
  "updated_at": "2026-06-14T07:10:00Z",
  "size_bytes": 12345,
  "file_count": 8,
  "entry_path": "index.html",
  "pin_protected": false,
  "visibility": "public"
}

GET/api/v1/pages/{id}

Получить информацию о странице

Возвращает метаданные страницы: адрес, размер сайта, число файлов, entrypoint, срок жизни, PIN-защиту и видимость.

Параметры пути

Параметр	Описание
id	Идентификатор страницы.

Пример запроса

curl -X GET https://htmlkin.ru/api/v1/pages/abc123 \
  -H "Authorization: Bearer $HTMLKIN_API_KEY"

Ответ 200

{
  "id": "abc123",
  "url": "https://mypage.htmlkin.ru",
  "expires_at": null,
  "created_at": "2026-06-14T07:00:00Z",
  "updated_at": "2026-06-14T07:10:00Z",
  "size_bytes": 12345,
  "file_count": 8,
  "entry_path": "index.html",
  "pin_protected": false,
  "visibility": "public"
}

DELETE/api/v1/pages/{id}

Удалить страницу

Безвозвратно удаляет страницу. Если к странице был привязан кастомный домен, домен остаётся в аккаунте — снимается только его связь с этой страницей.

Параметры пути

Параметр	Описание
id	Идентификатор страницы.

Пример запроса

curl -X DELETE https://htmlkin.ru/api/v1/pages/abc123 \
  -H "Authorization: Bearer $HTMLKIN_API_KEY"

Ответ 200

{
  "id": "abc123",
  "deleted": true
}

Коды ошибок

Тело ошибки всегда одинаковое: { "error": "<code>", "message": "<описание>" }.

HTTP	error	Описание
400	invalid_file	Одиночный файл не похож на HTML.
400	invalid_site	Неверная комбинация источников или невалидный набор файлов сайта.
400	invalid_archive	ZIP повреждён, зашифрован или использует неподдерживаемый формат.
400	invalid_path	Недопустимый, небезопасный или дублирующийся путь файла.
400	missing_entry_file	В корне сайта нет HTML-файла.
400	too_many_files	В сайте больше 500 полезных файлов.
400	banner_removal	В файле сайта есть код, убирающий промо-бар htmlkin; бар снимается переходом на платный тариф.
400	invalid_pin	PIN не из 4 цифр.
400	invalid_visibility	visibility не из public, link, team, private.
400	invalid_subdomain	Субдомен с недопустимыми символами (разрешены a-z, 0-9, «-»).
401	invalid_api_key	Невалидный или отсутствующий API-ключ.
403	account_banned	Аккаунт заблокирован за нарушение правил сервиса.
403	team_visibility_requires_plan	Режим team доступен на тарифе «Бизнес».
403	content_blocked	Входная страница (index.html) побайтово совпадает со страницей сайта, заблокированного за нарушение правил сервиса.
403	dangerous_link	На странице есть ссылка, которую Google Web Risk относит к фишингу или вредоносному ПО.
403	page_limit_exceeded	Превышен лимит активных сайтов по тарифу.
404	not_found	Страница не найдена или принадлежит другому владельцу.
409	subdomain_taken	Запрошенный субдомен уже занят.
413	file_too_large	Распакованный сайт больше 200 МБ — предела одной загрузки.
413	storage_limit_exceeded	Сайт не помещается в хранилище: вместе с остальными активными сайтами аккаунта он превысил бы объём хранилища тарифа. При обновлении место текущей версии сайта учитывается как свободное.
429	rate_limit_exceeded	Превышена частота запросов; в ответе заголовок Retry-After.

Тестирование и генерация клиентов

API описан машиночитаемой спецификацией OpenAPI 3.1. Импортируй её, чтобы интерактивно отправлять запросы и генерировать готовый клиент под свой язык:

Swagger UI / Postman — вставь адрес https://htmlkin.ru/api/v1/openapi.json, задай Bearer-ключ и вызывай эндпоинты прямо из браузера.
openapi-generator — сгенерируй SDK для Python, TypeScript, Go и других языков одной командой из той же спецификации.

Публикация из ИИ-ассистентов (MCP)

Тот же API доступен через MCP-сервер https://htmlkin.ru/mcp — Claude и другие ассистенты публикуют и обновляют сайты прямо из диалога, по твоему API-ключу. Устанавливать и запускать ничего не нужно.

Настройка MCP-сервера →