Links pela API

POST /api/links gera um link. Para um link de URL simples, o único campo obrigatório é default_target, uma URL http(s). Você também pode passar um slug próprio (3–32 caracteres base62), um name legível (até 80), um group_id, um carimbo de tempo expires_at em milissegundos de época e um placement de active (padrão) ou archived.

curl https://qr2r.com/api/links \
  -H "Authorization: Bearer $KILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "default_target": "https://example.com/landing", "name": "Spring flyer" }'

Uma criação bem-sucedida retorna 201 com o objeto de link completo. O slug é a alça pública permanente; default_target é o destino editável por trás:

{
  "id": 8231,
  "slug": "aA3k9",
  "name": "Spring flyer",
  "kind": "url",
  "data": null,
  "default_target": "https://example.com/landing",
  "expires_at": null,
  "disabled": false,
  "override_target": null,
  "expired_fallback_url": null,
  "group_id": null,
  "domain": null,
  "rule_count": 0,
  "created_at": 1719000000000,
  "updated_at": 1719000000000,
  "deleted_at": null,
  "reclaim_until": null,
  "paused_at": null,
  "pause_reason": null,
  "placement_country": null,
  "placement_region": null
}

GET /api/links retorna seus links página por página. Restrinja com status (active, archived, paused ou deleted - padrão active), group_id e o par limit/offset (limit padrão 50, teto 200). A resposta carrega a página mais contadores de toda a conta:

{
  "links": [ /* link objects, newest first */ ],
  "limit": 50,
  "offset": 0,
  "status": "active",
  "counts": { "active": 12, "archived": 3, "paused": 0, "deleted": 1 },
  "limits": { "active_links_max": 25, "archived_links_max": 100, "reclaim_window_days": 30 }
}

Leia um único link por slug com GET /api/links/:slug; ele retorna o mesmo formato de objeto da criação. Um slug desconhecido retorna 404 not_found. Para um link em um dos seus domínios próprios, acrescente ?domain=go.acme.com para o link certo resolver.

PUT /api/links/:slug recebe um corpo parcial - envie só os campos que você está mudando. O comum é default_target; você também pode mudar o name, movê-lo para um group_id, definir expires_at ou arquivá-lo com disabled. Editar o destino tem efeito no próximo escaneamento, em todo lugar de uma vez - que é todo o sentido de rotear um código impresso pela Kilo.

curl -X PUT https://qr2r.com/api/links/aA3k9 \
  -H "Authorization: Bearer $KILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "default_target": "https://example.com/new-landing" }'

A chamada retorna o objeto de link atualizado, com um updated_at novo.

DELETE /api/links/:slug exclui um link de forma reversível: ele para de encaminhar e vai para a aba Excluídos, mas não sumiu.

{ "ok": true, "soft": true }

Você pode trazê-lo de volta com POST /api/links/:slug/reclaim enquanto ele está dentro da janela de recuperação, ou removê-lo de vez com POST /api/links/:slug/purge. Nada é jamais apagado em definitivo por baixo dos seus panos por um simples delete - o mesmo princípio de nunca-um-beco-sem-saída que o guia do ciclo de vida do link descreve, expresso como endpoints.

Esse é o objeto completo por HTTP. O último guia da API cobre as duas coisas que você mais vai automatizar em torno de um link: ler suas estatísticas e dirigir seu tráfego.