L’API LinkHarbor en un coup d’œil

L’API REST vous permet de piloter LinkHarbor depuis vos propres programmes : créer des pages et des liens, modifier et publier des brouillons, générer des liens courts ou intégrer les statistiques à votre propre reporting. Cet article s’adresse aux développeurs et explique les règles de base valables pour chaque endpoint.

#Quelle voie choisir ?

#URL de base et versions

URL de base

https://dock.at-harbor.com – tous les endpoints du produit se trouvent sous /v1, par exemple https://dock.at-harbor.com/v1/pages.

Version

Il n’existe actuellement que la version v1. Le numéro de version fait partie du chemin.

Protocole

HTTPS uniquement.

OpenAPI

La description lisible par machine (OpenAPI 3.1) se trouve à l’adresse https://dock.at-harbor.com/openapi.yaml. Vous pouvez la charger dans Postman, Insomnia ou un générateur de code.

#Tester dans la sandbox

Pour le développement et les tests, il existe une sandbox séparée. Elle se comporte comme l’API réelle mais en est entièrement séparée : ses propres comptes, ses propres données, et rien n’arrive dans votre véritable espace de travail.

API

https://drydock.at-harbor.com, avec les mêmes chemins que ci-dessus, par exemple https://drydock.at-harbor.com/v1/pages.

Tableau de bord

https://sandbox-deck.linkharbor.com, par exemple pour créer des clés API.

Pages

Les pages publiées apparaissent sous https://<handle>.sandbox.linkharbor.com.

Compte

Votre véritable compte LinkHarbor n’y fonctionne pas. Créez un compte sandbox séparé.

La sandbox n’envoie pas d’e-mails. Si vous vous inscrivez via l’API (POST /v1/auth/register), le code de vérification revient directement dans la réponse, dans le champ _dev_verification. Il en va de même pour les réinitialisations de mot de passe et les changements d’e-mail. Ce champ n’existe que dans la sandbox : ne vous y fiez donc pas dans votre code.

• Les notifications push sont désactivées
• Les paiements passent par le mode test de Stripe, aucun argent réel ne circule
• Les limites de débit valent environ un tiers des valeurs réelles, et les nouveaux comptes sont limités à 5 par heure et par adresse IP
• Le 1er de chaque mois à 3:00 UTC, la sandbox est entièrement vidée, et tous les comptes et données disparaissent
• Chaque réponse porte l’en-tête X-Environment: sandbox

#L’authentification en bref

1. En tant que propriétaire ou admin, créez dans le tableau de bord sous « Callback et API » une clé API avec les portées nécessaires (à partir de Creator Pro)
2. Échangez l’ID et le secret de la clé contre un jeton d’accès via POST /v1/token
3. Envoyez le jeton avec chaque requête dans l’en-tête Authorization: Bearer …
4. Récupérez un nouveau jeton au bout de 15 minutes

Tous les détails figurent dans Clés API et jetons, les droits dans Portées.

#Requêtes et réponses

Format

Les requêtes et les réponses sont en JSON, encodé en UTF-8. Les téléversements de fichiers utilisent aussi multipart/form-data.

Content-Type

Envoyez l’en-tête Content-Type: application/json avec chaque requête qui a un corps. Tout autre type est refusé avec 400 bad_request – y compris celui que curl définit automatiquement pour -d lorsque cet en-tête manque.

Champs inconnus

Les champs qu’un endpoint ne connaît pas entraînent 422 validation_failed. La réponse nomme les champs inconnus.

JSON invalide

Entraîne 400 invalid_json.

Taille

Selon l’endpoint, un corps peut faire au maximum 64 Ko, 1 Mo ou 2 Mo, et un téléversement de fichier 10 Mo. Au-delà, l’API répond 413 request_too_large. Toutes les limites sont listées sous Limites de débit.

Listes

Arrivent sous forme d’objet avec le champ items, par exemple {"items":[…]}.

Création

Répond avec HTTP 201 et le nouvel ID, par exemple {"id":123}.

Actions sans valeur de retour

Répondent {"ok":true}.

Erreurs

Ont toujours un format fixe avec un code lisible par machine. Voir Format et codes d’erreur.

#Pagination

Il n’y a pas de schéma de pagination unique. La plupart des listes sont petites et reviennent complètes ; seuls quelques endpoints ont des paramètres :

Pour sort sur les liens courts, il existe created_desc, created_asc, redirects_desc et redirects_asc ; q recherche dans le slug, le titre et l’URL cible (jusqu’à 100 caractères, sans tenir compte de la casse). Pour les statistiques, period accepte 24h, 7d, 30d, 90d, this_month, last_month, last_30d et custom ; vous pouvez aussi passer from et to. granularity vaut hour ou day.

#ID de requête et langue

• Chaque réponse porte l’en-tête X-Request-Id – indiquez-le quand vous contactez le support
• Si vous envoyez vous-même un en-tête X-Request-Id, l’API l’utilise
• Le texte d’erreur dans message est dans la langue du compte du propriétaire de l’espace de travail, sinon il suit Accept-Language ; le code dans error reste toujours le même

#Appeler l’API depuis le navigateur ?

Techniquement, l’API autorise les appels depuis le navigateur (CORS). Mais un secret de clé n’a jamais sa place dans du code exécuté côté visiteur – ni dans un site web ni dans une app. Appelez toujours l’API depuis votre propre serveur.

#Offres

Il n’y a pas de quota d’appels API par offre. Seules les limites de débit par minute s’appliquent. Les limites de contenu de votre offre – comme les pages, liens ou blocs par page – s’appliquent via l’API comme dans le tableau de bord. Voir Comparatif des offres.

#Votre premier appel

# Échanger la clé contre un jeton
curl -X POST https://dock.at-harbor.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key_id":"6F668EA6598B0692","key_secret":"lt_…"}'
# → {"token":"eyJ…","expires_in":900}

export LH_TOKEN="eyJ…"

# Lister les pages (portée read:pages)
curl https://dock.at-harbor.com/v1/pages \
  -H "Authorization: Bearer $LH_TOKEN"

Un exemple complet qui ajoute un lien, modifie le design et publie se trouve dans Mettre à jour une page via l’API.