API en MCP

gibeon.io is volledig vanuit code aanstuurbaar zodra je een access token hebt. De REST API zit op www.gibeon.io/v1. Voor AI-tools die MCP spreken (Claude Desktop, Claude Code, Cursor) staat dezelfde set acties klaar op www.gibeon.io/mcp. Geen lokale install nodig.

Wat kan je ermee

Met één access token werk je rechtstreeks op je tenant:

• Schermen oplijsten, hernoemen, andere content toewijzen, een publish triggeren
• Playlists aanmaken, items toevoegen of verwijderen, volgorde wijzigen
• Sequenties en planningen beheren
• Assets uploaden en opvragen

De volledige interactieve reference staat op www.gibeon.io/dev/reference. De raw OpenAPI 3.1-spec is bereikbaar op www.gibeon.io/v1/openapi.yaml. Geschikt voor code-generatie of import in Postman, Bruno, Insomnia.

Een access token ophalen

Auth verloopt via OAuth 2.1, Authorization Code + PKCE, uitgegeven door Supabase. Er zijn geen statische sleutels meer om te kopiëren.

1. Je client registreert zich via Dynamic Client Registration (RFC 7591) bij de authorization server
2. De client doorloopt de Authorization Code + PKCE-flow
3. Je keurt de toegang goed op het gibeon.io consent-scherm en kiest de tenant waarop de agent mag werken (scope gibeon:api)
4. Je client krijgt een kortlevend access token plus een refresh token

De volledige flow met elk endpoint staat op www.gibeon.io/auth.md. Bewaar voor headless of cron-gebruik het refresh token en wissel het in voor nieuwe access tokens zonder opnieuw te moeten goedkeuren (één keer ingesteld door een mens).

Toegang trek je in vanuit de CMS onder Instellingen → Verbonden apps, of via het revocation-endpoint van de authorization server. Intrekken werkt onmiddellijk.

REST gebruiken

Stuur het access token mee in de Authorization header als Bearer token.

# Lijst van je schermen
curl https://www.gibeon.io/v1/players \
  -H "Authorization: Bearer <access_token>"

# Een scherm op een andere playlist zetten en publishen
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>"

Werkt vanuit elke taal die HTTPS spreekt: bash, Node, Python, Go, n8n, Zapier, Make.

MCP gebruiken: hosted (aanbevolen)

Plak deze config in de MCP-instellingen van je AI-tool. De client autoriseert zichzelf via OAuth bij de eerste verbinding: hij krijgt een 401 met een WWW-Authenticate-pointer, haalt de protected-resource-metadata op, registreert zichzelf (DCR) en doorloopt de OAuth-flow. Jij keurt het consent-scherm één keer goed. Er staat dus geen token in de config.

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

Configuratie-locatie per tool:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) of de equivalent op Windows/Linux
• Claude Code: .mcp.json in je project, of de globale config via claude mcp
• Cursor: ~/.cursor/mcp.json

Na een herstart van de tool verschijnen er 13 gibeon.io-tools (list_players, update_player, publish_players, create_playlist, add_playlist_item, reorder_playlist_items, …). De AI kan ze rechtstreeks aanroepen.

MCP gebruiken: npm-pakket (deprecated)

Er bestond een self-hosted stdio-variant (@gibeon/mcp-server), maar die is afgebouwd (deprecated): ze gebruikte de verwijderde gib_live_-sleutels. Gebruik de hosted MCP hierboven, die de autorisatie zelf afhandelt bij de eerste verbinding.

Limieten en goed gedrag

• 60 requests per minuut per token. Boven de limiet retourneert de API 429 met een Retry-After header in seconden.
• Tokens zijn tenant-scoped. Een token kan nooit buiten de goedgekeurde tenant kijken, ook niet als superadmin-account.
• Publishes zijn gratis in termen van rate-limit en kosten. Je mag na elke wijziging een publish triggeren. Players halen het pas binnen op hun volgende heartbeat, dat is altijd binnen 10 seconden.
• Assets uploaden gaat in twee stappen: eerst POST /v1/assets met metadata (krijg een upload-URL terug), dan PUT de bytes naar die URL. Max 100 MB per upload.

Veelvoorkomende fouten