REST API · v1

Documentation API

Raccourcissez des liens, récupérez des statistiques et gérez des URLs par programmation. Tous les endpoints retournent du JSON et nécessitent un token Bearer.

Obtenir un accès API gratuit

URL de base : https://urlly.me/api/v1

POST

/api/v1/shorten

Raccourcir une URL

GET

/api/v1/stats/{hash}

Récupérer les statistiques

GET

/api/v1/links

Lister tous vos liens

—

domain_id param

Utiliser un domaine personnalisé

Authentification

Envoyez votre token dans l'en-tête Authorization à chaque requête

En-tête	Valeur
Authorization	Bearer <token>
Accept	application/json
Content-Type	application/json (POST uniquement)

Générez des tokens depuis vos Paramètres API. Les tokens ne sont affichés qu'une seule fois — conservez-les en sécurité. Les tokens manquants ou invalides retournent 401 Unauthorized.

bash

# Save your token in an environment variable
export URLLY_TOKEN="your_token_here"

# Include it in every request
curl https://urlly.me/api/v1/shorten \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

POST /api/v1/shorten 201 Created

Raccourcit une URL. Fournissez optionnellement un alias personnalisé (3–20 caractères) et un domaine personnalisé vérifié.

Corps de la requête

Champ	Type	Requis	Notes
long_url	string	Oui	URL valide, max. 2048 caractères
custom_alias	string	Non	[a-z0-9_-], 3–20 caractères
domain_id	integer	Non	ID d'un domaine personnalisé vérifié. Omettez pour utiliser le domaine par défaut.

Réponse

201 Created

{
  "success": true,
  "short_url": "https://urlly.me/my-link",
  "original_url": "https://example.com/...",
  "hash": "my-link",
  "created_at": "2026-03-19T10:00:00+00:00"
}

Exemple de requête

bash

# Auto-generated short code
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"long_url":"https://example.com/long-page"}'

# With custom alias
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "custom_alias": "my-link"
  }'

GET /api/v1/stats/{hash} 200 OK

Statistiques de clics pour un lien vous appartenant — clics totaux, répartition quotidienne, appareils, principaux navigateurs.

Paramètre d'URL

Paramètre	Description
hash	Le code court ou l'alias personnalisé de votre lien

Réponse

200 OK

{
  "success": true,
  "hash": "aBcDeFg",
  "short_url": "https://urlly.me/aBcDeFg",
  "original_url": "https://example.com",
  "is_active": true,
  "stats": {
    "total_clicks": 142,
    "clicks_by_day": [
      { "date": "2026-03-19", "total": 108 }
    ],
    "devices": { "desktop": 80, "mobile": 62 },
    "browsers": { "Chrome": 95, "Safari": 47 }
  }
}

Exemple de requête

bash

curl -X GET \
  "https://urlly.me/api/v1/stats/aBcDeFg" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

GET /api/v1/links 200 OK · Paginated

Liste paginée de tous vos liens, les plus récents en premier. 20 éléments par page.

Paramètres de requête

Paramètre	Défaut	Description
page	1	Numéro de page

Réponse

200 OK

{
  "success": true,
  "data": [
    {
      "hash": "aBcDeFg",
      "short_url": "https://urlly.me/aBcDeFg",
      "original_url": "https://example.com",
      "clicks": 142,
      "is_active": true,
      "created_at": "2026-03-19T10:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 20,
    "total": 58
  }
}

Exemple de requête

bash

# First page
curl -X GET \
  "https://urlly.me/api/v1/links" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

# Page 2
curl -X GET \
  "https://urlly.me/api/v1/links?page=2" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Accept: application/json"

Domaines personnalisés

Diffusez des liens courts depuis votre propre domaine plutôt que le domaine par défaut

Les utilisateurs authentifiés peuvent ajouter des domaines personnalisés vérifiés. Une fois vérifié, passez domain_id à l'endpoint POST /shorten pour créer des liens courts sous ce domaine.

Comment configurer

1.Allez dans Domaines personnalisés dans votre tableau de bord et ajoutez votre domaine.
2.Ajoutez un enregistrement DNS CNAME pointant votre sous-domaine vers urlly.me.
3.Ajoutez l'enregistrement TXT de vérification affiché dans le tableau de bord, puis cliquez sur Vérifier.
4.Une fois vérifié, notez l'id du domaine et passez-le comme domain_id dans les appels API.

Les codes courts sont uniques par domaine. Le même alias peut exister sur votre domaine personnalisé et sur le domaine par défaut simultanément.

Exemple : raccourcir avec un domaine personnalisé

bash

# Shorten using your custom domain (id: 3)
curl -X POST \
  "https://urlly.me/api/v1/shorten" \
  -H "Authorization: Bearer $URLLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://example.com/long-page",
    "domain_id": 3
  }'

# Response — short_url uses your domain
{
  "success": true,
  "short_url": "https://links.yourdomain.com/aBcDeFg",
  "original_url": "https://example.com/long-page",
  "hash": "aBcDeFg",
  "created_at": "2026-03-21T10:00:00+00:00"
}

Limitation du débit

2000 requêtes par 1 min par token

En-tête de réponse	Description
X-RateLimit-Limit	Max. requêtes par fenêtre (2000)
X-RateLimit-Remaining	Requêtes restantes dans cette fenêtre
Retry-After	Secondes avant réinitialisation (429 uniquement)

En cas de dépassement, les requêtes retournent 429 Too Many Requests. Consultez Retry-After pour savoir quand réessayer.

Réponse 429

429 Too Many Requests

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 0
Retry-After: 47

{
  "message": "Too Many Attempts."
}

Codes d'erreur

Toutes les erreurs retournent du JSON avec un champ message. Les erreurs de validation (422) incluent aussi un objet errors.

Statut	Signification	Cause fréquente
401	Non autorisé	Token manquant ou invalide
403	Interdit	La ressource ne vous appartient pas
404	Non trouvé	Le hash du lien n'existe pas
422	Erreur de validation	Champs invalides ou alias en double
429	Trop de requêtes	Limite de débit dépassée
500	Erreur serveur	Une erreur s'est produite de notre côté

Exemples de réponses d'erreur

JSON

# 401 Unauthorized
{ "message": "Unauthenticated." }

# 404 Not Found
{
  "error": "not_found",
  "message": "Link not found or does not belong to you."
}

# 422 Validation Error
{
  "message": "The long_url field is required.",
  "errors": {
    "long_url": [ "The long_url field is required." ]
  }
}

# 422 Unsafe URL
{
  "error": "unsafe_url",
  "message": "This URL has been flagged as unsafe."
}

Prêt à développer ?

Générez un token et effectuez votre premier appel API en quelques secondes.

Créer un compte gratuit Se connecter