Aller au contenu
  • API publique v1
  • REST, JSON
  • OpenAPI 3.1

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
POST /links
curl -X POST "https://durl.louismetais.fr/api/v1/links" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e4c1e-7f2a-4d61-9a3c-2f8e6d1b7c90" \
  -d '{
  "url": "https://example.com/offres/ete",
  "slug": "promo-ete",
  "title": "Offres d'\''été",
  "expiresAt": "2027-01-31T23:00:00.000Z"
}'
201RéponseJSON
{
  "id": "cmb7k2q9x0001l5h8t3v6w4zr",
  "slug": "promo-ete",
  "shortUrl": "https://durl.louismetais.fr/promo-ete",
  "domainId": null,
  "url": "https://example.com/offres/ete?utm_source=newsletter",
  "title": "Offres d'été",
  "description": null,
  "notes": null,
  "folderId": null,
  "tagIds": [
    "cmb7k31ab0002l5h8c9d0e1f2"
  ],
  "favorite": false,
  "archived": false,
  "deleted": false,
  "deletedAt": null,
  "status": "ACTIVE",
  "statusReason": null,
  "activeFrom": null,
  "expiresAt": "2027-01-31T23:00:00.000Z",
  "expired": false,
  "maxClicks": null,
  "fallbackUrl": null,
  "hasPassword": false,
  "redirectType": 302,
  "noIndex": true,
  "interstitial": false,
  "targeting": null,
  "rotation": null,
  "ogTitle": null,
  "ogDescription": null,
  "ogImage": null,
  "publicStats": false,
  "statsToken": null,
  "qr": null,
  "clickCount": 128,
  "uniqueCount": 97,
  "qrCount": 12,
  "lastClickAt": "2026-11-15T18:42:07.000Z",
  "source": "API",
  "createdAt": "2026-11-02T09:15:00.000Z",
  "updatedAt": "2026-11-02T09:15:00.000Z"
}

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.

  1. Créez une clé dans Tableau de bord, Clés API, avec les portées utiles.
  2. Envoyez-la dans l'en-tête Authorization: Bearer de chaque requête.
  3. Lisez le statut HTTP : 2xx en cas de succès, sinon un document d'erreur détaillé.

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.

Chaque requête porte une clé API dans l'en-tête Authorization. Une clé commence par durl_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).

Requête authentifiéeHTTP
GET /api/v1/me HTTP/1.1
Host: durl.louismetais.fr
Authorization: Bearer durl_live_VOTRE_CLE

Portées des clés

links:read
Lire les liens
  • GET /links
  • GET /links/{id}
links:write
Créer, modifier et supprimer des liens
  • POST /links
  • POST /links/bulk
  • PATCH /links/{id}
  • DELETE /links/{id}
stats:read
Lire les statistiques
  • GET /links/{id}/stats
qr:read
Générer les QR codes
  • GET /links/{id}/qr
tags:read
Lire étiquettes et dossiers
  • GET /tags
  • GET /folders
tags:write
Gérer étiquettes et dossiers
  • POST /tags
  • PATCH /tags/{id}
  • DELETE /tags/{id}
  • POST /folders
  • PATCH /folders/{id}
  • DELETE /folders/{id}
domains:read
Lire les domaines
  • GET /domains
webhooks:read
Lire les webhooks
  • GET /webhooks
webhooks:write
Gérer les webhooks
  • POST /webhooks
  • DELETE /webhooks/{id}
account:read
Lire le compte et les quotas
  • GET /me

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-Limit
Requêtes autorisées par fenêtre de 60 secondes.
RateLimit-Remaining
Requêtes restantes dans la fenêtre en cours.
RateLimit-Reset
Secondes avant la remise à zéro du compteur.
Retry-After
Uniquement sur une réponse 429 : secondes à attendre avant de réessayer.

Au-delà de la limite, l'API répond 429 avec le code rate_limited. Les quotas de création de liens (par jour, au total) sont distincts : ils répondent 403 avec le code quota_exceeded, et GET /me donne la consommation en cours.

Astuce

Attendez le délai indiqué par Retry-After plutôt que de réessayer en boucle.

Limite dépasséeHTTP
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

{
  "type": "https://durl.louismetais.fr/docs#erreur-rate_limited",
  "title": "Trop de requêtes",
  "status": 429,
  "detail": "Trop de requêtes. Réessayez dans 23 secondes.",
  "code": "rate_limited"
}

Toute erreur est renvoyée au format application/problem+json (RFC 9457). Fiez-vous au statut HTTP et au membre code, stable et en anglais. detail est une phrase affichable telle quelle, en français par défaut ou en anglais avec l’en-tête Accept-Language: en. Pour une erreur de validation, errors associe chaque champ fautif à son message.

