Documentazione REST API
Pubblica e aggiorna pagine HTML direttamente dal codice e dalle pipeline di IA. Pubblica e aggiorna siti statici e pagine HTML dal codice e dalle pipeline di IA. Disponibile su tutti i piani, compreso Free, con una chiave API.
Autenticazione
Ogni richiesta richiede una chiave API nell'intestazione Authorization. Crea la chiave nel tuo Pannello, nella pagina “Chiavi API” — viene mostrata una sola volta. Una richiesta senza una chiave valida viene rifiutata con 401 invalid_api_key.
L’indirizzo base di tutti gli endpoint è https://htmlkin.io/api/v1. Aggiungi questa intestazione a ogni richiesta:
"Authorization: Bearer <api_key>"L’API è disponibile su tutti i piani, compreso Free. Crea una chiave nel tuo Pannello, nella pagina “Chiavi API” — viene mostrata una sola volta.
Limiti di richieste
La frequenza delle richieste è limitata in base al piano, per account: tutte le sue chiavi condividono un contatore. Oltre il limite ricevi 429 rate_limit_exceeded con l’intestazione Retry-After.
| Piano | Limite |
|---|---|
| Free | 10 richieste al minuto, fino a 60 caricamenti di siti all'ora insieme al Pannello, un aggiornamento per sito al minuto |
| Pro | 60 richieste al minuto |
| Business | 120 richieste al minuto |
Endpoint
Pubblica una pagina
Carica un file HTML o uno ZIP di un sito statico e lo pubblica sul proprio sottodominio. Invia esattamente uno dei campi html_file e site_archive. Per impostazione predefinita viene assegnato un sottodominio casuale; imposta il tuo nel campo subdomain.
multipart/form-data| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| html_file | file | no | Un singolo file HTML, salvato come index.html. Esattamente una fonte di contenuto. |
| site_archive | file | no | Uno ZIP di un sito statico: la pagina di ingresso è l'index.html nella radice o il primo file HTML nella radice dell'archivio. Il sito decompresso deve essere al massimo di 200 MB e rientrare nello spazio di archiviazione libero. |
| subdomain | string | no | Sottodominio desiderato ({subdomain}.htmlkin.io), 3–63 caratteri a-z, 0-9, “-” (non alle estremità). 409 se è già occupato. |
| pin | string | no | Un PIN di 4 cifre (0000–9999) per proteggere la visualizzazione. Sui piani a pagamento. |
| visibility | string | no | Chi può aprire il sito: public — chiunque, i motori di ricerca lo indicizzano; link — chiunque abbia il link, senza indicizzazione; team — i membri del team dell'account dopo l'accesso, con il piano Business; private — solo il proprietario dell'account dopo l'accesso. Il valore predefinito è 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"
}Aggiorna una pagina
Sostituisce l'intero sito con un nuovo HTML o ZIP allo stesso indirizzo e/o cambia il PIN e la visibilità. L'URL della pagina resta lo stesso. Invia al massimo uno dei campi html_file e site_archive; puoi inviare solo pin e/o visibility per cambiare soltanto la protezione o la visibilità.
multipart/form-data| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| html_file | file | no | Un nuovo file HTML (facoltativo; non insieme a site_archive). |
| site_archive | file | no | Un nuovo ZIP completo del sito; tutti i file precedenti vengono sostituiti. |
| pin | string | no | 4 cifre impostano o cambiano il PIN; una stringa vuota lo rimuove. |
| visibility | string | no | Chi può aprire il sito: public — chiunque, i motori di ricerca lo indicizzano; link — chiunque abbia il link, senza indicizzazione; team — i membri del team dell'account dopo l'accesso, con il piano Business; private — solo il proprietario dell'account dopo l'accesso. |
{
"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"
}Ottieni i dettagli della pagina
Restituisce i metadati della pagina: indirizzo, dimensione del sito, numero di file, punto di ingresso, durata, protezione con PIN e visibilità.
| Parametro | Descrizione |
|---|---|
| id | ID della pagina. |
{
"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"
}Elimina una pagina
Elimina la pagina definitivamente. Se alla pagina era collegato un dominio personalizzato, il dominio resta nell'account — viene rimosso solo il suo collegamento a questa pagina.
| Parametro | Descrizione |
|---|---|
| id | ID della pagina. |
{
"id": "abc123",
"deleted": true
}Codici di errore
Il corpo dell’errore è sempre lo stesso: { "error": "<code>", "message": "<description>" }.
| HTTP | error | Descrizione |
|---|---|---|
| 400 | invalid_file | Il file singolo non sembra HTML. |
| 400 | invalid_site | Combinazione di fonti non valida o insieme di file del sito non valido. |
| 400 | invalid_archive | Lo ZIP è danneggiato, cifrato o usa un formato non supportato. |
| 400 | invalid_path | Percorso del file non valido, non sicuro o duplicato. |
| 400 | missing_entry_file | Nella radice del sito non c'è alcun file HTML. |
| 400 | too_many_files | Il sito contiene più di 500 file utili. |
| 400 | banner_removal | Un file del sito contiene codice che rimuove la barra promozionale di htmlkin; la barra scompare con un piano a pagamento. |
| 400 | invalid_pin | Il PIN non è di 4 cifre. |
| 400 | invalid_visibility | visibility non è uno tra public, link, team, private. |
| 400 | invalid_subdomain | Il sottodominio contiene caratteri non validi (ammessi: a-z, 0-9, “-”). |
| 401 | invalid_api_key | Chiave API non valida o mancante. |
| 403 | account_banned | L'account è stato bloccato per violazione dei Termini di servizio. |
| 403 | team_visibility_requires_plan | La modalità team è disponibile con il piano Business. |
| 403 | content_blocked | La pagina di ingresso (index.html) è identica, byte per byte, a una pagina di un sito bloccato per violazione dei Termini di servizio. |
| 403 | dangerous_link | La pagina contiene un link che Google Web Risk classifica come phishing o malware. |
| 403 | page_limit_exceeded | È stato raggiunto il limite di siti attivi del piano. |
| 404 | not_found | La pagina non è stata trovata o appartiene a un altro proprietario. |
| 409 | subdomain_taken | Il sottodominio richiesto è già occupato. |
| 413 | file_too_large | Il sito decompresso supera 200 MB, il limite di un singolo caricamento. |
| 413 | storage_limit_exceeded | Il sito non entra nello spazio di archiviazione: insieme agli altri siti attivi dell'account supererebbe lo spazio del piano. In caso di aggiornamento, lo spazio della versione attuale del sito conta come libero. |
| 429 | rate_limit_exceeded | Troppe richieste; la risposta contiene l'intestazione Retry-After. |
Test e generazione dei client
L’API è descritta da una specifica OpenAPI 3.1 leggibile dalle macchine. Importala per inviare richieste in modo interattivo e generare un client pronto per il tuo linguaggio:
- Swagger UI / Postman — incolla
https://htmlkin.io/api/v1/openapi.json, imposta la chiave Bearer e chiama gli endpoint direttamente dal browser. - openapi-generator — genera un SDK per Python, TypeScript, Go e altri linguaggi con un solo comando a partire dalla stessa specifica.
Pubblicazione dagli assistenti IA (MCP)
La stessa API è disponibile tramite il server MCP https://htmlkin.io/mcp — Claude e altri assistenti pubblicano e aggiornano siti direttamente dalla chat, con la tua chiave API. Niente da installare o avviare.