Documentação da API

API REST completa para encurtamento e gerenciamento de links. Autenticação via token, suporte a slugs personalizados e operações CRUD.

Autenticação

Todas as requisições devem incluir o header X-API-Token com seu token pessoal.

Exemplo:

X-API-Token: seu_token_aqui

Tokens são gerados automaticamente no seu perfil. A API precisa estar habilitada globalmente ou para seu usuário.

POST

Criar Link


                    https://l4y.ovh/api?action=shorten

Exemplo de Requisição:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Token: SEU_TOKEN_AQUI" \
  -d '{"url":"https://exemplo.com","slug":"meu-link"}' \
  https://l4y.ovh/api?action=shorten

Escolhendo o domínio (opcional):

O campo domain define qual endereço volta em short_url. O slug responde em todos os domínios de qualquer forma. Sem o campo, usa o domínio padrão.

-d '{"url":"https://exemplo.com","slug":"meu-link","domain":"notipay.net"}'

Domínios disponíveis via GET /api?action=domains: l4y.ovh, abre.ovh, notipay.net.

Resposta (201):

{
  "slug": "meu-link",
  "short_url": "https://l4y.ovh/meu-link"
}

Erro (422):

{"error": "Slug já em uso"}

GET

Listar Links


                    https://l4y.ovh/api?action=list

Exemplo de Requisição:

curl -H "X-API-Token: SEU_TOKEN_AQUI" \
  https://l4y.ovh/api?action=list

Resposta (200):

{
  "links": [
    {
      "id": 123,
      "slug": "abc123",
      "original_url": "https://exemplo.com",
      "short_url": "https://l4y.ovh/abc123",
      "is_custom": false,
      "domain": null,
      "clicks": 42,
      "expires_at": null,
      "has_password": false,
      "qr_code": "https://api.qrserver.com/v1/create-qr-code/?size=240x240&data=...",
      "user_id": 1,
      "created_at": "2026-09-16 12:00:00",
      "updated_at": "2026-09-16 12:00:00"
    }
  ]
}

domain — domínio exibido no short_url. null = usa o domínio pelo qual você acessou.

clicks — total de acessos ao link.

expires_at — data de expiração, ou null. Depois dela o link responde 410.

has_password — se true, o visitante precisa digitar a senha antes do redirect.

qr_code — URL da imagem do QR code do link.

Admin: Use ?all=1 para listar todos os links do sistema.

PUT

Atualizar Link


                    https://l4y.ovh/api?action=update

Exemplo de Requisição:

curl -X PUT \
  -H "Content-Type: application/json" \
  -H "X-API-Token: SEU_TOKEN_AQUI" \
  -d '{"id":123,"url":"https://novo.com","slug":"novo-slug"}' \
  https://l4y.ovh/api?action=update

Resposta (200):

{
  "slug": "novo-slug",
  "short_url": "https://l4y.ovh/novo-slug"
}

Aceita domain para trocar o domínio exibido. Enviar "domain": null volta ao domínio da requisição; omitir o campo mantém o que já estava.

DELETE

Deletar Link


                    https://l4y.ovh/api?action=delete&id=123

Exemplo de Requisição:

curl -X DELETE \
  -H "X-API-Token: SEU_TOKEN_AQUI" \
  "https://l4y.ovh/api?action=delete&id=123"

Resposta (200):

{"status": "ok"}

GET

Listar Domínios


                    https://l4y.ovh/api?action=domains

Domínios ativos que podem ser usados no campo domain de shorten e update. Um slug responde em todos eles — o domínio escolhido define apenas o endereço devolvido em short_url.

Exemplo de Requisição:

curl -H "X-API-Token: SEU_TOKEN_AQUI" \
  https://l4y.ovh/api?action=domains

Resposta (200):

{
  "domains": [
    {"hostname": "l4y.ovh", "scheme": "https", "is_default": true},
    {"hostname": "abre.ovh", "scheme": "https", "is_default": false},
    {"hostname": "notipay.net", "scheme": "https", "is_default": false}
  ]
}

Regras e Permissões

Seu usuário deve estar verificado e com API habilitada (ou API global ativa).
Usuários só podem editar/deletar seus próprios links personalizados.
Links automáticos (numéricos) só podem ser deletados por administradores.
Administradores têm acesso total: podem listar, editar e deletar qualquer link.

Códigos de resposta

Código	Significado	Quando acontece
200	OK	Requisição bem-sucedida.
201	Criado	Link criado com sucesso (`shorten`).
400	Ação inválida	O `action` da URL não existe.
401	Não autorizado	Token ausente, inválido, usuário não verificado ou API desabilitada.
403	Sem permissão	O link é de outro usuário, ou é automático e você não é admin.
404	Não encontrado	O `id` informado não existe.
405	Método errado	`update` exige PUT ou POST; `delete` exige DELETE ou POST.
422	Dados inválidos	URL malformada, slug já em uso, slug fora do padrão, domínio não cadastrado, ou destino interno/não-http.
429	Limite excedido	Rate limit atingido. Veja o header `Retry-After` antes de tentar de novo.

Todo erro devolve JSON no formato {"error": "descrição"}.

Limites de uso

Situação	Limite
Requisições autenticadas	60 por minuto
Escrita (criar, editar, apagar)	20 por minuto
Sem token válido (por IP)	10 por minuto

Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining. Ao estourar, a API devolve 429 com Retry-After em segundos — espere esse tempo em vez de repetir a chamada imediatamente.

Leitura e escrita contam separado: atingir o limite de criação não impede de continuar consultando os links.

Para agentes de IA

Esta mesma documentação está disponível em texto puro, num formato que assistentes de IA e agentes automatizados conseguem ler diretamente, sem precisar interpretar HTML.

https://l4y.ovh/llms.txt

Inclui os endpoints, os campos de cada resposta, os códigos de erro e as regras que costumam passar despercebidas numa primeira integração.

Comece a usar a API agora!

Seu token está disponível na página de perfil.

Acessar Meu Perfil