Documentation de l’API REST
Publiez et mettez à jour des pages HTML directement depuis votre code et vos pipelines d’IA. Publiez et mettez à jour des sites statiques et des pages HTML depuis votre code et vos pipelines d’IA. Disponible avec toutes les offres, y compris Gratuit, avec une clé API.
Authentification
Chaque requête nécessite une clé API dans l’en-tête Authorization. Créez la clé dans votre tableau de bord, sur la page « Clés API » — elle ne s’affiche qu’une seule fois. Une requête sans clé valide est refusée avec 401 invalid_api_key.
L’adresse de base de tous les endpoints est https://htmlkin.io/api/v1. Ajoutez cet en-tête à chaque requête :
"Authorization: Bearer <api_key>"L’API est disponible avec toutes les offres, y compris Gratuit. Créez une clé dans votre tableau de bord, sur la page « Clés API » — elle ne s’affiche qu’une seule fois.
Limites de requêtes
Le nombre de requêtes est limité selon l’offre, par compte : toutes ses clés partagent un compteur. Au-delà de la limite, vous recevez 429 rate_limit_exceeded avec un en-tête Retry-After.
| Offre | Limite |
|---|---|
| Gratuit | 10 requêtes par minute, jusqu’à 60 imports de site par heure avec le tableau de bord, une mise à jour par site et par minute |
| Pro | 60 requêtes par minute |
| Business | 120 requêtes par minute |
Endpoints
Publier une page
Importe un fichier HTML ou un ZIP de site statique et le publie sur son propre sous-domaine. Envoyez exactement un des champs html_file et site_archive. Un sous-domaine aléatoire est attribué par défaut ; indiquez le vôtre dans le champ subdomain.
multipart/form-data| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| html_file | file | non | Un fichier HTML unique, enregistré sous index.html. Exactement une source de contenu. |
| site_archive | file | non | Un ZIP de site statique : la page d’entrée est l’index.html à la racine ou le premier fichier HTML à la racine de l’archive. Le site décompressé doit faire au plus 200 Mo et tenir dans l’espace de stockage libre. |
| subdomain | string | non | Sous-domaine souhaité ({subdomain}.htmlkin.io), 3 à 63 caractères a-z, 0-9, « - » (pas aux extrémités). 409 s’il est déjà pris. |
| pin | string | non | Un code PIN à 4 chiffres (0000–9999) pour protéger l’affichage. Avec les offres payantes. |
| visibility | string | non | Qui peut ouvrir le site : public — tout le monde, les moteurs de recherche l’indexent ; link — toute personne ayant le lien, sans indexation ; team — les membres de l’équipe du compte après connexion, avec l’offre Business ; private — uniquement le propriétaire du compte après connexion. Par défaut : public. |
{
"id": "abc123",
"url": "https://mypage.htmlkin.io",
"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"
}Mettre à jour une page
Remplace tout le site par un nouveau HTML ou ZIP à la même adresse et/ou change le code PIN et la visibilité. L’URL de la page reste la même. Envoyez au plus un des champs html_file et site_archive ; vous pouvez n’envoyer que pin et/ou visibility pour modifier uniquement la protection ou la visibilité.
multipart/form-data| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| html_file | file | non | Un nouveau fichier HTML (facultatif ; pas en même temps que site_archive). |
| site_archive | file | non | Un nouveau ZIP complet du site ; tous les fichiers précédents sont remplacés. |
| pin | string | non | 4 chiffres définissent ou changent le code PIN ; une chaîne vide le supprime. |
| visibility | string | non | Qui peut ouvrir le site : public — tout le monde, les moteurs de recherche l’indexent ; link — toute personne ayant le lien, sans indexation ; team — les membres de l’équipe du compte après connexion, avec l’offre Business ; private — uniquement le propriétaire du compte après connexion. |
{
"id": "abc123",
"url": "https://mypage.htmlkin.io",
"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"
}Obtenir les détails d’une page
Renvoie les métadonnées de la page : adresse, taille du site, nombre de fichiers, point d’entrée, durée de vie, protection par code PIN et visibilité.
| Paramètre | Description |
|---|---|
| id | ID de la page. |
{
"id": "abc123",
"url": "https://mypage.htmlkin.io",
"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"
}Supprimer une page
Supprime la page définitivement. Si un domaine personnalisé était associé à la page, le domaine reste dans le compte — seul son lien avec cette page est supprimé.
| Paramètre | Description |
|---|---|
| id | ID de la page. |
{
"id": "abc123",
"deleted": true
}Codes d’erreur
Le corps de l’erreur a toujours la même forme : { "error": "<code>", "message": "<description>" }.
| HTTP | error | Description |
|---|---|---|
| 400 | invalid_file | Le fichier unique ne ressemble pas à du HTML. |
| 400 | invalid_site | Combinaison de sources non valide ou ensemble de fichiers du site non valide. |
| 400 | invalid_archive | Le ZIP est endommagé, chiffré ou utilise un format non pris en charge. |
| 400 | invalid_path | Chemin de fichier non valide, non sûr ou en double. |
| 400 | missing_entry_file | Il n’y a aucun fichier HTML à la racine du site. |
| 400 | too_many_files | Le site contient plus de 500 fichiers utiles. |
| 400 | banner_removal | Un fichier du site contient du code qui supprime le bandeau promotionnel htmlkin ; le bandeau disparaît avec une offre payante. |
| 400 | invalid_pin | Le code PIN ne comporte pas 4 chiffres. |
| 400 | invalid_visibility | visibility n’est pas l’une des valeurs public, link, team, private. |
| 400 | invalid_subdomain | Le sous-domaine contient des caractères non valides (autorisés : a-z, 0-9, « - »). |
| 401 | invalid_api_key | Clé API non valide ou manquante. |
| 403 | account_banned | Le compte a été bloqué pour violation des conditions d’utilisation. |
| 403 | team_visibility_requires_plan | Le mode team est disponible avec l’offre Business. |
| 403 | content_blocked | La page d’entrée (index.html) est identique, octet pour octet, à une page d’un site bloqué pour violation des conditions d’utilisation. |
| 403 | dangerous_link | La page contient un lien que Google Web Risk classe comme hameçonnage ou logiciel malveillant. |
| 403 | page_limit_exceeded | La limite de sites actifs de l’offre est atteinte. |
| 404 | not_found | La page est introuvable ou appartient à un autre propriétaire. |
| 409 | subdomain_taken | Le sous-domaine demandé est déjà pris. |
| 413 | file_too_large | Le site décompressé dépasse 200 Mo, la limite d’un seul import. |
| 413 | storage_limit_exceeded | Le site ne tient pas dans l’espace de stockage : avec les autres sites actifs du compte, il dépasserait le stockage de l’offre. Lors d’une mise à jour, l’espace de la version actuelle du site compte comme libre. |
| 429 | rate_limit_exceeded | Trop de requêtes ; la réponse contient un en-tête Retry-After. |
Tests et génération de clients
L’API est décrite par une spécification OpenAPI 3.1 lisible par les machines. Importez-la pour envoyer des requêtes de façon interactive et générer un client prêt à l’emploi pour votre langage :
- Swagger UI / Postman — collez
https://htmlkin.io/api/v1/openapi.json, renseignez la clé Bearer et appelez les endpoints directement depuis votre navigateur. - openapi-generator — générez un SDK pour Python, TypeScript, Go et d’autres langages en une seule commande à partir de la même spécification.
Publier depuis des assistants IA (MCP)
La même API est disponible via le serveur MCP https://htmlkin.io/mcp — Claude et d’autres assistants publient et mettent à jour des sites directement depuis la conversation, avec votre clé API. Rien à installer ni à lancer.