Para desenvolvedores

Documentação da REST API

Publique e atualize páginas HTML direto do código e de pipelines de IA. Publique e atualize sites estáticos e páginas HTML a partir do código e de pipelines de IA. Disponível em todos os planos, inclusive o Grátis, com uma chave de API.

Criar uma chave de API →Baixar OpenAPI

Autenticação

Toda requisição precisa de uma chave de API no cabeçalho Authorization. Crie a chave no seu Painel, na página “Chaves de API” — ela é exibida só uma vez. Uma requisição sem chave válida é recusada com 401 invalid_api_key.

O endereço base de todos os endpoints é https://htmlkin.io/api/v1. Adicione este cabeçalho a cada requisição:

"Authorization: Bearer <api_key>"

A API está disponível em todos os planos, inclusive o Grátis. Crie uma chave no seu Painel, na página “Chaves de API” — ela é exibida só uma vez.

Limites de requisições

A frequência de requisições é limitada conforme o plano, por conta: todas as chaves dela compartilham um contador. Acima do limite, você recebe 429 rate_limit_exceeded com o cabeçalho Retry-After.

Plano	Limite
Grátis	10 requisições por minuto, até 60 envios de site por hora somados ao Painel, uma atualização por site a cada minuto
Pro	60 requisições por minuto
Business	120 requisições por minuto

Endpoints

POST/api/v1/pages

Publicar uma página

Envia um arquivo HTML ou um ZIP de site estático e o publica no seu próprio subdomínio. Envie exatamente um dos campos html_file e site_archive. Por padrão é atribuído um subdomínio aleatório; defina o seu no campo subdomain.

Corpo da requisição multipart/form-data

Campo	Tipo	Obrigatório	Descrição
html_file	file	não	Um único arquivo HTML, salvo como index.html. Exatamente uma fonte de conteúdo.
site_archive	file	não	Um ZIP de site estático: a página de entrada é o index.html da raiz ou o primeiro arquivo HTML na raiz do arquivo. O site descompactado deve ter até 200 MB e caber no espaço livre de armazenamento.
subdomain	string	não	Subdomínio desejado ({subdomain}.htmlkin.io), 3–63 caracteres a-z, 0-9, “-” (não nas pontas). 409 se já estiver em uso.
pin	string	não	Um PIN de 4 dígitos (0000–9999) para proteger a visualização. Nos planos pagos.
visibility	string	não	Quem pode abrir o site: public — qualquer pessoa, os buscadores o indexam; link — qualquer pessoa com o link, sem indexação; team — os membros da equipe da conta, depois de entrar, no plano Business; private — só o dono da conta, depois de entrar. O padrão é public.

Exemplo de requisição

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

Resposta 201

{
  "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"
}

PUT/api/v1/pages/{id}

Atualizar uma página

Substitui o site inteiro por um novo HTML ou ZIP no mesmo endereço e/ou altera o PIN e a visibilidade. A URL da página não muda. Envie no máximo um dos campos html_file e site_archive; você pode enviar só pin e/ou visibility para alterar apenas a proteção ou a visibilidade.

Corpo da requisição multipart/form-data

Campo	Tipo	Obrigatório	Descrição
html_file	file	não	Um novo arquivo HTML (opcional; não junto com site_archive).
site_archive	file	não	Um novo ZIP completo do site; todos os arquivos anteriores são substituídos.
pin	string	não	4 dígitos definem ou alteram o PIN; uma string vazia o remove.
visibility	string	não	Quem pode abrir o site: public — qualquer pessoa, os buscadores o indexam; link — qualquer pessoa com o link, sem indexação; team — os membros da equipe da conta, depois de entrar, no plano Business; private — só o dono da conta, depois de entrar.

Exemplo de requisição

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

Resposta 200

{
  "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"
}

GET/api/v1/pages/{id}

Obter detalhes da página

Retorna os metadados da página: endereço, tamanho do site, número de arquivos, ponto de entrada, prazo de validade, proteção por PIN e visibilidade.

Parâmetros de caminho

Parâmetro	Descrição
id	ID da página.

Exemplo de requisição

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

Resposta 200

{
  "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"
}

DELETE/api/v1/pages/{id}

Excluir uma página

Exclui a página permanentemente. Se um domínio próprio estava vinculado à página, o domínio continua na conta — só o vínculo dele com esta página é removido.

Parâmetros de caminho

Parâmetro	Descrição
id	ID da página.

Exemplo de requisição

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

Resposta 200

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

Códigos de erro

O corpo do erro é sempre o mesmo: { "error": "<code>", "message": "<description>" }.

HTTP	error	Descrição
400	invalid_file	O arquivo único não parece ser HTML.
400	invalid_site	Combinação de fontes inválida ou conjunto de arquivos do site inválido.
400	invalid_archive	O ZIP está corrompido, criptografado ou usa um formato não suportado.
400	invalid_path	Caminho de arquivo inválido, inseguro ou duplicado.
400	missing_entry_file	Não há arquivo HTML na raiz do site.
400	too_many_files	O site tem mais de 500 arquivos úteis.
400	banner_removal	Um arquivo do site contém código que remove a barra promocional do htmlkin; a barra sai nos planos pagos.
400	invalid_pin	O PIN não tem 4 dígitos.
400	invalid_visibility	visibility não é public, link, team nem private.
400	invalid_subdomain	O subdomínio tem caracteres inválidos (permitidos: a-z, 0-9, “-”).
401	invalid_api_key	Chave de API inválida ou ausente.
403	account_banned	A conta foi bloqueada por violar os Termos de Uso.
403	team_visibility_requires_plan	O modo team está disponível no plano Business.
403	content_blocked	A página de entrada (index.html) é idêntica, byte a byte, a uma página de um site bloqueado por violar os Termos de Uso.
403	dangerous_link	A página tem um link que o Google Web Risk classifica como phishing ou malware.
403	page_limit_exceeded	O limite de sites ativos do plano foi atingido.
404	not_found	A página não foi encontrada ou pertence a outro dono.
409	subdomain_taken	O subdomínio solicitado já está em uso.
413	file_too_large	O site descompactado tem mais de 200 MB, o limite de um único envio.
413	storage_limit_exceeded	O site não cabe no armazenamento: junto com os outros sites ativos da conta, ele ultrapassaria o armazenamento do plano. Na atualização, o espaço da versão atual do site conta como livre.
429	rate_limit_exceeded	Requisições demais; a resposta traz o cabeçalho Retry-After.

Testes e geração de clientes

A API é descrita por uma especificação OpenAPI 3.1 legível por máquina. Importe-a para enviar requisições de forma interativa e gerar um cliente pronto para a sua linguagem:

Swagger UI / Postman — cole https://htmlkin.io/api/v1/openapi.json, defina a chave Bearer e chame os endpoints direto do navegador.
openapi-generator — gere um SDK para Python, TypeScript, Go e outras linguagens com um único comando a partir da mesma especificação.

Publicação a partir de assistentes de IA (MCP)

A mesma API está disponível pelo servidor MCP https://htmlkin.io/mcp — o Claude e outros assistentes publicam e atualizam sites direto no chat, com a sua chave de API. Nada para instalar ou executar.

Configurar o servidor MCP →