422Erreur de validationJSON
{
  "type": "https://durl.louismetais.fr/docs#erreur-validation",
  "title": "Données invalides",
  "status": 422,
  "detail": "Certains champs sont invalides.",
  "code": "validation",
  "errors": {
    "slug": "Ce slug est déjà pris.",
    "expiresAt": "La date d'expiration doit être dans le futur."
  }
}
400bad_request
Requête invalide. La requête est mal formée : JSON illisible, en-tête ou paramètre incorrect.
401invalid_api_key
Clé API invalide. Clé absente, inconnue, expirée ou révoquée.
403forbidden
Action non autorisée. Le rôle du compte ne permet pas cette action, ou le compte est suspendu.
403insufficient_scope
Portée insuffisante. La clé n'a pas la portée (scope) exigée par ce point d'entrée.
403quota_exceeded
Quota atteint. Une limite du rôle est atteinte (liens par jour, liens au total, nombre de webhooks...).
404not_found
Ressource introuvable. La ressource n'existe pas ou n'appartient pas au compte de la clé.
405method_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.
409conflict
Conflit. La ressource existe déjà ou son état ne permet pas l'opération.
409idempotency_in_progress
Requête idempotente en cours. Une requête portant la même clé d'idempotence est encore en cours de traitement.
413payload_too_large
Corps trop volumineux. Le corps de la requête dépasse la taille maximale acceptée.
415unsupported_media_type
Format non pris en charge. Le corps doit être envoyé en JSON (Content-Type: application/json).
422validation
Données invalides. Un ou plusieurs champs sont invalides. Le membre errors donne le détail par champ.
422idempotency_mismatch
Clé d'idempotence déjà utilisée. La clé d'idempotence a déjà servi pour une requête différente.
429rate_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.
500internal
Erreur interne. Erreur inattendue du serveur. Réessayez plus tard.
503maintenance
Maintenance en cours. Le site est en maintenance. Réessayez plus tard.

Les listes sont paginées par curseur, de l'élément le plus récent au plus ancien. limit fixe la taille de page (1 à 100, 20 par défaut). La réponse contient data et nextCursor : renvoyez cette valeur dans cursor pour obtenir la page suivante, jusqu'à recevoir null.

À 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.

Parcourir toutes les pages
# Première page
curl "https://durl.louismetais.fr/api/v1/links?limit=50" \
  -H "Authorization: Bearer $DURL_API_KEY"

# Page suivante : renvoyez la valeur de nextCursor
curl "https://durl.louismetais.fr/api/v1/links?limit=50&cursor=VALEUR_DE_NEXTCURSOR" \
  -H "Authorization: Bearer $DURL_API_KEY"

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êtes POST de 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ête Idempotent-Replayed: true, sans rien créer.

  • Même clé, requête différente (autre chemin ou autre corps) : 422, code idempotency_mismatch.
  • Même clé alors que la première requête est encore en cours : 409, code idempotency_in_progress.
  • Seules les réponses de succès sont mémorisées : après une erreur, la même clé peut resservir.
  • Une clé d'idempotence est propre à la clé API qui l'a utilisée.
POST /linksShell
curl -X POST "https://durl.louismetais.fr/api/v1/links" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e4c1e-7f2a-4d61-9a3c-2f8e6d1b7c90" \
  -d '{"url": "https://example.com/offres/ete"}'

Un webhook envoie une requête POST en 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.created
Lien créé
link.updated
Lien modifié
link.deleted
Lien supprimé
link.clicked
Clic sur un lien
link.expired
Lien expiré

Chaque 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) et X-Durl-Signature.

Corps du messageJSON
{
  "id": "cmb7k8r3t0007l5h8q7r8s9t0",
  "event": "link.created",
  "createdAt": "2026-11-16T09:30:00.000Z",
  "data": {
    "id": "cmb7k2q9x0001l5h8t3v6w4zr",
    "slug": "promo-ete",
    "shortUrl": "https://durl.louismetais.fr/promo-ete",
    "url": "https://example.com/offres/ete"
  }
}
En-têtes du messageHTTP
X-Durl-Event: link.created
X-Durl-Delivery: cmb7k9d1u0009l5h8a1b2c3d4
X-Durl-Signature: t=1794821400,v1=<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.

Vérifier la signature
# Recalcule la signature d'un message reçu (t et corps tels que reçus)
printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$DURL_WEBHOOK_SECRET" -hex

Créer, lister, modifier et supprimer des liens courts.

POST/api/v1/links/bulk

Cré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 LinkCreaterequis

Liens à 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.

createdentier

Nombre de liens créés.

failedentier

Nombre de liens refusés.

resultsliste de objet

Un résultat par lien envoyé, dans le même ordre.

results[].indexentier

Position dans le tableau envoyé.

results[].okbooléen
results[].linkobjet Link

Un lien court.

results[].link.idtexte

Identifiant du lien.

results[].link.slugtexte

Partie finale du lien court.

results[].link.shortUrltexte

Lien court complet.

results[].link.domainIdtexte | null

Domaine personnalisé, ou null pour le domaine principal.

results[].link.urltexte

