API REST

Documentação da API

Encurte e gerencie links a partir dos seus sistemas. Base: https://kurto.me/api?action=<ação>. Respostas em JSON; erros no formato {"error": "descrição"}.

Autenticação

Toda requisição leva o cabeçalho X-API-Token com o seu token, que fica em Perfil e API.

X-API-Token: SEU_TOKEN

Somente pelo cabeçalho: ?token= na URL foi removido porque gravava a credencial nos logs. A conta precisa estar verificada e com a API liberada (individualmente ou para todos). API para todos neste momento: habilitada.

Multi-domínio

O slug é único e global: responde em todos os domínios ativos. O campo domain escolhe só qual endereço volta em short_url. Domínios ativos: kurto.me (padrão).

POST /api?action=shorten

Cria um link. url é obrigatória (com http:// ou https://). slug é opcional (3 a 64 caracteres: letras, números, - e _); sem ele, o sistema gera um número de 6 dígitos. domain é opcional.

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

Resposta 201

{ "slug": "meu-link", "short_url": "https://kurto.me/meu-link" }

Erro 422

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

GET /api?action=list

Lista os seus links, do mais novo para o mais antigo. Admin pode usar &all=1 para ver todos. Opcional: &ids=12,18,19 (até 500) devolve só esses, no mesmo escopo — ids de outro usuário são omitidos.

curl -H "X-API-Token: SEU_TOKEN" "https://kurto.me/api?action=list"

Resposta 200

{ "links": [ { "id": 123, "slug": "abc123", "original_url": "https://exemplo.com", "short_url": "https://kurto.me/abc123", "is_custom": false, "domain": null, "clicks": 42, "expires_at": null, "has_password": false, "qr_code": "https://kurto.me/qr/abc123.png", "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 do acesso.
expires_at: data de expiração ou null. Depois dela o link responde 410.
has_password: o visitante digita a senha antes do redirect.
qr_code: imagem PNG do QR, gerada aqui. Aceita ?size=120 a 1000.

PUT /api?action=update

Altera um link (PUT ou POST). id e url são obrigatórios; slug é opcional. Para domain: omitir mantém o atual, null volta ao domínio do acesso.

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

Resposta 200

{ "slug": "novo-slug", "short_url": "https://kurto.me/novo-slug" }

DELETE /api?action=delete&id=123

Remove um link (DELETE ou POST).

curl -X DELETE -H "X-API-Token: SEU_TOKEN" "https://kurto.me/api?action=delete&id=123"

Resposta 200

{"status": "ok"}

GET /api?action=domains

Domínios ativos, para usar no campo domain sem errar o hostname.

curl -H "X-API-Token: SEU_TOKEN" "https://kurto.me/api?action=domains"

Resposta 200

{ "domains": [ {"hostname": "kurto.me", "scheme": "https", "is_default": true} ] }

Regras e permissões

Usuário comum só edita e apaga os próprios links personalizados.
Links automáticos (slug numérico) só são apagados por administradores.
Administradores podem listar, editar e apagar qualquer link.
O slug não diferencia maiúsculas: Promo e promo são o mesmo link.
O redirect é 302 de propósito: trocar o destino vale na hora, sem cache do navegador.
Destino aceito: só http:// e https://, até 2000 caracteres. Endereços internos (localhost, 10.x, 192.168.x, 169.254.x) são recusados.

Códigos de resposta

Código	Quando acontece
200	Requisição bem-sucedida.
201	Link criado (shorten).
400	A action da URL não existe.
401	Token ausente ou inválido, usuário não verificado ou API desabilitada.
403	O link é de outro usuário, ou é automático e você não é admin.
404	O id informado não existe.
405	Método errado: update exige PUT ou POST; delete exige DELETE ou POST.
422	URL malformada, slug em uso ou fora do padrão, domínio não cadastrado, ou destino interno.
429	Limite de uso atingido. Veja o cabeçalho Retry-After.

Limites de uso

Requisições autenticadas: 60 por minuto.
Escrita (criar, editar, apagar): 20 por minuto, dentro do total.
Sem token válido: 10 por minuto por IP.

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.

Para agentes de IA

A mesma documentação em texto puro, para assistentes e agentes lerem direto: /llms.txt. Inclui endpoints, campos, códigos de erro e as armadilhas comuns numa primeira integração.