Les liens via l’API

POST /api/links génère un lien. Pour un lien URL simple, le seul champ obligatoire est default_target, une URL http(s). Vous pouvez aussi passer un slug personnalisé (3–32 caractères base62), un name humain (jusqu’à 80), un group_id, un horodatage expires_at en millisecondes d’époque et un placement de active (par défaut) 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" }'

Une création réussie renvoie 201 avec l’objet lien complet. Le slug est la poignée publique permanente ; default_target est la destination modifiable derrière :

{
  "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 renvoie vos liens page par page. Restreignez-le avec status (active, archived, paused ou deleted - par défaut active), group_id et le couple limit/offset (limit par défaut 50, plafonné à 200). La réponse porte la page plus des compteurs à l’échelle du compte :

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

Lisez un seul lien par slug avec GET /api/links/:slug ; il renvoie la même forme d’objet que la création. Un slug inconnu renvoie 404 not_found. Pour un lien sur l’un de vos domaines personnalisés, ajoutez ?domain=go.acme.com pour que le bon lien se résolve.

PUT /api/links/:slug prend un corps partiel - envoyez seulement les champs que vous changez. Le courant est default_target ; vous pouvez aussi changer le name, le déplacer vers un group_id, régler expires_at ou l’archiver avec disabled. Modifier la destination prend effet dès le scan suivant, partout d’un coup - ce qui est tout l’intérêt de router un code imprimé via 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" }'

L’appel renvoie l’objet lien mis à jour, avec un updated_at frais.

DELETE /api/links/:slug supprime un lien en douceur : il cesse de renvoyer et passe dans l’onglet Supprimés, mais il n’a pas disparu.

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

Vous pouvez le récupérer avec POST /api/links/:slug/reclaim tant qu’il est dans la fenêtre de récupération, ou le retirer pour de bon avec POST /api/links/:slug/purge. Rien n’est jamais supprimé définitivement à votre insu par un simple delete - le même principe de jamais-une-impasse que décrit le guide du cycle de vie du lien, exprimé en endpoints.

C’est l’objet complet via HTTP. Le dernier guide de l’API couvre les deux choses que vous automatiserez le plus souvent autour d’un lien : lire ses statistiques et diriger son trafic.