- 400
bad_request - Requête invalide. La requête est mal formée : JSON illisible, en-tête ou paramètre incorrect.
- 401
invalid_api_key - Clé API invalide. Clé absente, inconnue, expirée ou révoquée.
- 403
forbidden - Action non autorisée. Le rôle du compte ne permet pas cette action, ou le compte est suspendu.
- 403
insufficient_scope - Portée insuffisante. La clé n'a pas la portée (scope) exigée par ce point d'entrée.
- 403
quota_exceeded - Quota atteint. Une limite du rôle est atteinte (liens par jour, liens au total, nombre de webhooks...).
- 404
not_found - Ressource introuvable. La ressource n'existe pas ou n'appartient pas au compte de la clé.
- 405
method_not_allowed - Méthode non autorisée. Le chemin existe mais pas avec cette méthode. L'en-tête Allow liste les méthodes acceptées.
- 409
conflict - Conflit. La ressource existe déjà ou son état ne permet pas l'opération.
- 409
idempotency_in_progress - Requête idempotente en cours. Une requête portant la même clé d'idempotence est encore en cours de traitement.
- 413
payload_too_large - Corps trop volumineux. Le corps de la requête dépasse la taille maximale acceptée.
- 415
unsupported_media_type - Format non pris en charge. Le corps doit être envoyé en JSON (Content-Type: application/json).
- 422
validation - Données invalides. Un ou plusieurs champs sont invalides. Le membre errors donne le détail par champ.
- 422
idempotency_mismatch - Clé d'idempotence déjà utilisée. La clé d'idempotence a déjà servi pour une requête différente.
- 429
rate_limited - Trop de requêtes. La limite de débit est atteinte. L'en-tête Retry-After indique le délai d'attente en secondes.
- 500
internal - Erreur interne. Erreur inattendue du serveur. Réessayez plus tard.
- 503
maintenance - Maintenance en cours. Le site est en maintenance. Réessayez plus tard.
Documentation de l’API
Tout ce que fait l’interface, vos scripts peuvent le faire : créer et gérer des liens, lire les statistiques, générer des QR codes, recevoir des webhooks. API REST en JSON, versionnée, décrite en OpenAPI.
URL de base
https://durl.louismetais.fr/api/v1/linksIntroduction
L'API est servie sous
https://durl.louismetais.fr/api/v1. Les requêtes et les réponses sont en JSON (UTF-8), les dates au format ISO 8601 en UTC. La version fait partie du chemin (/v1) : une évolution incompatible donnerait une nouvelle version, sans casser celle-ci.Authorization: Bearerde chaque requête.La description complète est disponible au format OpenAPI 3.1 sur /api/v1/openapi.json. Elle est générée à partir des schémas qui valident réellement les requêtes : elle ne peut pas être en retard sur le serveur.
Authentification
Chaque requête porte une clé API dans l'en-tête
Authorization. Une clé commence pardurl_live_, n'est affichée qu'une fois à sa création et n'est conservée que sous forme d'empreinte SHA-256 : personne, pas même un administrateur, ne peut la relire.Les cookies de session sont ignorés par l'API : être connecté dans le navigateur ne donne aucun accès. L'API peut donc être appelée depuis un autre site (CORS ouvert), toujours avec une clé.
Attention
Ne placez jamais une clé dans du code exécuté par le navigateur de vos visiteurs.
Une clé agit au nom de son propriétaire et ne voit que ses ressources : l'identifiant d'une ressource d'un autre compte répond 404, comme s'il n'existait pas. Deux contrôles s'appliquent à chaque requête : la portée de la clé (ci-dessous), puis les permissions du rôle du compte. Une clé révoquée ou expirée cesse de fonctionner immédiatement (401).
Portées des clés
links:read/links/links/{id}links:write/links/links/bulk/links/{id}/links/{id}stats:read/links/{id}/statsqr:read/links/{id}/qrtags:read/tags/folderstags:write/tags/tags/{id}/tags/{id}/folders/folders/{id}/folders/{id}domains:read/domainswebhooks:read/webhookswebhooks:write/webhooks/webhooks/{id}account:read/meLimites de débit
Le débit est limité par clé, sur une fenêtre de 60 secondes. Le nombre de requêtes par minute et le nombre de clés dépendent du rôle du compte. Les requêtes sans clé valide sont limitées par adresse IP.
Sans compte, le point d'entrée invité est limité à 5 requêtes par minute et par adresse IP. Connectez-vous pour voir les limites de votre rôle.
Chaque réponse, succès ou erreur, porte ces en-têtes :
RateLimit-LimitRateLimit-RemainingRateLimit-ResetRetry-AfterAu-delà de la limite, l'API répond
429avec le coderate_limited. Les quotas de création de liens (par jour, au total) sont distincts : ils répondent403avec le codequota_exceeded, et GET /me donne la consommation en cours.Astuce
Attendez le délai indiqué par
Retry-Afterplutôt que de réessayer en boucle.Erreurs
Toute erreur est renvoyée au format
application/problem+json(RFC 9457). Fiez-vous au statut HTTP et au membrecode, stable et en anglais.detailest une phrase affichable telle quelle, en français par défaut ou en anglais avec l’en-têteAccept-Language: en. Pour une erreur de validation,errorsassocie chaque champ fautif à son message.bad_requestinvalid_api_keyforbiddeninsufficient_scopequota_exceedednot_foundmethod_not_allowedconflictidempotency_in_progresspayload_too_largeunsupported_media_typevalidationidempotency_mismatchrate_limitedinternalmaintenancePagination
Les listes sont paginées par curseur, de l'élément le plus récent au plus ancien.
limitfixe la taille de page (1 à 100, 20 par défaut). La réponse contientdataetnextCursor: renvoyez cette valeur danscursorpour obtenir la page suivante, jusqu'à recevoirnull.À savoir
Le curseur est opaque : ne le construisez pas et ne le modifiez pas. Contrairement à une pagination par numéro de page, il ne saute ni ne répète d'élément quand des liens sont créés pendant le parcours.
Idempotence
Une coupure réseau pendant une création laisse un doute : le lien a-t-il été créé ? Pour réessayer sans risque de doublon, ajoutez un en-tête
Idempotency-Key(un UUID convient) aux requêtesPOSTde création. Si la même requête revient avec la même clé dans les 24 heures, l'API renvoie la réponse d'origine, avec l'en-têteIdempotent-Replayed: true, sans rien créer.422, codeidempotency_mismatch.409, codeidempotency_in_progress./linksShellWebhooks
Un webhook envoie une requête
POSTen JSON à votre serveur quand un événement se produit. Créez-le depuis le tableau de bord ou par l'API (POST /webhooks). Le secret de signature est généré par Durl et affiché une seule fois, à la création.link.createdlink.updatedlink.deletedlink.clickedlink.expiredChaque message porte les en-têtes
X-Durl-Event(nom de l'événement),X-Durl-Delivery(identifiant de la livraison, utile pour ignorer un doublon) etX-Durl-Signature.Vérifier la signature
L'en-tête a la forme
X-Durl-Signature: t=<horodatage>,v1=<signature>. La signature est le HMAC-SHA256, en hexadécimal, de la chaîne<horodatage>.<corps brut>avec votre secret pour clé. Recalculez-la sur le corps exact reçu (avant tout décodage JSON), comparez en temps constant, et refusez les messages dont l'horodatage (secondes Unix) date de plus de cinq minutes.Répondez par un statut 2xx en moins de 8 secondes, puis traitez le message de votre côté. Toute autre réponse compte comme un échec : la livraison est retentée jusqu'à cinq fois, après 1 minute, 5 minutes, 30 minutes, 2 heures puis 12 heures. Après 20 échecs consécutifs, le webhook est désactivé et vous êtes prévenu.
À savoir
Votre adresse doit être publique et en HTTPS, les redirections ne sont pas suivies.
Référence
Tous les chemins sont relatifs à
https://durl.louismetais.fr/api/v1. Les exemples lisent la clé dans la variable d'environnementDURL_API_KEY.Liens
Créer, lister, modifier et supprimer des liens courts.
Lister les liens
GET
/api/v1/linksRenvoie les liens du compte, du plus récent au plus ancien, avec recherche, filtres et pagination par curseur.
Paramètres de requête
qtextefacultatifRecherche dans le slug, la destination, le titre et la description.
200 caractères max.
viewtextefacultatifactive (par défaut), archived, trash (corbeille) ou all.
Valeurs possibles :
"active""archived""trash""all"Par défaut :
"active"folderIdtextefacultatifIdentifiant de dossier, ou « none » pour les liens sans dossier.
40 caractères max.
tagIdstextefacultatifIdentifiants d'étiquettes séparés par des virgules (10 au plus). Un lien est retenu s'il en porte au moins une.
450 caractères max.
favoritetextefacultatifFavoris uniquement (true) ou non favoris (false).
Valeurs possibles :
"true""false"statustextefacultatifÉtat de modération.
Valeurs possibles :
"ACTIVE""DISABLED""QUARANTINED"hasPasswordtextefacultatifLiens protégés par mot de passe, ou non.
Valeurs possibles :
"true""false"expiredtextefacultatifLiens dont la date d'expiration est passée, ou non.
Valeurs possibles :
"true""false"fromdate ISO 8601facultatifCréés à partir de cette date (ISO 8601).
todate ISO 8601facultatifCréés jusqu'à cette date (ISO 8601).
limitentierfacultatifNombre d'éléments par page (1 à 100, 20 par défaut).
Par défaut :
20min. 1max. 100cursortextefacultatifCurseur opaque renvoyé dans nextCursor par la page précédente.
200 caractères max.
Réponse 200
Une page de liens. Type : application/json.
dataliste de objet LinknextCursortexte | nullCurseur de la page suivante, ou null à la dernière page.
Erreurs possibles
/linksCréer un lien
POST
/api/v1/linksCrée un lien court. Seul url est obligatoire. Chaque option avancée (slug personnalisé, mot de passe, expiration, ciblage, rotation...) dépend d'une permission du rôle : sans elle, la requête est refusée avec le champ concerné.
Corps de la requête (JSON)
urltexterequisAdresse de destination (http ou https).
2048 caractères max.
Afficher les 23 champs facultatifs
slugtextefacultatifSlug personnalisé. Généré automatiquement quand il est absent.
64 caractères max.
domainIdtexte | nullfacultatifIdentifiant d'un domaine personnalisé vérifié. Absent ou null : domaine principal.
40 caractères max.
workspaceIdtexte | nullfacultatif40 caractères max.
titletexte | nullfacultatifTitre affiché dans le tableau de bord.
200 caractères max.
descriptiontexte | nullfacultatifDescription libre.
500 caractères max.
notestexte | nullfacultatifNotes privées.
5000 caractères max.
folderIdtexte | nullfacultatifIdentifiant du dossier.
40 caractères max.
tagIdsliste de textefacultatifIdentifiants d'étiquettes (20 au plus).
20 éléments max.
favoritebooléenfacultatifMarque le lien comme favori.
activeFromdate ISO 8601 | nullfacultatifDate d'activation (ISO 8601 avec fuseau). Avant elle, le lien ne redirige pas.
expiresAtdate ISO 8601 | nullfacultatifDate d'expiration (ISO 8601 avec fuseau).
maxClicksentier | nullfacultatifNombre maximal de clics, après quoi le lien expire.
min. 1max. 1000000000
fallbackUrltexte | nullfacultatifDestination utilisée une fois le lien expiré.
2048 caractères max.
passwordtexte | nullfacultatifMot de passe demandé au visiteur (4 caractères au moins). Jamais renvoyé.
4 caractères min.200 caractères max.
redirectTypeentierfacultatifCode HTTP de redirection : 301, 302 ou 307.
Valeurs possibles :
301302307noIndexbooléenfacultatifDemande aux moteurs de recherche de ne pas indexer le lien.
interstitialbooléenfacultatifAffiche une page intermédiaire avant la redirection.
targetingobjet | nullfacultatifDestinations par appareil (ios, android, desktop) et par pays (code ISO à deux lettres).
targeting.devicesobjetfacultatifDestination par appareil : ios, android, desktop.
Par défaut :
{}targeting.devices.iostextefacultatif2048 caractères max.
targeting.devices.androidtextefacultatif2048 caractères max.
targeting.devices.desktoptextefacultatif2048 caractères max.
targeting.countriesobjetfacultatifDestination par pays (code ISO à deux lettres en majuscules).
Par défaut :
{}rotationliste de objet | nullfacultatifRotation pondérée entre plusieurs destinations (test A/B), deux au moins.
2 élément(s) min.10 éléments max.
rotation[].urltexterequisAdresse de destination (http ou https).
2048 caractères max.
rotation[].weightentierrequisPoids relatif de la destination (1 à 1000).
min. 1max. 1000
ogTitletexte | nullfacultatifTitre de l'aperçu social.
200 caractères max.
ogDescriptiontexte | nullfacultatifDescription de l'aperçu social.
500 caractères max.
publicStatsbooléenfacultatifActive la page de statistiques publique.
utmobjetfacultatifParamètres UTM ajoutés à la destination (source, medium, campaign, term, content).
utm.sourcetexte | nullfacultatif100 caractères max.
utm.mediumtexte | nullfacultatif100 caractères max.
utm.campaigntexte | nullfacultatif100 caractères max.
utm.termtexte | nullfacultatif100 caractères max.
utm.contenttexte | nullfacultatif100 caractères max.
Réponse 201
Le lien créé. Type : application/json.
Le corps est un objet Link.
Erreurs possibles
/linksCréer des liens en masse
POST
/api/v1/links/bulkCrée jusqu'à 100 liens en une requête. Chaque lien est traité séparément : la réponse est toujours 200 et donne un résultat par lien, créé ou refusé avec son erreur.
Corps de la requête (JSON)
linksliste de objet LinkCreaterequisLiens à créer (100 au plus).
1 élément(s) min.100 éléments max.
Réponse 200
Résultat lien par lien. Type : application/json.
createdentierNombre de liens créés.
failedentierNombre de liens refusés.
resultsliste de objetUn résultat par lien envoyé, dans le même ordre.
results[].indexentierPosition dans le tableau envoyé.
results[].okbooléenresults[].linkobjet LinkUn lien court.
results[].link.idtexteIdentifiant du lien.
results[].link.slugtextePartie finale du lien court.
results[].link.shortUrltexteLien court complet.
results[].link.domainIdtexte | nullDomaine personnalisé, ou null pour le domaine principal.
results[].link.urltexteAdresse de destination.
results[].link.titletexte | nullTitre affiché dans le tableau de bord.
results[].link.descriptiontexte | nullDescription libre.
results[].link.notestexte | nullNotes privées.
results[].link.folderIdtexte | nullIdentifiant du dossier.
results[].link.tagIdsliste de texteIdentifiants d'étiquettes (20 au plus).
results[].link.favoritebooléenMarque le lien comme favori.
results[].link.archivedbooléenRange le lien dans les archives.
results[].link.deletedbooléenVrai quand le lien est dans la corbeille.
results[].link.deletedAtdate ISO 8601 | nullDate de mise à la corbeille.
results[].link.statustexteÉtat de modération du lien.
Valeurs possibles :
"ACTIVE""DISABLED""QUARANTINED"results[].link.statusReasontexte | nullMotif de la désactivation ou de la mise en quarantaine.
results[].link.activeFromdate ISO 8601 | nullDate d'activation.
results[].link.expiresAtdate ISO 8601 | nullDate d'expiration.
results[].link.expiredbooléenVrai quand la date ou le nombre maximal de clics est dépassé.
results[].link.maxClicksentier | nullNombre maximal de clics, après quoi le lien expire.
results[].link.fallbackUrltexte | nullDestination utilisée une fois le lien expiré.
results[].link.hasPasswordbooléenLe mot de passe lui-même ne sort jamais.
results[].link.redirectTypeentierCode HTTP de redirection : 301, 302 ou 307.
results[].link.noIndexbooléenDemande aux moteurs de recherche de ne pas indexer le lien.
results[].link.interstitialbooléenAffiche une page intermédiaire avant la redirection.
results[].link.targetingobjet | nullDestinations par appareil (ios, android, desktop) et par pays (code ISO à deux lettres).
results[].link.rotationliste de objet | nullRotation pondérée entre plusieurs destinations (test A/B), deux au moins.
2 élément(s) min.10 éléments max.
results[].link.ogTitletexte | nullTitre de l'aperçu social.
results[].link.ogDescriptiontexte | nullDescription de l'aperçu social.
results[].link.ogImagetexte | nullImage de l'aperçu social.
results[].link.publicStatsbooléenActive la page de statistiques publique.
results[].link.statsTokentexte | nullJeton de la page de statistiques publique, le cas échéant.
results[].link.qrobjet | nullOptions enregistrées du QR code (couleurs, marge, niveau de correction, logo).
results[].link.clickCountentierClics comptés (hors robots).
results[].link.uniqueCountentierVisiteurs uniques.
results[].link.qrCountentierClics venant du QR code.
results[].link.lastClickAtdate ISO 8601 | nullDate du dernier clic.
results[].link.sourcetexteOrigine de la création.
Valeurs possibles :
"WEB""API""BULK""ANON"results[].link.createdAtdate ISO 8601Date de création.
results[].link.updatedAtdate ISO 8601Date de dernière modification.
results[].errorobjetresults[].error.codetexteresults[].error.detailtexteresults[].error.errorsobjetErreurs possibles
/links/bulkLire un lien
GET
/api/v1/links/{id}Renvoie un lien du compte, y compris quand il est archivé ou dans la corbeille.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Réponse 200
Le lien. Type : application/json.
Le corps est un objet Link.
Erreurs possibles
/links/{id}Modifier un lien
PATCH
/api/v1/links/{id}Modifie les champs envoyés et laisse les autres intacts. Envoyez null pour effacer une valeur facultative (expiration, mot de passe, dossier...). archived range ou ressort le lien des archives.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Corps de la requête (JSON)
Afficher les 22 champs acceptés
urltextefacultatifAdresse de destination (http ou https).
2048 caractères max.
slugtextefacultatifSlug personnalisé. Généré automatiquement quand il est absent.
64 caractères max.
titletexte | nullfacultatifTitre affiché dans le tableau de bord.
200 caractères max.
descriptiontexte | nullfacultatifDescription libre.
500 caractères max.
notestexte | nullfacultatifNotes privées.
5000 caractères max.
folderIdtexte | nullfacultatifIdentifiant du dossier.
40 caractères max.
tagIdsliste de textefacultatifIdentifiants d'étiquettes (20 au plus).
20 éléments max.
favoritebooléenfacultatifMarque le lien comme favori.
activeFromdate ISO 8601 | nullfacultatifDate d'activation (ISO 8601 avec fuseau). Avant elle, le lien ne redirige pas.
expiresAtdate ISO 8601 | nullfacultatifDate d'expiration (ISO 8601 avec fuseau).
maxClicksentier | nullfacultatifNombre maximal de clics, après quoi le lien expire.
min. 1max. 1000000000
fallbackUrltexte | nullfacultatifDestination utilisée une fois le lien expiré.
2048 caractères max.
passwordtexte | nullfacultatifMot de passe demandé au visiteur (4 caractères au moins). Jamais renvoyé.
4 caractères min.200 caractères max.
redirectTypeentierfacultatifCode HTTP de redirection : 301, 302 ou 307.
Valeurs possibles :
301302307noIndexbooléenfacultatifDemande aux moteurs de recherche de ne pas indexer le lien.
interstitialbooléenfacultatifAffiche une page intermédiaire avant la redirection.
targetingobjet | nullfacultatifDestinations par appareil (ios, android, desktop) et par pays (code ISO à deux lettres).
targeting.devicesobjetfacultatifDestination par appareil : ios, android, desktop.
Par défaut :
{}targeting.devices.iostextefacultatif2048 caractères max.
targeting.devices.androidtextefacultatif2048 caractères max.
targeting.devices.desktoptextefacultatif2048 caractères max.
targeting.countriesobjetfacultatifDestination par pays (code ISO à deux lettres en majuscules).
Par défaut :
{}rotationliste de objet | nullfacultatifRotation pondérée entre plusieurs destinations (test A/B), deux au moins.
2 élément(s) min.10 éléments max.
rotation[].urltexterequisAdresse de destination (http ou https).
2048 caractères max.
rotation[].weightentierrequisPoids relatif de la destination (1 à 1000).
min. 1max. 1000
ogTitletexte | nullfacultatifTitre de l'aperçu social.
200 caractères max.
ogDescriptiontexte | nullfacultatifDescription de l'aperçu social.
500 caractères max.
publicStatsbooléenfacultatifActive la page de statistiques publique.
archivedbooléenfacultatifRange le lien dans les archives.
Réponse 200
Le lien modifié. Type : application/json.
Le corps est un objet Link.
Erreurs possibles
/links/{id}Supprimer un lien
DELETE
/api/v1/links/{id}Place le lien dans la corbeille : il cesse de rediriger mais reste récupérable depuis le tableau de bord. Avec permanent=true, le lien et ses statistiques sont supprimés définitivement.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Paramètres de requête
permanenttextefacultatiftrue pour supprimer définitivement au lieu de mettre à la corbeille.
Valeurs possibles :
"true""false"Réponse 204
Lien supprimé. Réponse sans corps.
Erreurs possibles
/links/{id}204Réponse sans corps.
Statistiques
Clics d'un lien : totaux et série quotidienne.
Statistiques d'un lien
GET
/api/v1/links/{id}/statsTotaux depuis la création et série quotidienne (jours UTC) sur la période demandée. Les robots sont exclus. Les répartitions par pays, référent et appareil demandent la permission de statistiques avancées.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Paramètres de requête
daysentierfacultatifNombre de jours de la série (30 par défaut), plafonné par la durée de conservation du rôle.
Par défaut :
30min. 1max. 365Réponse 200
Les statistiques du lien. Type : application/json.
Le corps est un objet LinkStats.
Erreurs possibles
/links/{id}/statsQR codes
Image du QR code d'un lien, générée localement.
QR code d'un lien
GET
/api/v1/links/{id}/qrRenvoie l'image du QR code (SVG ou PNG), avec les couleurs, la marge et le niveau de correction enregistrés pour le lien. Le code pointe vers le lien court et les scans sont comptés à part.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Paramètres de requête
formattextefacultatifFormat de l'image.
Valeurs possibles :
"svg""png"Par défaut :
"svg"sizeentierfacultatifCôté en pixels (64 à 2048).
Par défaut :
512min. 64max. 2048Réponse 200
L'image du QR code. Type : image/svg+xml ou image/png.
Erreurs possibles
/links/{id}/qr200L'image du QR code.
Étiquettes
Étiquettes servant à classer les liens.
Lister les étiquettes
GET
/api/v1/tagsRenvoie les étiquettes du compte, de la plus récente à la plus ancienne.
Paramètres de requête
limitentierfacultatifNombre d'éléments par page (1 à 100, 20 par défaut).
Par défaut :
20min. 1max. 100cursortextefacultatifCurseur opaque renvoyé dans nextCursor par la page précédente.
200 caractères max.
Réponse 200
Une page d'étiquettes. Type : application/json.
dataliste de objet TagnextCursortexte | nullCurseur de la page suivante, ou null à la dernière page.
Erreurs possibles
/tagsCréer une étiquette
POST
/api/v1/tagsCrée une étiquette. Le nom doit être unique dans le compte.
Corps de la requête (JSON)
nametexterequisNom, unique dans le compte (40 caractères au plus).
40 caractères max.
colortextefacultatifCouleur : blue, green, amber, red, purple, gray.
Valeurs possibles :
"blue""green""amber""red""purple""gray"Par défaut :
"blue"Réponse 201
L'étiquette créée. Type : application/json.
Le corps est un objet Tag.
Erreurs possibles
/tagsModifier une étiquette
PATCH
/api/v1/tags/{id}Renomme l'étiquette ou change sa couleur.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Corps de la requête (JSON)
nametextefacultatifNouveau nom.
40 caractères max.
colortextefacultatifCouleur : blue, green, amber, red, purple, gray.
Valeurs possibles :
"blue""green""amber""red""purple""gray"Réponse 200
L'étiquette modifiée. Type : application/json.
Le corps est un objet Tag.
Erreurs possibles
/tags/{id}Supprimer une étiquette
DELETE
/api/v1/tags/{id}Supprime l'étiquette. Les liens qui la portaient sont conservés, sans elle.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Réponse 204
Étiquette supprimée. Réponse sans corps.
Erreurs possibles
/tags/{id}204Réponse sans corps.
Dossiers
Dossiers servant à ranger les liens.
Lister les dossiers
GET
/api/v1/foldersRenvoie les dossiers du compte, du plus récent au plus ancien.
Paramètres de requête
limitentierfacultatifNombre d'éléments par page (1 à 100, 20 par défaut).
Par défaut :
20min. 1max. 100cursortextefacultatifCurseur opaque renvoyé dans nextCursor par la page précédente.
200 caractères max.
Réponse 200
Une page de dossiers. Type : application/json.
dataliste de objet FoldernextCursortexte | nullCurseur de la page suivante, ou null à la dernière page.
Erreurs possibles
/foldersCréer un dossier
POST
/api/v1/foldersCrée un dossier. Le nom doit être unique dans le compte.
Corps de la requête (JSON)
nametexterequisNom, unique dans le compte (60 caractères au plus).
60 caractères max.
colortextefacultatifCouleur : blue, green, amber, red, purple, gray.
Valeurs possibles :
"blue""green""amber""red""purple""gray"Par défaut :
"blue"Réponse 201
Le dossier créé. Type : application/json.
Le corps est un objet Folder.
Erreurs possibles
/foldersModifier un dossier
PATCH
/api/v1/folders/{id}Renomme le dossier ou change sa couleur.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Corps de la requête (JSON)
nametextefacultatifNouveau nom.
60 caractères max.
colortextefacultatifCouleur : blue, green, amber, red, purple, gray.
Valeurs possibles :
"blue""green""amber""red""purple""gray"Réponse 200
Le dossier modifié. Type : application/json.
Le corps est un objet Folder.
Erreurs possibles
/folders/{id}Supprimer un dossier
DELETE
/api/v1/folders/{id}Supprime le dossier. Les liens qu’il contenait sont conservés, sans dossier.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Réponse 204
Dossier supprimé. Réponse sans corps.
Erreurs possibles
/folders/{id}204Réponse sans corps.
Domaines
Domaines personnalisés du compte.
Lister les domaines
GET
/api/v1/domainsRenvoie les domaines personnalisés du compte. L'identifiant d'un domaine vérifié peut être passé dans domainId à la création d'un lien.
Paramètres de requête
limitentierfacultatifNombre d'éléments par page (1 à 100, 20 par défaut).
Par défaut :
20min. 1max. 100cursortextefacultatifCurseur opaque renvoyé dans nextCursor par la page précédente.
200 caractères max.
Réponse 200
Une page de domaines. Type : application/json.
dataliste de objet DomainnextCursortexte | nullCurseur de la page suivante, ou null à la dernière page.
Erreurs possibles
/domainsWebhooks
Notifications HTTP signées envoyées à votre serveur.
Lister les webhooks
GET
/api/v1/webhooksRenvoie les webhooks du compte. Le secret de signature ne sort jamais ici.
Paramètres de requête
limitentierfacultatifNombre d'éléments par page (1 à 100, 20 par défaut).
Par défaut :
20min. 1max. 100cursortextefacultatifCurseur opaque renvoyé dans nextCursor par la page précédente.
200 caractères max.
Réponse 200
Une page de webhooks. Type : application/json.
dataliste de objet WebhooknextCursortexte | nullCurseur de la page suivante, ou null à la dernière page.
Erreurs possibles
/webhooksCréer un webhook
POST
/api/v1/webhooksCrée un webhook. Le secret de signature est généré par le serveur et renvoyé une seule fois, dans cette réponse : conservez-le pour vérifier l'en-tête X-Durl-Signature.
Corps de la requête (JSON)
nametexterequisNom affiché dans le tableau de bord.
60 caractères max.
urltexterequisAdresse HTTPS publique qui recevra les événements.
2048 caractères max.
eventsliste de "link.created" | "link.updated" | "link.deleted" | "link.clicked" | "link.expired"requisÉvénements à recevoir : link.created, link.updated, link.deleted, link.clicked, link.expired.
1 élément(s) min.5 éléments max.
Réponse 201
Le webhook créé, avec son secret. Type : application/json.
Le corps est un objet WebhookCreated.
Erreurs possibles
/webhooksSupprimer un webhook
DELETE
/api/v1/webhooks/{id}Supprime le webhook et son historique de livraisons. Plus aucun événement ne lui est envoyé.
Paramètres de chemin
idtexterequisIdentifiant de la ressource.
40 caractères max.
Réponse 204
Webhook supprimé. Réponse sans corps.
Erreurs possibles
/webhooks/{id}204Réponse sans corps.
Compte
Compte, rôle, limites et quotas.
Compte et quotas
GET
/api/v1/meRenvoie le compte propriétaire de la clé, son rôle, les limites de ce rôle et la consommation actuelle.
Réponse 200
Le compte, ses limites et sa consommation. Type : application/json.
Le corps est un objet Account.
Erreurs possibles
/meInvités
Raccourcissement sans clé, très limité.
Raccourcir sans clé
POST
/api/v1/shortenCrée un lien anonyme sans authentification. Très limité en débit (par adresse IP, par minute, par heure et par jour), sans option avancée, et le lien expire automatiquement. La réponse contient les jetons secrets de gestion et de statistiques : ils ne sont affichés qu'une fois. Ce point d'entrée peut être désactivé par l'administrateur.
Corps de la requête (JSON)
urltexterequisAdresse à raccourcir.
2048 caractères max.
acceptTermstruerequisDoit valoir true : vous acceptez les conditions générales, la politique de confidentialité et les mentions légales.
Réponse 201
Le lien anonyme créé. Type : application/json.
Le corps est un objet GuestLink.
Erreurs possibles
/shortenSpécification
Description OpenAPI de cette API.
Spécification OpenAPI
GET
/api/v1/openapi.jsonRenvoie la description OpenAPI 3.1 de l'API, générée à partir des schémas de validation du serveur. Publique et mise en cache.
Paramètres de requête
langtextefacultatifLangue du document : fr ou en. Par défaut, celle de l'en-tête Accept-Language, sinon le français.
Valeurs possibles :
"fr""en"Réponse 200
Le document OpenAPI 3.1. Type : application/json.
Erreurs possibles
/openapi.json200Le document OpenAPI 3.1.
Objets
Les objets renvoyés par plusieurs points d'entrée sont décrits une seule fois ici. Les mêmes définitions figurent dans la spécification OpenAPI, sous
components.schemas.ProblemErreur au format application/problem+json (RFC 9457).
typetexteURI identifiant le type d'erreur.
titletexteRésumé court.
statusentierCode HTTP.
detailtexteExplication affichable.
codetexteIdentifiant stable, en anglais.
errorsobjetErreurs par champ (validation).
LinkUn lien court.
Afficher les 40 champs de la réponse
idtexteIdentifiant du lien.
slugtextePartie finale du lien court.
shortUrltexteLien court complet.
domainIdtexte | nullDomaine personnalisé, ou null pour le domaine principal.
urltexteAdresse de destination.
titletexte | nullTitre affiché dans le tableau de bord.
descriptiontexte | nullDescription libre.
notestexte | nullNotes privées.
folderIdtexte | nullIdentifiant du dossier.
tagIdsliste de texteIdentifiants d'étiquettes (20 au plus).
favoritebooléenMarque le lien comme favori.
archivedbooléenRange le lien dans les archives.
deletedbooléenVrai quand le lien est dans la corbeille.
deletedAtdate ISO 8601 | nullDate de mise à la corbeille.
statustexteÉtat de modération du lien.
Valeurs possibles :
"ACTIVE""DISABLED""QUARANTINED"statusReasontexte | nullMotif de la désactivation ou de la mise en quarantaine.
activeFromdate ISO 8601 | nullDate d'activation.
expiresAtdate ISO 8601 | nullDate d'expiration.
expiredbooléenVrai quand la date ou le nombre maximal de clics est dépassé.
maxClicksentier | nullNombre maximal de clics, après quoi le lien expire.
fallbackUrltexte | nullDestination utilisée une fois le lien expiré.
hasPasswordbooléenLe mot de passe lui-même ne sort jamais.
redirectTypeentierCode HTTP de redirection : 301, 302 ou 307.
noIndexbooléenDemande aux moteurs de recherche de ne pas indexer le lien.
interstitialbooléenAffiche une page intermédiaire avant la redirection.
targetingobjet | nullDestinations par appareil (ios, android, desktop) et par pays (code ISO à deux lettres).
targeting.devicesobjetDestination par appareil : ios, android, desktop.
Par défaut :
{}targeting.devices.iostexte2048 caractères max.
targeting.devices.androidtexte2048 caractères max.
targeting.devices.desktoptexte2048 caractères max.
targeting.countriesobjetDestination par pays (code ISO à deux lettres en majuscules).
Par défaut :
{}rotationliste de objet | nullRotation pondérée entre plusieurs destinations (test A/B), deux au moins.
2 élément(s) min.10 éléments max.
rotation[].urltexteAdresse de destination (http ou https).
2048 caractères max.
rotation[].weightentierPoids relatif de la destination (1 à 1000).
min. 1max. 1000
ogTitletexte | nullTitre de l'aperçu social.
ogDescriptiontexte | nullDescription de l'aperçu social.
ogImagetexte | nullImage de l'aperçu social.
publicStatsbooléenActive la page de statistiques publique.
statsTokentexte | nullJeton de la page de statistiques publique, le cas échéant.
qrobjet | nullOptions enregistrées du QR code (couleurs, marge, niveau de correction, logo).
qr.fgtextePar défaut :
"#2563eb"qr.bgtextePar défaut :
"#ffffff"qr.marginentierPar défaut :
2min. 0max. 8qr.ecctexteValeurs possibles :
"L""M""Q""H"Par défaut :
"Q"qr.logobooléenPar défaut :
trueqr.styletexteValeurs possibles :
"classic""durl"Par défaut :
"durl"clickCountentierClics comptés (hors robots).
uniqueCountentierVisiteurs uniques.
qrCountentierClics venant du QR code.
lastClickAtdate ISO 8601 | nullDate du dernier clic.
sourcetexteOrigine de la création.
Valeurs possibles :
"WEB""API""BULK""ANON"createdAtdate ISO 8601Date de création.
updatedAtdate ISO 8601Date de dernière modification.
LinkCreateChamps acceptés à la création d’un lien.
urltexterequisAdresse de destination (http ou https).
2048 caractères max.
Afficher les 23 champs facultatifs
slugtextefacultatifSlug personnalisé. Généré automatiquement quand il est absent.
64 caractères max.
domainIdtexte | nullfacultatifIdentifiant d'un domaine personnalisé vérifié. Absent ou null : domaine principal.
40 caractères max.
workspaceIdtexte | nullfacultatif40 caractères max.
titletexte | nullfacultatifTitre affiché dans le tableau de bord.
200 caractères max.
descriptiontexte | nullfacultatifDescription libre.
500 caractères max.
notestexte | nullfacultatifNotes privées.
5000 caractères max.
folderIdtexte | nullfacultatifIdentifiant du dossier.
40 caractères max.
tagIdsliste de textefacultatifIdentifiants d'étiquettes (20 au plus).
20 éléments max.
favoritebooléenfacultatifMarque le lien comme favori.
activeFromdate ISO 8601 | nullfacultatifDate d'activation (ISO 8601 avec fuseau). Avant elle, le lien ne redirige pas.
expiresAtdate ISO 8601 | nullfacultatifDate d'expiration (ISO 8601 avec fuseau).
maxClicksentier | nullfacultatifNombre maximal de clics, après quoi le lien expire.
min. 1max. 1000000000
fallbackUrltexte | nullfacultatifDestination utilisée une fois le lien expiré.
2048 caractères max.
passwordtexte | nullfacultatifMot de passe demandé au visiteur (4 caractères au moins). Jamais renvoyé.
4 caractères min.200 caractères max.
redirectTypeentierfacultatifCode HTTP de redirection : 301, 302 ou 307.
Valeurs possibles :
301302307noIndexbooléenfacultatifDemande aux moteurs de recherche de ne pas indexer le lien.
interstitialbooléenfacultatifAffiche une page intermédiaire avant la redirection.
targetingobjet | nullfacultatifDestinations par appareil (ios, android, desktop) et par pays (code ISO à deux lettres).
targeting.devicesobjetfacultatifDestination par appareil : ios, android, desktop.
Par défaut :
{}targeting.devices.iostextefacultatif2048 caractères max.
targeting.devices.androidtextefacultatif2048 caractères max.
targeting.devices.desktoptextefacultatif2048 caractères max.
targeting.countriesobjetfacultatifDestination par pays (code ISO à deux lettres en majuscules).
Par défaut :
{}rotationliste de objet | nullfacultatifRotation pondérée entre plusieurs destinations (test A/B), deux au moins.
2 élément(s) min.10 éléments max.
rotation[].urltexterequisAdresse de destination (http ou https).
2048 caractères max.
rotation[].weightentierrequisPoids relatif de la destination (1 à 1000).
min. 1max. 1000
ogTitletexte | nullfacultatifTitre de l'aperçu social.
200 caractères max.
ogDescriptiontexte | nullfacultatifDescription de l'aperçu social.
500 caractères max.
publicStatsbooléenfacultatifActive la page de statistiques publique.
utmobjetfacultatifParamètres UTM ajoutés à la destination (source, medium, campaign, term, content).
utm.sourcetexte | nullfacultatif100 caractères max.
utm.mediumtexte | nullfacultatif100 caractères max.
utm.campaigntexte | nullfacultatif100 caractères max.
utm.termtexte | nullfacultatif100 caractères max.
utm.contenttexte | nullfacultatif100 caractères max.
LinkStatsStatistiques d'un lien.
linkIdtexteIdentifiant du lien.
totalsobjetCompteurs depuis la création du lien.
totals.clicksentiertotals.uniquesentiertotals.qrentierOptions enregistrées du QR code (couleurs, marge, niveau de correction, logo).
totals.lastClickAtdate ISO 8601 | nullperiodobjetTotaux sur la période demandée.
period.daysentierperiod.fromtexteperiod.totexteperiod.clicksentierperiod.uniquesentierperiod.qrentierOptions enregistrées du QR code (couleurs, marge, niveau de correction, logo).
dailyliste de objetUne entrée par jour de la période, y compris les jours sans clic.
daily[].datetexteJour (UTC), au format AAAA-MM-JJ.
daily[].clicksentierdaily[].uniquesentierdaily[].qrentierOptions enregistrées du QR code (couleurs, marge, niveau de correction, logo).
countriesliste de objet | nullDix premiers pays (code ISO). null sans la permission de statistiques avancées.
countries[].valuetexte | nullcountries[].clicksentierreferrersliste de objet | nullDix premiers référents. null sans la permission de statistiques avancées.
referrers[].valuetexte | nullreferrers[].clicksentierdevicesliste de objet | nullRépartition par type d'appareil. null sans la permission de statistiques avancées.
devices[].valuetexte | nulldevices[].clicksentierTagUne étiquette.
idtexteIdentifiant.
nametextecolortextelinkCountentierNombre de liens portant cette étiquette.
createdAtdate ISO 8601Date de création.
FolderUn dossier.
idtexteIdentifiant.
nametextecolortextelinkCountentierNombre de liens rangés dans ce dossier.
createdAtdate ISO 8601Date de création.
DomainUn domaine personnalisé.
idtexteIdentifiant.
hostnametextestatustexteSeuls les domaines VERIFIED peuvent porter des liens.
Valeurs possibles :
"PENDING""VERIFIED""FAILED"verifiedAtdate ISO 8601 | nullDate de vérification DNS.
createdAtdate ISO 8601Date d'ajout.
WebhookUn webhook.
idtexteIdentifiant.
nametexteurltexteAdresse appelée en POST.
eventsliste de "link.created" | "link.updated" | "link.deleted" | "link.clicked" | "link.expired"activebooléenfailureCountentierÉchecs consécutifs.
disabledAtdate ISO 8601 | nullDate de désactivation automatique après trop d'échecs.
createdAtdate ISO 8601Date de création.
WebhookCreatedUn webhook qui vient d’être créé, avec son secret.
Afficher les 9 champs de la réponse
idtexteIdentifiant.
nametexteurltexteAdresse appelée en POST.
eventsliste de "link.created" | "link.updated" | "link.deleted" | "link.clicked" | "link.expired"activebooléenfailureCountentierÉchecs consécutifs.
disabledAtdate ISO 8601 | nullDate de désactivation automatique après trop d'échecs.
createdAtdate ISO 8601Date de création.
secrettexteSecret de signature. Renvoyé une seule fois, à la création.
AccountCompte, rôle, limites et quotas.
userobjetuser.idtexteIdentifiant.
user.usernametexteuser.emailtexteuser.displayNametexte | nulluser.emailVerifiedbooléenuser.createdAtdate ISO 8601roleobjetrole.keytexterole.nametextelimitsobjetLimites du rôle. -1 signifie illimité.
limits.linksPerDayentiermin. -1
limits.linksTotalentiermin. -1
limits.trackedClicksPerMonthentiermin. -1
limits.apiRequestsPerMinuteentiermin. 0
limits.apiKeysentiermin. 0
limits.domainsentiermin. 0
limits.statsRetentionDaysentiermin. 1
limits.minSlugLengthentiermin. 1max. 32
usageobjetConsommation actuelle, à comparer aux limites.
usage.linksTodayentierusage.linksTotalentierusage.trackedClicksThisMonthentierusage.apiKeysentierusage.domainsentierusage.webhooksentierapiKeyobjetLa clé utilisée pour cette requête.
apiKey.idtexteIdentifiant.
apiKey.scopesliste de "links:read" | "links:write" | "stats:read" | "qr:read" | "tags:read" | "tags:write" | "domains:read" | "webhooks:read" | "webhooks:write" | "account:read"apiKey.requestsPerMinuteentierGuestLinkUn lien créé sans compte.
idtexteIdentifiant du lien.
slugtexteSlug personnalisé. Généré automatiquement quand il est absent.
shortUrltexteurltexteAdresse de destination (http ou https).
statustexteValeurs possibles :
"ACTIVE""DISABLED""QUARANTINED"expiresAtdate ISO 8601 | nullDate d'expiration automatique du lien anonyme.
manageTokentexte | nullJeton secret de gestion (suppression, rattachement à un compte). Affiché une seule fois.
statsTokentexte | nullJeton secret de la page de statistiques.
Console d'essai
Essayez l'API sans quitter cette page. Les requêtes partent de votre navigateur vers ce site, sans cookie. Votre clé reste dans la mémoire de cet onglet : elle n'est ni enregistrée, ni envoyée ailleurs qu'à l'API.
Réponse
Choisissez un point d'entrée, remplissez les champs puis envoyez : le statut, les en-têtes de débit et le corps de la réponse s'afficheront ici.