API and MCP

Once you have an access token, you can control gibeon.io entirely from code. The REST API lives at www.gibeon.io/v1. For AI tools that speak MCP (Claude Desktop, Claude Code, Cursor), the same set of actions is available at www.gibeon.io/mcp. No local install needed.

Do you only want to connect Claude, without code? Then follow Connect Claude to gibeon.io.

A working example from token to publish is in the quickstarts for Python, Node.js and Go.

What you can do with it

With one access token you work directly on your tenant:

• List screens, rename them, assign other content, trigger a publish
• Create playlists, add or remove items, change the order
• Manage sequences and schedules
• Upload and retrieve assets

The full interactive reference is at www.gibeon.io/en/dev/reference. The raw OpenAPI 3.1 spec is available at www.gibeon.io/v1/openapi.yaml. Suitable for code generation or for importing into Postman, Bruno or Insomnia.

Getting an access token

Auth runs through OAuth 2.1, Authorization Code + PKCE, issued by Supabase. There are no static keys to copy anymore.

1. Your client registers itself with the authorization server through Dynamic Client Registration (RFC 7591)
2. The client goes through the Authorization Code + PKCE flow
3. You approve access on the gibeon.io consent screen and choose the tenant the agent may work on (scope gibeon:api)
4. Your client receives a short-lived access token plus a refresh token

The full flow with every endpoint is at www.gibeon.io/auth.md. For headless or cron use, keep the refresh token and exchange it for new access tokens without having to approve again (set up once by a human).

You revoke access from the CMS under Settings → Connected apps, or through the revocation endpoint of the authorization server. Revoking takes effect immediately.

Using REST

Send the access token in the Authorization header as a Bearer token.

# List your screens
curl https://www.gibeon.io/v1/players \
  -H "Authorization: Bearer <access_token>"

# Put a screen on another playlist and publish it
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>"

Works from any language that speaks HTTPS: bash, Node, Python, Go, n8n, Zapier, Make.

Using MCP: hosted (recommended)

Paste this config into the MCP settings of your AI tool. The client authorizes itself through OAuth on the first connection: it gets a 401 with a WWW-Authenticate pointer, fetches the protected-resource metadata, registers itself (DCR) and goes through the OAuth flow. You approve the consent screen once. So there is no token in the config.

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

Config location per tool:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows/Linux
• Claude Code: .mcp.json in your project, or the global config via claude mcp
• Cursor: ~/.cursor/mcp.json

After you restart the tool, 14 gibeon.io tools appear (list_players, update_player, publish_players, create_player, create_playlist, add_playlist_item, reorder_playlist_items, …). The AI can call them directly.

Using MCP: npm package (deprecated)

There used to be a self-hosted stdio variant (@gibeon/mcp-server), but it has been retired (deprecated): it used the removed gib_live_ keys. Use the hosted MCP above, which handles authorization itself on the first connection.

Limits and good behavior

• 60 requests per minute per token. Above the limit the API returns 429 with a Retry-After header in seconds.
• Tokens are tenant-scoped. A token can never look outside the approved tenant, not even for a superadmin account.
• Publishes are free in terms of rate limit and cost. You may trigger a publish after every change. A screen with an active connection gets a signal right away and loads the new version within a few seconds; a playlist only switches at the next item. If only one screen needs to change, publish just that screen: publishing all screens restarts playback on every zone and sequence screen.
• Uploading assets takes two steps: first POST /v1/assets with metadata (you get an upload URL back), then PUT the bytes to that URL. Max 100 MB per upload.

Common errors