Adresse de destination.

results[].link.titletexte | null

Titre affiché dans le tableau de bord.

results[].link.descriptiontexte | null

Description libre.

results[].link.notestexte | null

Notes privées.

results[].link.folderIdtexte | null

Identifiant du dossier.

results[].link.tagIdsliste de texte

Identifiants d'étiquettes (20 au plus).

results[].link.favoritebooléen

Marque le lien comme favori.

results[].link.archivedbooléen

Range le lien dans les archives.

results[].link.deletedbooléen

Vrai quand le lien est dans la corbeille.

results[].link.deletedAtdate ISO 8601 | null

Date de mise à la corbeille.

results[].link.statustexte

État de modération du lien.

Valeurs possibles :"ACTIVE""DISABLED""QUARANTINED"

results[].link.statusReasontexte | null

Motif de la désactivation ou de la mise en quarantaine.

results[].link.activeFromdate ISO 8601 | null

Date d'activation.

results[].link.expiresAtdate ISO 8601 | null

Date d'expiration.

results[].link.expiredbooléen

Vrai quand la date ou le nombre maximal de clics est dépassé.

results[].link.maxClicksentier | null

Nombre maximal de clics, après quoi le lien expire.

results[].link.fallbackUrltexte | null

Destination utilisée une fois le lien expiré.

results[].link.hasPasswordbooléen

Le mot de passe lui-même ne sort jamais.

results[].link.redirectTypeentier

Code HTTP de redirection : 301, 302 ou 307.

results[].link.noIndexbooléen

Demande aux moteurs de recherche de ne pas indexer le lien.

results[].link.interstitialbooléen

Affiche une page intermédiaire avant la redirection.

results[].link.targetingobjet | null

Destinations par appareil (ios, android, desktop) et par pays (code ISO à deux lettres).

results[].link.rotationliste de objet | null

Rotation pondérée entre plusieurs destinations (test A/B), deux au moins.

2 élément(s) min.10 éléments max.

results[].link.ogTitletexte | null

Titre de l'aperçu social.

results[].link.ogDescriptiontexte | null

Description de l'aperçu social.

results[].link.ogImagetexte | null

Image de l'aperçu social.

results[].link.publicStatsbooléen

Active la page de statistiques publique.

results[].link.statsTokentexte | null

Jeton de la page de statistiques publique, le cas échéant.

results[].link.qrobjet | null

Options enregistrées du QR code (couleurs, marge, niveau de correction, logo).

results[].link.clickCountentier

Clics comptés (hors robots).

results[].link.uniqueCountentier

Visiteurs uniques.

results[].link.qrCountentier

Clics venant du QR code.

results[].link.lastClickAtdate ISO 8601 | null

Date du dernier clic.

results[].link.sourcetexte

Origine de la création.

Valeurs possibles :"WEB""API""BULK""ANON"

results[].link.createdAtdate ISO 8601

Date de création.

results[].link.updatedAtdate ISO 8601

Date de dernière modification.

results[].errorobjet
results[].error.codetexte
results[].error.detailtexte
results[].error.errorsobjet
POST /links/bulk
curl -X POST "https://durl.louismetais.fr/api/v1/links/bulk" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e4c1e-7f2a-4d61-9a3c-2f8e6d1b7c90" \
  -d '{
  "links": [
    {
      "url": "https://example.com/a"
    },
    {
      "url": "https://example.com/b",
      "slug": "page-b"
    }
  ]
}'
200RéponseJSON
{
  "created": 1,
  "failed": 1,
  "results": [
    {
      "index": 0,
      "ok": true,
      "link": {
        "id": "cmb7k2q9x0001l5h8t3v6w4zr",
        "slug": "promo-ete",
        "shortUrl": "https://durl.louismetais.fr/promo-ete",
        "domainId": null,
        "url": "https://example.com/offres/ete?utm_source=newsletter",
        "title": "Offres d'été",
        "description": null,
        "notes": null,
        "folderId": null,
        "tagIds": [
          "cmb7k31ab0002l5h8c9d0e1f2"
        ],
        "favorite": false,
        "archived": false,
        "deleted": false,
        "deletedAt": null,
        "status": "ACTIVE",
        "statusReason": null,
        "activeFrom": null,
        "expiresAt": "2027-01-31T23:00:00.000Z",
        "expired": false,
        "maxClicks": null,
        "fallbackUrl": null,
        "hasPassword": false,
        "redirectType": 302,
        "noIndex": true,
        "interstitial": false,
        "targeting": null,
        "rotation": null,
        "ogTitle": null,
        "ogDescription": null,
        "ogImage": null,
        "publicStats": false,
        "statsToken": null,
        "qr": null,
        "clickCount": 128,
        "uniqueCount": 97,
        "qrCount": 12,
        "lastClickAt": "2026-11-15T18:42:07.000Z",
        "source": "API",
        "createdAt": "2026-11-02T09:15:00.000Z",
        "updatedAt": "2026-11-02T09:15:00.000Z"
      }
    },
    {
      "index": 1,
      "ok": false,
      "error": {
        "code": "validation",
        "detail": "Certains champs sont invalides.",
        "errors": {
          "slug": "Ce slug est déjà pris."
        }
      }
    }
  ]
}

