Documentação da API

A API REST do HTMLy permite criar, consultar, atualizar e excluir seus sites por código. Serve para scripts, automações e integrações com ferramentas de IA.

Autenticação

Todas as requisições à API devem incluir sua API key no header Authorization como Bearer token.

Você encontra sua API key na página de Perfil do painel (/profile).

curl -H "Authorization: Bearer SUA_API_KEY" \
  https://htmly.com.br/api/v1/sites

Endpoints

Método	Endpoint	Descrição
POST	`/api/v1/sites`	Criar um site com uma página HTML
GET	`/api/v1/sites`	Listar seus sites
GET	`/api/v1/sites/{slug}`	Obter os detalhes de um site
PATCH	`/api/v1/sites/{slug}`	Atualizar as configurações de um site (título, meta tags, indexação, selo)
PUT	`/api/v1/sites/{slug}/content`	Substituir o site inteiro por uma nova página HTML
DELETE	`/api/v1/sites/{slug}`	Excluir um site

Uma página por chamada

A API v1 publica um HTML por vez, e ele vira o index.html do site. Ela não extrai ZIP nem recebe CSS, imagens ou outras páginas junto. Para um site com vários arquivos, publique pelo painel ou pelo servidor MCP, que envia vários arquivos na mesma chamada e, ao atualizar, só troca os arquivos enviados.

Exemplos

Listar sites

curl -X GET https://htmly.com.br/api/v1/sites \
  -H "Authorization: Bearer SUA_API_KEY"

# Response 200
{
  "data": [
    {
      "slug": "meu-portfolio",
      "title": "Meu Portfolio",
      "status": "active",
      "total_views": 1234,
      "storage_bytes": 524288,
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Criar site (arquivo HTML)

O HTML vai no campo file (arquivo .html ou .htm) ou, como texto, no campo content. Os campos slug e title são opcionais; sem slug, o HTMLy gera um.

curl -X POST https://htmly.com.br/api/v1/sites \
  -H "Authorization: Bearer SUA_API_KEY" \
  -F "[email protected]" \
  -F "slug=meu-portfolio" \
  -F "title=Meu Portfolio"

# Response 201
{
  "data": {
    "slug": "meu-portfolio",
    "url": "https://meu-portfolio.htmly.com.br",
    "title": "Meu Portfolio",
    "status": "active",
    "created_at": "2026-03-15T14:30:00Z"
  },
  "meta": {
    "plan": "starter",
    "sites_remaining": 4
  }
}

Obter detalhes do site

curl -X GET https://htmly.com.br/api/v1/sites/meu-portfolio \
  -H "Authorization: Bearer SUA_API_KEY"

# Response 200
{
  "data": {
    "slug": "meu-portfolio",
    "title": "Meu Portfolio",
    "url": "https://meu-portfolio.htmly.com.br",
    "status": "active",
    "total_views": 1234,
    "storage_bytes": 524288,
    "meta_title": "Meu Portfolio",
    "meta_description": "Portfolio pessoal",
    "is_indexable": true,
    "show_badge": true,
    "created_at": "2026-03-01T10:00:00Z",
    "updated_at": "2026-03-10T08:15:00Z"
  }
}

Atualizar as configurações do site

curl -X PATCH https://htmly.com.br/api/v1/sites/meu-portfolio \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Novo Titulo", "meta_description": "Nova descricao"}'

# Response 200
{
  "data": {
    "slug": "meu-portfolio",
    "title": "Novo Titulo",
    "meta_description": "Nova descricao"
  }
}

Substituir o conteúdo do site

Apaga todos os arquivos atuais do site e grava só o HTML enviado, como index.html. CSS, imagens e outras páginas que estavam no site deixam de existir. Para trocar só alguns arquivos, use o editor do painel ou o servidor MCP. No Free, cada substituição conta no limite de 3 atualizações por dia.

Para enviar arquivo, use POST com o campo _method=PUT: o PHP não lê arquivo enviado numa requisição PUT. Com o HTML como texto, o PUT com corpo JSON funciona direto.

# Arquivo HTML
curl -X POST https://htmly.com.br/api/v1/sites/meu-portfolio/content \
  -H "Authorization: Bearer SUA_API_KEY" \
  -F "_method=PUT" \
  -F "[email protected]"

# HTML como texto
curl -X PUT https://htmly.com.br/api/v1/sites/meu-portfolio/content \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "<!doctype html><html><body><h1>Nova versão</h1></body></html>"}'

# Response 200
{
  "data": {
    "slug": "meu-portfolio",
    "url": "https://meu-portfolio.htmly.com.br",
    "storage_bytes": 18432,
    "status": "active",
    "updated_at": "2026-03-16T09:00:00Z"
  }
}

Excluir site

curl -X DELETE https://htmly.com.br/api/v1/sites/meu-portfolio \
  -H "Authorization: Bearer SUA_API_KEY"

# Response 204 (No Content)

Rate Limits

Os limites de requisições variam conforme o plano. Ao exceder o limite, a API retorna 429 Too Many Requests.

Plano	Limite
Free	30 requisições/min
Starter	45 requisições/min
Pro	60 requisições/min
Agency	120 requisições/min

Códigos de resposta

Código	Significado
`200`	Sucesso
`201`	Site criado
`204`	Site excluído (resposta sem corpo)
`401`	Não autenticado: API key ausente ou inválida
`403`	Sem permissão: o site não existe na sua conta, o plano não inclui o recurso, o limite de sites do plano foi atingido ou o site está suspenso e não aceita exclusão nem troca de conteúdo
`404`	Endpoint não encontrado
`413`	Requisição grande demais para o servidor receber
`422`	Erro de validação: campo inválido, slug reservado ou em uso, tipo de arquivo não aceito, HTML com código PHP ou arquivo acima do storage do plano
`429`	Limite de requisições do plano ou, no Free, limite de atualizações do dia (o campo retry_after diz em quantos segundos tentar de novo)
`500`	Erro interno do servidor

URL Base

Todas as requisições devem ser feitas para https://htmly.com.br/api/v1. Todas as respostas são em formato JSON.