Accéder au contenu
cutty.dev
Pour les développeurs

API et serveur MCP

Créez et gérez des liens courts directement depuis votre code — via l'API REST ou via un serveur MCP dans votre assistant IA.

cutty dispose d'une API publique et d'un serveur MCP. La première vous permet de créer et de modifier des liens depuis du code ; le second fonctionne directement depuis un assistant IA qui parle le protocole MCP. Les deux utilisent la même clé d'API.

Clé d'API

Authentifiez chaque appel avec un en-tête :

Authorization: Bearer ck_your_key

Où obtenir une clé : connectez-vous, ouvrez votre tableau de bord → Clés d'API → Créer une clé. La clé complète (elle commence par ck_) ne s'affiche qu'une seule fois, à sa création — mettez-la tout de suite en lieu sûr. La limite est de 120 requêtes par minute et par clé.

URL de base

Tous les endpoints REST se trouvent sous https://cutty.dev/api/v1. Les requêtes et les réponses sont en JSON.

Créer un lien

POST /api/v1/links — le corps JSON exige au minimum une url. Le reste est facultatif :

  • url — adresse de destination (obligatoire)
  • slug — terminaison personnalisée, 3 à 40 caractères ; omettez-la pour en obtenir une aléatoire
  • expiresAt — date d'expiration au format ISO 8601
  • maxHits — limite de clics (1 à 1 000 000)
  • password — mot de passe protégeant le lien
  • tags — étiquettes séparées par des virgules pour l'organisation dans le tableau de bord
  • folder — nom du dossier dans lequel le lien est rangé
  • utmSource, utmMedium, utmCampaign — paramètres UTM ajoutés lors de la redirection

La réponse vous renvoie slug, shortUrl et target.

curl -X POST https://cutty.dev/api/v1/links \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/a/very/long/address","slug":"offer","tags":"campaign,summer"}'

Lister les liens et en consulter un seul

GET /api/v1/links renvoie tous vos liens. GET /api/v1/links/{slug} — les détails d'un lien.

curl https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key"

Modifier et supprimer

PATCH /api/v1/links/{slug} met à jour les champs que vous transmettez, DELETE /api/v1/links/{slug} supprime le lien.

curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"maxHits":500}'

Via PATCH, vous pouvez définir, entre autres : targetUrl, expiresAt, maxHits, status, password, tags, folder, ainsi que les champs avancés ci-dessous. Un champ mis à null (ou à une chaîne vide) efface cette propriété.

Ciblage, A/B et champs avancés

Les mêmes possibilités que dans l'éditeur de lien sont accessibles via l'API :

  • rules — un tableau de règles de redirection par pays ou par appareil, par ex. [{"kind":"country","match":"PL","url":"https://shop.pl"},{"kind":"device","match":"ios","url":"https://apps.apple.com/..."}]
  • abUrls — rotation A/B : un tableau [{"url":"https://a.com","weight":1},{"url":"https://b.com","weight":1}] ; utilisé quand aucune règle ne correspond
  • startsAt — date (ISO 8601) à laquelle le lien devient actif ; avant cela, le lien renvoie 425
  • webhookUrl — adresse qui reçoit une notification POST à chaque clic (fire-and-forget)
  • serveOg avec ogTitle, ogDescription, ogImageUrl — une carte d'aperçu personnalisée pour les robots des réseaux sociaux (les humains sont toujours redirigés)
curl -X PATCH https://cutty.dev/api/v1/links/offer \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"kind":"country","match":"DE","url":"https://example.de"}]}'

Opérations groupées

POST /api/v1/bulk crée plusieurs liens en une seule requête. Transmettez un tableau links (chaque élément comme une création classique), jusqu'à 500 à la fois. La réponse renvoie un résultat par ligne.

curl -X POST https://cutty.dev/api/v1/bulk \
  -H "Authorization: Bearer ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"links":[{"url":"https://a.com"},{"url":"https://b.com","slug":"b"}]}'

Statistiques d'un lien

GET /api/v1/links/{slug}/stats renvoie un résumé des clics : le total, une répartition par appareil et par navigateur, et la distribution sur les dernières 24 heures.

curl https://cutty.dev/api/v1/links/offer/stats \
  -H "Authorization: Bearer ck_your_key"

Serveur MCP

Si vous travaillez avec un assistant IA, vous pouvez connecter cutty via MCP (Model Context Protocol) et lui demander de raccourcir et d'organiser des liens directement dans la conversation. Le serveur tourne sur https://mcp.cutty.dev/mcp en Streamable HTTP, et vous vous authentifiez avec la même clé d'API — l'en-tête Authorization: Bearer ck_....

La liste complète des outils, les extraits de connexion prêts à l'emploi et des exemples se trouvent sur une page dédiée : serveur MCP de cutty.

Quelque chose ne fonctionne pas ?

Écrivez à [email protected] — je réponds le jour même.