Quickstart

1 Get an access token

Auth is OAuth 2.1, Authorization Code + PKCE, issued by Supabase. Authorize gibeon.io from your OAuth client, approve access on the consent screen, and pick the tenant the agent may work on. You get an access token plus a refresh token, not a static key. The full flow with every endpoint lives at www.gibeon.io/auth.md.

2 Drop it in your environment

export GIBEON_TOKEN=<access_token>

Every request goes to https://www.gibeon.io/v1 as Authorization: Bearer $GIBEON_TOKEN. The hosted MCP at https://www.gibeon.io/mcphandles its own auth, more on that in step 5.

3 List your players

Get the screens in your tenant and their online state.

curl https://www.gibeon.io/v1/players \
  -H "Authorization: Bearer $GIBEON_TOKEN"

The Node/Deno equivalent:

const res = await fetch('https://www.gibeon.io/v1/players', {
  headers: { Authorization: `Bearer ${process.env.GIBEON_TOKEN}` },
})
const { data } = await res.json()
console.log(`${data.length} screens, ${data.filter(p => p.status === 'online').length} online`)

Pick one and grab its id. You will use it in the next step.

4 Reassign content + publish

Point a screen at a different playlist. The PATCH responds with publish_required: true for content-changing fields. Until you publish, the player keeps showing the old assignment.

curl -X PATCH https://www.gibeon.io/v1/players/<player_id> \
  -H "Authorization: Bearer $GIBEON_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 $GIBEON_TOKEN"

The player picks up the new snapshot on its next heartbeat, typically within 10 seconds. Publish a single screen via /v1/players/<id>/publish or every screen in the tenant via /v1/players/publish.

5 Hook up an AI agent (MCP)

Paste this into your MCP host config to expose the 13 gibeon.io tools to Claude Desktop, Claude Code, or Cursor. The client authorizes itself via OAuth on first connect (you approve the consent screen once), so there is no token in the config:

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

Restart your client. Ask it "how many screens are online in my gibeon.io tenant?" and the agent will call list_players and report back. The client handles auth itself, no separate install.

What's next

• Full endpoint reference at www.gibeon.io/dev/reference (interactive, try-it included).
• Raw OpenAPI 3.1 spec at www.gibeon.io/v1/openapi.yaml for Postman, Bruno, Insomnia, or codegen.
• Background, limits, common errors: API en MCP

Hit a rough edge? The repo is private during the dev-portal launch. For now, mail [email protected] and we will fix it the same day where we can.