API Reference

A API REST do Htmly permite criar, gerenciar e monitorar seus sites programaticamente. Ideal para integracoes com ferramentas de IA e automacoes.

Autenticacao

Todas as requisicoes a API devem incluir sua API key no header Authorization como Bearer token.

Voce pode encontrar sua API key na pagina de Perfil do dashboard (/profile).

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

Endpoints

Metodo	Endpoint	Descricao
POST	`/api/v1/sites`	Criar um novo site (upload de arquivo ZIP ou HTML)
GET	`/api/v1/sites`	Listar todos os seus sites
GET	`/api/v1/sites/{slug}`	Obter detalhes de um site
PATCH	`/api/v1/sites/{slug}`	Atualizar configuracoes de um site
DELETE	`/api/v1/sites/{slug}`	Excluir um site
GET	`/api/v1/sites/{slug}/analytics`	Obter analytics de um site
GET	`/api/v1/user`	Obter dados do usuario autenticado

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 (upload ZIP)

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",
    "title": "Meu Portfolio",
    "url": "https://meu-portfolio.htmly.com.br",
    "status": "active",
    "created_at": "2026-03-15T14:30:00Z"
  }
}

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

Excluir site

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

# Response 204 (No Content)

Obter analytics

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

# Response 200
{
  "data": {
    "total_views": 1234,
    "views_by_date": [
      { "date": "2026-03-14", "views": 42 },
      { "date": "2026-03-15", "views": 58 }
    ],
    "top_referrers": [
      { "referrer": "google.com", "views": 320 },
      { "referrer": "twitter.com", "views": 156 }
    ],
    "top_countries": [
      { "country": "BR", "views": 890 },
      { "country": "US", "views": 210 }
    ]
  }
}

Rate Limits

Os limites de requisicoes variam conforme o plano. Ao exceder o limite, a API retorna 429 Too Many Requests.

Plano	Limite
Free	30 requisicoes/min
Starter	45 requisicoes/min
Pro	60 requisicoes/min
Agency	120 requisicoes/min

Codigos de Erro

Codigo	Significado
`200`	Sucesso
`201`	Recurso criado com sucesso
`400`	Requisicao invalida — verifique os parametros enviados
`401`	Nao autenticado — API key ausente ou invalida
`403`	Proibido — sem permissao para este recurso
`404`	Recurso nao encontrado
`409`	Conflito — slug ja em uso
`413`	Arquivo muito grande — excede o limite do plano
`422`	Erro de validacao — campos invalidos
`429`	Rate limit excedido — aguarde antes de tentar novamente
`500`	Erro interno do servidor

URL Base

Todas as requisicoes devem ser feitas para https://htmly.com.br/api/v1. Todas as respostas sao em formato JSON.