Clics d'un lien : totaux et série quotidienne.

GET/api/v1/links/{id}/stats

Totaux 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.

  • Portée requise : stats:read
  • Permission du rôle : Voir les statistiques de base
Paramètres de chemin
idtexterequis

Identifiant de la ressource.

40 caractères max.

Paramètres de requête
daysentierfacultatif

Nombre 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. 365

Réponse 200

Les statistiques du lien. Type : application/json.

Le corps est un objet LinkStats.

GET /links/{id}/stats
curl "https://durl.louismetais.fr/api/v1/links/cmb7k2q9x0001l5h8t3v6w4zr/stats?days=7" \
  -H "Authorization: Bearer $DURL_API_KEY"
200RéponseJSON
{
  "linkId": "cmb7k2q9x0001l5h8t3v6w4zr",
  "totals": {
    "clicks": 128,
    "uniques": 97,
    "qr": 12,
    "lastClickAt": "2026-11-15T18:42:07.000Z"
  },
  "period": {
    "days": 2,
    "from": "2026-11-15",
    "to": "2026-11-16",
    "clicks": 31,
    "uniques": 24,
    "qr": 3
  },
  "daily": [
    {
      "date": "2026-11-15",
      "clicks": 19,
      "uniques": 15,
      "qr": 2
    },
    {
      "date": "2026-11-16",
      "clicks": 12,
      "uniques": 9,
      "qr": 1
    }
  ],
  "countries": [
    {
      "value": "FR",
      "clicks": 22
    },
    {
      "value": "BE",
      "clicks": 6
    }
  ],
  "referrers": [
    {
      "value": "example.net",
      "clicks": 14
    },
    {
      "value": null,
      "clicks": 11
    }
  ],
  "devices": [
    {
      "value": "mobile",
      "clicks": 20
    },
    {
      "value": "desktop",
      "clicks": 11
    }
  ]
}

Image du QR code d'un lien, générée localement.

GET/api/v1/links/{id}/qr

Renvoie 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.

  • Portée requise : qr:read
Paramètres de chemin
idtexterequis

Identifiant de la ressource.

40 caractères max.

Paramètres de requête
formattextefacultatif

Format de l'image.

Valeurs possibles :"svg""png"

Par défaut : "svg"

sizeentierfacultatif

Côté en pixels (64 à 2048).

Par défaut : 512min. 64max. 2048

Réponse 200

L'image du QR code. Type : image/svg+xml ou image/png.

GET /links/{id}/qr
curl "https://durl.louismetais.fr/api/v1/links/cmb7k2q9x0001l5h8t3v6w4zr/qr?format=png&size=512" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  --output qr.png

200L'image du QR code.

Étiquettes servant à classer les liens.

GET/api/v1/tags

Renvoie les étiquettes du compte, de la plus récente à la plus ancienne.

  • Portée requise : tags:read
Paramètres de requête
limitentierfacultatif

Nombre d'éléments par page (1 à 100, 20 par défaut).

Par défaut : 20min. 1max. 100

cursortextefacultatif

Curseur 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 Tag
nextCursortexte | null

Curseur de la page suivante, ou null à la dernière page.

GET /tags
curl "https://durl.louismetais.fr/api/v1/tags" \
  -H "Authorization: Bearer $DURL_API_KEY"
