Documentation API - klipo.link

URL de base

https://klipo.link/api/v1

Authentification

Créez un jeton depuis Paramètres → Jetons API (propriétaire du compte uniquement). Le jeton n'est affiché qu'une seule fois à sa création — conservez-le en lieu sûr.

Envoyez-le dans l'en-tête Authorization de chaque requête :

Authorization: Bearer <votre_jeton>

Un jeton créé par un membre invité (éditeur/éditrice) agit sur les mêmes liens que le propriétaire du compte — les jetons eux-mêmes ne peuvent être créés que par le propriétaire.

Erreurs

Les erreurs applicatives ont la forme suivante :

{
  "error": {
    "code": "short_url_not_found",
    "message": "No short URL found for code "abc12"."
  }
}

Les erreurs de validation des champs envoyés suivent le format standard Laravel : {"message": "...", "errors": {"champ": ["..."]}}.

Statut	Code	Signification
401	-	Jeton absent, invalide ou révoqué.
403	api_access_requires_paid_plan	Le compte est sur le forfait gratuit.
404	short_url_not_found	Aucun lien pour ce code.
409	slug_taken	Le code personnalisé demandé existe déjà.
422	link_limit_reached	Limite de liens du forfait atteinte.
422	invalid_data	L'URL de destination a été rejetée.
403	feature_not_available	L'expiration ou les règles de redirection ne sont pas incluses dans le forfait.

Liens courts

GET /short-urls

Liste vos liens, paginée par 20.

Paramètres de requête

page — numéro de page (défaut 1)
q — recherche texte libre

Exemple

curl https://klipo.link/api/v1/short-urls?page=1 \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "shortCode": "promo-ete",
      "shortUrl": "https://klipo.link/promo-ete",
      "longUrl": "https://exemple.com/collections/ete",
      "title": "Campagne été",
      "tags": ["campagne", "été"],
      "dateCreated": "2026-06-12T14:03:00+00:00",
      "validUntil": null,
      "visitsSummary": { "total": 4812, "nonBots": 4680 }
    }
  ],
  "meta": { "currentPage": 1, "pagesCount": 8, "totalItems": 148 }
}

POST /short-urls

Crée un nouveau lien court.

Corps de la requête (JSON)

long_url (requis) — l'URL de destination
title — titre libre
custom_slug — code personnalisé (lettres, chiffres, tirets ; ne peut pas être un mot réservé par klipo.link, ex. login)
tags — tableau de chaînes
expires_at — date ISO 8601 - forfaits payants avec expiration uniquement

Exemple

curl -X POST https://klipo.link/api/v1/short-urls \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"long_url": "https://exemple.com/page", "custom_slug": "promo-ete"}'

Réponse : 201 avec le lien créé, même forme que ci-dessus (sans meta).

GET /short-urls/{'{shortCode}'}

Détails d'un lien.

curl https://klipo.link/api/v1/short-urls/promo-ete \
  -H "Authorization: Bearer $TOKEN"

PUT /short-urls/{'{shortCode}'}

Met à jour un lien existant. Remplace entièrement le titre, les tags et la date d'expiration - un champ omis est retiré, pas conservé.

Corps de la requête (JSON)

long_url (requis) — l'URL de destination
title — titre libre
tags — tableau de chaînes
expires_at — date ISO 8601 - forfaits payants avec expiration uniquement

Exemple

curl -X PUT https://klipo.link/api/v1/short-urls/promo-ete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"long_url": "https://exemple.com/nouvelle-page", "title": "Nouveau titre"}'

Réponse : 200 avec le lien mis à jour, même forme que ci-dessus.

DELETE /short-urls/{'{shortCode}'}

Supprime un lien. Réponse 204 sans contenu.

curl -X DELETE https://klipo.link/api/v1/short-urls/promo-ete \
  -H "Authorization: Bearer $TOKEN"

GET /short-urls/{'{shortCode}'}/visits

Statistiques de clics sur les 30 derniers jours (fenêtre fixe). Les robots détectés sont exclus.

curl https://klipo.link/api/v1/short-urls/promo-ete/visits \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "daily": { "2026-08-15": 12, "2026-08-16": 8, "...": 0 },
    "referrers": { "newsletter.exemple.fr": 2140, "instagram.com": 842 },
    "countries": { "France": 3104, "Belgique": 612 },
    "browsers": { "Chrome": 2890, "Safari": 1204 },
    "totalNonBot": 4680
  }
}

referrers, countries et browsers sont limités aux 5 valeurs les plus fréquentes.

Règles de redirection

Disponibles sur les forfaits payants incluant les règles de redirection. Une règle redirige vers une autre URL selon l'appareil, le pays ou la langue du visiteur - la destination par défaut du lien s'applique quand aucune règle ne correspond.

GET /short-urls/{'{shortCode}'}/redirect-rules

Liste les règles de redirection d'un lien, par ordre de priorité.

curl https://klipo.link/api/v1/short-urls/promo-ete/redirect-rules \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "priority": 1,
      "longUrl": "https://exemple.com/mobile",
      "conditions": [{ "type": "device", "matchValue": "mobile", "matchKey": null }]
    }
  ]
}

POST /short-urls/{'{shortCode}'}/redirect-rules

Ajoute une règle de redirection (la nouvelle règle est ajoutée après les règles existantes).

Corps de la requête (JSON)

condition_type (requis) — device, country ou language
condition_value (requis) — appareil (android, ios, mobile, windows, macos, linux, chromeos, desktop), code pays ISO 2 lettres (ex. FR), ou code langue
destination_url (requis) — URL de redirection si la condition correspond

Exemple

curl -X POST https://klipo.link/api/v1/short-urls/promo-ete/redirect-rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"condition_type": "device", "condition_value": "mobile", "destination_url": "https://exemple.com/mobile"}'

Réponse : 201 avec la liste complète des règles, même forme que ci-dessus.

DELETE /short-urls/{'{shortCode}'}/redirect-rules/{'{priority}'}

Supprime une règle par sa priorité (le nombre renvoyé par la liste ci-dessus). Réponse 204 sans contenu.

curl -X DELETE https://klipo.link/api/v1/short-urls/promo-ete/redirect-rules/1 \
  -H "Authorization: Bearer $TOKEN"

QR code

GET /short-urls/{'{shortCode}'}/qr-code

Génère le QR code du lien court et renvoie directement l'image (pas de JSON).

Sur les forfaits payants, si un logo a été ajouté dans les paramètres du compte, il est automatiquement inséré au centre du QR code — aucun paramètre supplémentaire n'est requis.

Paramètres de requête

format — png ou svg (défaut png)
download — mis à 1 pour recevoir un en-tête Content-Disposition en pièce jointe plutôt qu'affiché en ligne

Exemple

curl "https://klipo.link/api/v1/short-urls/promo-ete/qr-code?format=svg&download=1" \
  -H "Authorization: Bearer $TOKEN" \
  -o promo-ete.svg