API en MCP

gibeon.io kan vanaf een sleutelpaar volledig vanuit code aangestuurd worden. De REST API zit op api.gibeon.io/v1. Voor AI-tools die MCP spreken (Claude Desktop, Claude Code, Cursor) staat dezelfde set acties klaar op api.gibeon.io/mcp. Geen lokale install nodig.

Wat kan je ermee

Met één API-sleutel 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 api.gibeon.io/v1/openapi.yaml. Geschikt voor code-generatie of import in Postman, Bruno, Insomnia.

Een API-sleutel aanmaken

1. Open de CMS op app.gibeon.io
2. Ga naar Instellingen → API
3. Klik Nieuwe sleutel, kies een naam (bijvoorbeeld n8n integratie of Claude Code laptop) en bevestig
4. Kopieer de getoonde gib_live_… waarde meteen. Die wordt maar één keer getoond. Daarna bewaart gibeon.io enkel de hash.
5. Plak de sleutel waar je hem nodig hebt (.env, MCP-host config, etc.)

Sleutels zijn intrekbaar via dezelfde pagina. Een ingetrokken sleutel werkt onmiddellijk niet meer.

REST gebruiken

Stuur de sleutel mee in de Authorization header als Bearer token.

# Lijst van je schermen
curl https://api.gibeon.io/v1/players \
  -H "Authorization: Bearer gib_live_..."

# Een scherm op een andere playlist zetten en publishen
curl -X PATCH https://api.gibeon.io/v1/players/<player_id> \
  -H "Authorization: Bearer gib_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "playlist_id": "<playlist_id>" }'

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

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 en vervang gib_live_… door je echte sleutel.

{
  "mcpServers": {
    "gibeon": {
      "url": "https://api.gibeon.io/mcp",
      "headers": {
        "Authorization": "Bearer gib_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

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 (fallback)

Voor MCP-clients die nog geen remote-transport ondersteunen, draait dezelfde toolset als lokaal stdio-proces via @gibeon/mcp-server.

{
  "mcpServers": {
    "gibeon": {
      "command": "npx",
      "args": ["-y", "@gibeon/mcp-server"],
      "env": {
        "GIBEON_API_KEY": "gib_live_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Vereist Node 20 of hoger op de machine waar de MCP-host draait.

Limieten en goed gedrag

• 60 requests per minuut per sleutel. Boven de limiet retourneert de API 429 met een Retry-After header in seconden.
• Sleutels zijn tenant-scoped. Een sleutel kan nooit buiten zijn eigen 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