200RéponseJSON
{
  "data": [
    {
      "id": "cmb7k31ab0002l5h8c9d0e1f2",
      "name": "campagne",
      "color": "blue",
      "linkCount": 4,
      "createdAt": "2026-10-20T08:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/api/v1/tags

Crée une étiquette. Le nom doit être unique dans le compte.

Corps de la requête (JSON)
nametexterequis

Nom, unique dans le compte (40 caractères au plus).

40 caractères max.

colortextefacultatif

Couleur : 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.

POST /tags
curl -X POST "https://durl.louismetais.fr/api/v1/tags" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e4c1e-7f2a-4d61-9a3c-2f8e6d1b7c90" \
  -d '{
  "name": "campagne",
  "color": "blue"
}'
201RéponseJSON
{
  "id": "cmb7k31ab0002l5h8c9d0e1f2",
  "name": "campagne",
  "color": "blue",
  "linkCount": 0,
  "createdAt": "2026-10-20T08:00:00.000Z"
}

PATCH/api/v1/tags/{id}

Renomme l'étiquette ou change sa couleur.

  • Portée requise : tags:write
  • Permission du rôle : Étiquettes, dossiers, favoris et archivage
Paramètres de chemin
idtexterequis

Identifiant de la ressource.

40 caractères max.

Corps de la requête (JSON)
nametextefacultatif

Nouveau nom.

40 caractères max.

colortextefacultatif

Couleur : 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.

PATCH /tags/{id}
curl -X PATCH "https://durl.louismetais.fr/api/v1/tags/cmb7k31ab0002l5h8c9d0e1f2" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "campagne-hiver",
  "color": "purple"
}'
200RéponseJSON
{
  "id": "cmb7k31ab0002l5h8c9d0e1f2",
  "name": "campagne",
  "color": "blue",
  "linkCount": 4,
  "createdAt": "2026-10-20T08:00:00.000Z"
}

DELETE/api/v1/tags/{id}

Supprime l'étiquette. Les liens qui la portaient sont conservés, sans elle.

  • Portée requise : tags:write
  • Permission du rôle : Étiquettes, dossiers, favoris et archivage
Paramètres de chemin
idtexterequis

Identifiant de la ressource.

40 caractères max.

Réponse 204

Étiquette supprimée. Réponse sans corps.

DELETE /tags/{id}
curl -X DELETE "https://durl.louismetais.fr/api/v1/tags/cmb7k31ab0002l5h8c9d0e1f2" \
  -H "Authorization: Bearer $DURL_API_KEY"

204Réponse sans corps.

Dossiers servant à ranger les liens.

GET/api/v1/folders

Renvoie les dossiers du compte, du plus récent au plus ancien.

  • Portée requise : tags:read
Paramètres de requête
limitentierfacultatif

Nombre d'éléments par page (1 à 100, 20 par défaut).

Par défaut : 20min. 1max. 100

cursortextefacultatif

Curseur 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 Folder
nextCursortexte | null

Curseur de la page suivante, ou null à la dernière page.

GET /folders
curl "https://durl.louismetais.fr/api/v1/folders" \
  -H "Authorization: Bearer $DURL_API_KEY"
200RéponseJSON
{
  "data": [
    {
      "id": "cmb7k3f5g0003l5h8a1b2c3d4",
      "name": "Newsletter",
      "color": "green",
      "linkCount": 12,
      "createdAt": "2026-10-18T14:30:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/api/v1/folders

Crée un dossier. Le nom doit être unique dans le compte.

Corps de la requête (JSON)
nametexterequis

Nom, unique dans le compte (60 caractères au plus).

60 caractères max.

colortextefacultatif

Couleur : 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.

POST /folders
curl -X POST "https://durl.louismetais.fr/api/v1/folders" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e4c1e-7f2a-4d61-9a3c-2f8e6d1b7c90" \
  -d '{
  "name": "Newsletter",
  "color": "green"
}'
201RéponseJSON
{
  "id": "cmb7k3f5g0003l5h8a1b2c3d4",
  "name": "Newsletter",
  "color": "green",
  "linkCount": 0,
  "createdAt": "2026-10-18T14:30:00.000Z"
}

PATCH/api/v1/folders/{id}

Renomme le dossier ou change sa couleur.

  • Portée requise : tags:write
  • Permission du rôle : Étiquettes, dossiers, favoris et archivage
Paramètres de chemin
idtexterequis

Identifiant de la ressource.

40 caractères max.

Corps de la requête (JSON)
nametextefacultatif

Nouveau nom.

60 caractères max.

colortextefacultatif

Couleur : 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.

PATCH /folders/{id}
curl -X PATCH "https://durl.louismetais.fr/api/v1/folders/cmb7k3f5g0003l5h8a1b2c3d4" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Newsletter 2027"
}'
200RéponseJSON
{
  "id": "cmb7k3f5g0003l5h8a1b2c3d4",
  "name": "Newsletter",
  "color": "green",
  "linkCount": 12,
  "createdAt": "2026-10-18T14:30:00.000Z"
}

DELETE/api/v1/folders/{id}

Supprime le dossier. Les liens qu’il contenait sont conservés, sans dossier.

  • Portée requise : tags:write
  • Permission du rôle : Étiquettes, dossiers, favoris et archivage
Paramètres de chemin
idtexterequis

Identifiant de la ressource.

40 caractères max.

Réponse 204

Dossier supprimé. Réponse sans corps.

DELETE /folders/{id}
curl -X DELETE "https://durl.louismetais.fr/api/v1/folders/cmb7k3f5g0003l5h8a1b2c3d4" \
  -H "Authorization: Bearer $DURL_API_KEY"

204Réponse sans corps.

Domaines personnalisés du compte.

GET/api/v1/domains

Renvoie les domaines personnalisés du compte. L'identifiant d'un domaine vérifié peut être passé dans domainId à la création d'un lien.

  • Portée requise : domains:read
Paramètres de requête
limitentierfacultatif

Nombre d'éléments par page (1 à 100, 20 par défaut).

Par défaut : 20min. 1max. 100

cursortextefacultatif

Curseur 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 Domain
nextCursortexte | null

Curseur de la page suivante, ou null à la dernière page.

GET /domains
curl "https://durl.louismetais.fr/api/v1/domains" \
  -H "Authorization: Bearer $DURL_API_KEY"
200RéponseJSON
{
  "data": [
    {
      "id": "cmb7k4h7j0004l5h8e5f6g7h8",
      "hostname": "go.exemple.fr",
      "status": "VERIFIED",
      "verifiedAt": "2026-10-01T10:00:00.000Z",
      "createdAt": "2026-10-01T09:55:00.000Z"
    }
  ],
  "nextCursor": null
}

Notifications HTTP signées envoyées à votre serveur.

GET/api/v1/webhooks

Renvoie les webhooks du compte. Le secret de signature ne sort jamais ici.

  • Portée requise : webhooks:read
Paramètres de requête
limitentierfacultatif

Nombre d'éléments par page (1 à 100, 20 par défaut).

Par défaut : 20min. 1max. 100

cursortextefacultatif

Curseur 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 Webhook
nextCursortexte | null

Curseur de la page suivante, ou null à la dernière page.

GET /webhooks
curl "https://durl.louismetais.fr/api/v1/webhooks" \
  -H "Authorization: Bearer $DURL_API_KEY"
200RéponseJSON
{
  "data": [
    {
      "id": "cmb7k5k9m0005l5h8i9j0k1l2",
      "name": "Mon serveur",
      "url": "https://example.org/hooks/durl",
      "events": [
        "link.created",
        "link.clicked"
      ],
      "active": true,
      "failureCount": 0,
      "disabledAt": null,
      "createdAt": "2026-11-01T12:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST/api/v1/webhooks

Cré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)
nametexterequis

Nom affiché dans le tableau de bord.

60 caractères max.

urltexterequis

Adresse 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.

POST /webhooks
curl -X POST "https://durl.louismetais.fr/api/v1/webhooks" \
  -H "Authorization: Bearer $DURL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e4c1e-7f2a-4d61-9a3c-2f8e6d1b7c90" \
  -d '{
  "name": "Mon serveur",
  "url": "https://example.org/hooks/durl",
  "events": [
    "link.created",
    "link.clicked"
  ]
}'
201RéponseJSON
{
  "id": "cmb7k5k9m0005l5h8i9j0k1l2",
  "name": "Mon serveur",
  "url": "https://example.org/hooks/durl",
  "events": [
    "link.created",
    "link.clicked"
  ],
  "active": true,
  "failureCount": 0,
  "disabledAt": null,
  "createdAt": "2026-11-01T12:00:00.000Z",
  "secret": "whsec_4mJ8xQ2nR7vB1cK9pL3sT6yW0zA5dF8h"
}

DELETE/api/v1/webhooks/{id}

Supprime le webhook et son historique de livraisons. Plus aucun événement ne lui est envoyé.

  • Portée requise : webhooks:write
  • Permission du rôle : Gérer ses webhooks
Paramètres de chemin
idtexterequis

Identifiant de la ressource.

40 caractères max.

Réponse 204

Webhook supprimé. Réponse sans corps.

DELETE /webhooks/{id}
curl -X DELETE "https://durl.louismetais.fr/api/v1/webhooks/cmb7k5k9m0005l5h8i9j0k1l2" \
  -H "Authorization: Bearer $DURL_API_KEY"

204Réponse sans corps.

Compte, rôle, limites et quotas.

GET/api/v1/me

Renvoie le compte propriétaire de la clé, son rôle, les limites de ce rôle et la consommation actuelle.

  • Portée requise : account:read
Réponse 200

Le compte, ses limites et sa consommation. Type : application/json.

Le corps est un objet Account.

GET /me
curl "https://durl.louismetais.fr/api/v1/me" \
  -H "Authorization: Bearer $DURL_API_KEY"
200RéponseJSON
{
  "user": {
    "id": "cmb7jz0aa0000l5h8u1v2w3x4",
    "username": "camille",
    "email": "camille@example.com",
    "displayName": "Camille Martin",
    "emailVerified": true,
    "createdAt": "2026-09-12T07:45:00.000Z"
  },
  "role": {
    "key": "verified",
    "name": "Vérifié"
  },
  "limits": {
    "linksPerDay": 200,
    "linksTotal": 5000,
    "trackedClicksPerMonth": 500000,
    "apiRequestsPerMinute": 60,
    "apiKeys": 3,
    "domains": 0,
    "statsRetentionDays": 365,
    "minSlugLength": 4
  },
  "usage": {
    "linksToday": 3,
    "linksTotal": 142,
    "trackedClicksThisMonth": 8421,
    "apiKeys": 1,
    "domains": 0,
    "webhooks": 0
  },
  "apiKey": {
    "id": "cmb7k6n1p0006l5h8m3n4o5p6",
    "scopes": [
      "links:read",
      "links:write",
      "account:read"
    ],
    "requestsPerMinute": 60
  }
}

Raccourcissement sans clé, très limité.

POST/api/v1/shorten

Cré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)
urltexterequis

Adresse à raccourcir.

2048 caractères max.

acceptTermstruerequis

Doit 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.

POST /shorten
curl -X POST "https://durl.louismetais.fr/api/v1/shorten" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e4c1e-7f2a-4d61-9a3c-2f8e6d1b7c90" \
  -d '{
  "url": "https://example.com/une/adresse/tres/longue",
  "acceptTerms": true
}'
201RéponseJSON
{
  "id": "cmb7k2q9x0001l5h8t3v6w4zr",
  "slug": "k3Tn9Qx",
  "shortUrl": "https://durl.louismetais.fr/k3Tn9Qx",
  "url": "https://example.com/une/adresse/tres/longue",
  "status": "ACTIVE",
  "expiresAt": "2027-02-14T10:00:00.000Z",
  "manageToken": "Zk1uY3h2Qm5NYXNkRmdISmtMcG9J",
  "statsToken": "cXdlcnR5dWlvcGFzZGZnaGprbA"
}

Description OpenAPI de cette API.

GET/api/v1/openapi.json

Renvoie 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.

  • Sans clé
Paramètres de requête
langtextefacultatif

Langue 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.

GET /openapi.json
curl "https://durl.louismetais.fr/api/v1/openapi.json"

200Le document OpenAPI 3.1.

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.

Erreur au format application/problem+json (RFC 9457).

typetexte

URI identifiant le type d'erreur.

titletexte

Résumé court.

statusentier

Code HTTP.

detailtexte

Explication affichable.

codetexte

Identifiant stable, en anglais.

errorsobjet

Erreurs par champ (validation).

Champs acceptés à la création d’un lien.

urltexterequis

Adresse de destination (http ou https).

2048 caractères max.

Afficher les 23 champs facultatifs
slugtextefacultatif

Slug personnalisé. Généré automatiquement quand il est absent.

64 caractères max.

domainIdtexte | nullfacultatif

Identifiant d'un domaine personnalisé vérifié. Absent ou null : domaine principal.

40 caractères max.

workspaceIdtexte | nullfacultatif

40 caractères max.

titletexte | nullfacultatif

Titre affiché dans le tableau de bord.

200 caractères max.

descriptiontexte | nullfacultatif

Description libre.

500 caractères max.

notestexte | nullfacultatif

Notes privées.

5000 caractères max.

folderIdtexte | nullfacultatif

Identifiant du dossier.

40 caractères max.

tagIdsliste de textefacultatif

Identifiants d'étiquettes (20 au plus).

20 éléments max.

favoritebooléenfacultatif

Marque le lien comme favori.

activeFromdate ISO 8601 | nullfacultatif

Date d'activation (ISO 8601 avec fuseau). Avant elle, le lien ne redirige pas.

expiresAtdate ISO 8601 | nullfacultatif

Date d'expiration (ISO 8601 avec fuseau).

maxClicksentier | nullfacultatif

Nombre maximal de clics, après quoi le lien expire.

min. 1max. 1000000000

fallbackUrltexte | nullfacultatif

Destination utilisée une fois le lien expiré.

2048 caractères max.

passwordtexte | nullfacultatif

Mot de passe demandé au visiteur (4 caractères au moins). Jamais renvoyé.

4 caractères min.200 caractères max.

redirectTypeentierfacultatif

Code HTTP de redirection : 301, 302 ou 307.

Valeurs possibles :301302307

noIndexbooléenfacultatif

Demande aux moteurs de recherche de ne pas indexer le lien.

interstitialbooléenfacultatif

Affiche une page intermédiaire avant la redirection.

targetingobjet | nullfacultatif

Destinations par appareil (ios, android, desktop) et par pays (code ISO à deux lettres).

targeting.devicesobjetfacultatif

Destination par appareil : ios, android, desktop.

Par défaut : {}

targeting.devices.iostextefacultatif

2048 caractères max.

targeting.devices.androidtextefacultatif

2048 caractères max.

targeting.devices.desktoptextefacultatif

2048 caractères max.

targeting.countriesobjetfacultatif

Destination par pays (code ISO à deux lettres en majuscules).

Par défaut : {}

rotationliste de objet | nullfacultatif

Rotation pondérée entre plusieurs destinations (test A/B), deux au moins.

2 élément(s) min.10 éléments max.

rotation[].urltexterequis

Adresse de destination (http ou https).

2048 caractères max.

rotation[].weightentierrequis

Poids relatif de la destination (1 à 1000).

min. 1max. 1000

ogTitletexte | nullfacultatif

Titre de l'aperçu social.

200 caractères max.

ogDescriptiontexte | nullfacultatif

Description de l'aperçu social.

500 caractères max.

publicStatsbooléenfacultatif

Active la page de statistiques publique.

utmobjetfacultatif

Paramètres UTM ajoutés à la destination (source, medium, campaign, term, content).

utm.sourcetexte | nullfacultatif

100 caractères max.

utm.mediumtexte | nullfacultatif

100 caractères max.

utm.campaigntexte | nullfacultatif

100 caractères max.

utm.termtexte | nullfacultatif

100 caractères max.

utm.contenttexte | nullfacultatif

100 caractères max.

Statistiques d'un lien.

linkIdtexte

Identifiant du lien.

totalsobjet

Compteurs depuis la création du lien.

totals.clicksentier
totals.uniquesentier
totals.qrentier

Options enregistrées du QR code (couleurs, marge, niveau de correction, logo).

totals.lastClickAtdate ISO 8601 | null
periodobjet

Totaux sur la période demandée.

period.daysentier
period.fromtexte
period.totexte
period.clicksentier
period.uniquesentier
period.qrentier

Options enregistrées du QR code (couleurs, marge, niveau de correction, logo).

dailyliste de objet

Une entrée par jour de la période, y compris les jours sans clic.

daily[].datetexte

Jour (UTC), au format AAAA-MM-JJ.

daily[].clicksentier
daily[].uniquesentier
daily[].qrentier

Options enregistrées du QR code (couleurs, marge, niveau de correction, logo).

countriesliste de objet | null

Dix premiers pays (code ISO). null sans la permission de statistiques avancées.

countries[].valuetexte | null
countries[].clicksentier
referrersliste de objet | null

Dix premiers référents. null sans la permission de statistiques avancées.

referrers[].valuetexte | null
referrers[].clicksentier
devicesliste de objet | null

Répartition par type d'appareil. null sans la permission de statistiques avancées.

devices[].valuetexte | null
devices[].clicksentier

Une étiquette.

idtexte

Identifiant.

nametexte
colortexte
linkCountentier

Nombre de liens portant cette étiquette.

createdAtdate ISO 8601

Date de création.

Un dossier.

idtexte

Identifiant.

nametexte
colortexte
linkCountentier

Nombre de liens rangés dans ce dossier.

createdAtdate ISO 8601

Date de création.

Un domaine personnalisé.

idtexte

Identifiant.

hostnametexte
statustexte

Seuls les domaines VERIFIED peuvent porter des liens.

Valeurs possibles :"PENDING""VERIFIED""FAILED"

verifiedAtdate ISO 8601 | null

Date de vérification DNS.

createdAtdate ISO 8601

Date d'ajout.

Un webhook.

idtexte

Identifiant.

nametexte
urltexte

Adresse appelée en POST.

eventsliste de "link.created" | "link.updated" | "link.deleted" | "link.clicked" | "link.expired"
activebooléen
failureCountentier

Échecs consécutifs.

disabledAtdate ISO 8601 | null

Date de désactivation automatique après trop d'échecs.

createdAtdate ISO 8601

Date de création.

Un webhook qui vient d’être créé, avec son secret.

Afficher les 9 champs de la réponse
idtexte

Identifiant.

nametexte
urltexte

Adresse appelée en POST.

eventsliste de "link.created" | "link.updated" | "link.deleted" | "link.clicked" | "link.expired"
activebooléen
failureCountentier

Échecs consécutifs.

disabledAtdate ISO 8601 | null

Date de désactivation automatique après trop d'échecs.

createdAtdate ISO 8601

Date de création.

secrettexte

Secret de signature. Renvoyé une seule fois, à la création.

Compte, rôle, limites et quotas.

userobjet
user.idtexte

Identifiant.

user.usernametexte
user.emailtexte
user.displayNametexte | null
user.emailVerifiedbooléen
user.createdAtdate ISO 8601
roleobjet
role.keytexte
role.nametexte
limitsobjet

Limites du rôle. -1 signifie illimité.

limits.linksPerDayentier

min. -1

limits.linksTotalentier

min. -1

limits.trackedClicksPerMonthentier

min. -1

limits.apiRequestsPerMinuteentier

min. 0

limits.apiKeysentier

min. 0

limits.domainsentier

min. 0

limits.statsRetentionDaysentier

min. 1

limits.minSlugLengthentier

min. 1max. 32

usageobjet

Consommation actuelle, à comparer aux limites.

usage.linksTodayentier
usage.linksTotalentier
usage.trackedClicksThisMonthentier
usage.apiKeysentier
usage.domainsentier
usage.webhooksentier
apiKeyobjet

La clé utilisée pour cette requête.

apiKey.idtexte

Identifiant.

apiKey.scopesliste de "links:read" | "links:write" | "stats:read" | "qr:read" | "tags:read" | "tags:write" | "domains:read" | "webhooks:read" | "webhooks:write" | "account:read"
apiKey.requestsPerMinuteentier

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.

GET/api/v1/links

Gardée en mémoire dans cet onglet uniquement : jamais enregistrée, effacée au rechargement.

Lister les liens. Portée requise : links:read.

Paramètres de requête (facultatifs)

GET https://durl.louismetais.fr/api/v1/links

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.