Документация REST API
Публикуйте и обновляйте HTML-страницы прямо из кода и AI-пайплайнов. Публикация и обновление статических сайтов, HTML-страниц и PDF-документов из кода и AI-пайплайнов. Доступен на тарифах Оптимальный и Бизнес по API-ключу.
Аутентификация
Все запросы требуют API-ключа в заголовке Authorization. Ключ создаётся в личном кабинете на странице «API-ключи» и показывается один раз. Запрос без валидного ключа отклоняется с 401 invalid_api_key.
Базовый адрес всех эндпоинтов — https://htmlkin.ru/api/v1. В каждый запрос добавляйте заголовок:
"Authorization: Bearer <api_key>"API доступен на тарифах Оптимальный и Бизнес. Ключ создаётся в личном кабинете на странице «API-ключи» и показывается один раз.
Лимиты частоты
Частота запросов ограничена по тарифу. При превышении возвращается 429 rate_limit_exceeded с заголовком Retry-After.
| Тариф | Лимит |
|---|---|
| Оптимальный | 60 запросов в минуту |
| Бизнес | 120 запросов в минуту |
Эндпоинты
Опубликовать страницу
Загружает HTML-файл, ZIP статического сайта или PDF-документ и публикует его на собственном субдомене. Передаётся ровно одно из полей html_file, site_archive и pdf_file. По умолчанию присваивается случайный субдомен; можно задать свой в поле subdomain.
multipart/form-data| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| html_file | file | нет | Один HTML-файл; сохраняется как index.html. Ровно один источник контента. |
| site_archive | file | нет | ZIP статического сайта: корневой index.html, суммарный распакованный лимит тарифа. |
| pdf_file | file | нет | PDF-документ вместо сайта. Ровно один источник контента. |
| subdomain | string | нет | Желаемый субдомен ({subdomain}.htmlkin.ru), символы a-z, 0-9, «-». Если занят — 409. |
| pin | string | нет | 4-значный PIN (0000–9999) для защиты просмотра. На платных тарифах. |
{
"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"
}Обновить страницу
Полностью заменяет сайт новым HTML, ZIP или PDF по тому же адресу и/или меняет PIN. URL страницы не меняется (тип контента менять можно: HTML-страницу допустимо заменить PDF-документом и наоборот). Источник — не более одного из полей html_file, site_archive и pdf_file; можно передать только pin, если нужно лишь изменить защиту.
multipart/form-data| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
| html_file | file | нет | Новый HTML-файл (опционально; не вместе с pdf_file). |
| site_archive | file | нет | Новый полный ZIP сайта; все прежние файлы будут заменены. |
| pdf_file | file | нет | Новый PDF-документ (опционально; не вместе с html_file). |
| pin | string | нет | 4 цифры — установить/сменить PIN; пустая строка — снять PIN. |
{
"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
}Получить информацию о странице
Возвращает метаданные страницы: адрес, размер сайта, число файлов, entrypoint, срок жизни и PIN-защиту.
| Параметр | Описание |
|---|---|
| id | Идентификатор страницы. |
{
"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
}Удалить страницу
Безвозвратно удаляет страницу. Если к странице был привязан кастомный домен, домен остаётся в аккаунте — снимается только его связь с этой страницей.
| Параметр | Описание |
|---|---|
| id | Идентификатор страницы. |
{
"id": "abc123",
"deleted": true
}Коды ошибок
Тело ошибки всегда одинаковое: { "error": "<code>", "message": "<описание>" }.
| HTTP | error | Описание |
|---|---|---|
| 400 | invalid_file | Одиночный файл не похож на HTML или PDF. |
| 400 | invalid_site | Неверная комбинация источников или невалидный набор файлов сайта. |
| 400 | invalid_archive | ZIP повреждён, зашифрован или использует неподдерживаемый формат. |
| 400 | invalid_path | Недопустимый, небезопасный или дублирующийся путь файла. |
| 400 | missing_entry_file | В корне сайта отсутствует index.html. |
| 400 | too_many_files | В сайте больше 100 полезных файлов. |
| 400 | invalid_pin | PIN не из 4 цифр. |
| 400 | invalid_subdomain | Субдомен с недопустимыми символами (разрешены a-z, 0-9, «-»). |
| 401 | invalid_api_key | Невалидный или отсутствующий API-ключ. |
| 403 | api_not_allowed | Тариф без доступа к API (нужен Оптимальный или Бизнес). |
| 403 | page_limit_exceeded | Превышен лимит активных сайтов по тарифу. |
| 404 | not_found | Страница не найдена или принадлежит другому владельцу. |
| 409 | subdomain_taken | Запрошенный субдомен уже занят. |
| 413 | file_too_large | Суммарный распакованный размер сайта превышает лимит тарифа (до 50 МБ). |
| 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 и других языков одной командой из той же спецификации.
Публикация из AI-ассистентов (MCP)
Тот же API доступен через MCP-сервер https://htmlkin.ru/mcp — Claude и другие ассистенты публикуют и обновляют страницы прямо из диалога, по вашему API-ключу. Устанавливать и запускать ничего не нужно.