API et MCP

gibeon.io se pilote entièrement par code dès que vous avez un access token. L’API REST se trouve sur www.gibeon.io/v1. Pour les outils IA qui parlent MCP (Claude Desktop, Claude Code, Cursor), le même ensemble d’actions est disponible sur www.gibeon.io/mcp. Aucune installation locale n’est nécessaire.

Vous voulez seulement connecter Claude, sans code ? Suivez alors Connecter Claude à gibeon.io.

Un exemple complet, du token à la publication, figure dans les quickstarts pour Python, Node.js et Go.

Ce que vous pouvez faire

Avec un seul access token, vous travaillez directement sur votre tenant :

• Lister les écrans, les renommer, leur attribuer un autre contenu, déclencher une publication
• Créer des playlists, ajouter ou supprimer des éléments, changer l’ordre
• Gérer les séquences et les planifications
• Téléverser et consulter des assets

La référence interactive complète se trouve sur www.gibeon.io/fr/dev/reference. La spécification OpenAPI 3.1 brute est disponible sur www.gibeon.io/v1/openapi.yaml. Elle convient à la génération de code ou à l’import dans Postman, Bruno ou Insomnia.

Obtenir un access token

L’authentification passe par OAuth 2.1, Authorization Code + PKCE, émis par Supabase. Il n’y a plus de clés statiques à copier.

1. Votre client s’enregistre auprès du serveur d’autorisation via Dynamic Client Registration (RFC 7591)
2. Le client suit le flux Authorization Code + PKCE
3. Vous approuvez l’accès sur l’écran de consentement de gibeon.io et choisissez le tenant sur lequel l’agent peut travailler (scope gibeon:api)
4. Votre client reçoit un access token de courte durée et un refresh token

Le flux complet, avec chaque endpoint, est décrit sur www.gibeon.io/auth.md. Pour un usage headless ou cron, conservez le refresh token et échangez-le contre de nouveaux access tokens sans devoir approuver à nouveau (une seule configuration, faite par une personne).

Vous retirez l’accès depuis le CMS sous Paramètres → Applications connectées, ou via l’endpoint de révocation du serveur d’autorisation. La révocation prend effet immédiatement.

Utiliser REST

Envoyez l’access token dans l’en-tête Authorization, comme Bearer token.

# Liste de vos écrans
curl https://www.gibeon.io/v1/players \
  -H "Authorization: Bearer <access_token>"

# Mettre un écran sur une autre playlist et le publier
curl -X PATCH https://www.gibeon.io/v1/players/<player_id> \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "playlist_id": "<playlist_id>" }'

curl -X POST https://www.gibeon.io/v1/players/<player_id>/publish \
  -H "Authorization: Bearer <access_token>"

Cela fonctionne depuis tout langage qui parle HTTPS : bash, Node, Python, Go, n8n, Zapier, Make.

Utiliser MCP : hébergé (recommandé)

Collez cette configuration dans les paramètres MCP de votre outil IA. Le client s’autorise lui-même via OAuth à la première connexion : il reçoit un 401 avec un pointeur WWW-Authenticate, récupère les métadonnées de la ressource protégée, s’enregistre (DCR) et déroule le flux OAuth. Vous approuvez l’écran de consentement une seule fois. Il n’y a donc aucun token dans la configuration.

{
  "mcpServers": {
    "gibeon": {
      "url": "https://www.gibeon.io/mcp"
    }
  }
}

Emplacement de la configuration selon l’outil :

• Claude Desktop : ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou l’équivalent sous Windows/Linux
• Claude Code : .mcp.json dans votre projet, ou la configuration globale via claude mcp
• Cursor : ~/.cursor/mcp.json

Après un redémarrage de l’outil, 14 outils gibeon.io apparaissent (list_players, update_player, publish_players, create_player, create_playlist, add_playlist_item, reorder_playlist_items, …). L’IA peut les appeler directement.

Utiliser MCP : paquet npm (obsolète)

Il existait une variante stdio auto-hébergée (@gibeon/mcp-server), mais elle a été retirée (deprecated) : elle utilisait les clés gib_live_, qui n’existent plus. Utilisez le MCP hébergé ci-dessus, qui gère l’autorisation lui-même à la première connexion.

Limites et bonnes pratiques

• 60 requêtes par minute et par token. Au-delà de la limite, l’API renvoie 429 avec un en-tête Retry-After en secondes.
• Les tokens sont limités à un tenant. Un token ne peut jamais voir en dehors du tenant approuvé, même avec un compte superadmin.
• Les publications sont gratuites en termes de limite de débit et de coûts. Vous pouvez déclencher une publication après chaque modification. Un écran avec une connexion active reçoit aussitôt un signal et charge la nouvelle version en quelques secondes ; une playlist ne change qu’à l’élément suivant. Si un seul écran doit changer, ne publiez que celui-là : une publication de tous les écrans redémarre l’affichage sur chaque écran en zones et en séquence.
• Le téléversement d’assets se fait en deux étapes : d’abord POST /v1/assets avec les métadonnées (vous recevez une URL de téléversement), puis PUT des octets vers cette URL. 100 Mo maximum par téléversement.

Erreurs courantes