Eyemagnet Media API v2 — Trigger Integration Guide

Eyemagnet Media API v2 publishes commands to media players. Its public integration surface is the trigger GraphQL mutation.

Before you start

Eyemagnet will provide the base URL and bearer-token arrangement for the environment. Use the supplied base URL exactly as given:

Send an Eyemagnet bearer token in the Authorization header. The token needs the modify players scope. Its first audience value (aud[0]) selects the active team, and triggers are published only to players in that team.

Authorization: Bearer <access-token> 

Pass ids to target one or more player IDs. Omit it to publish to every listening player in the active team. The API accepts an ID for value, which means a string, numeric ID, or a JSON document encoded as a string can be supplied. Always pass a type, even though the current schema marks it nullable.

Publish a trigger

The mutation returns true after the event has been published. It does not confirm that a player was connected, received the event, or completed the action.

const response = await fetch("https://media.example.com/media/v2", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    query: `
      mutation Trigger($ids: [ID!], $type: TriggerType!, $value: ID) {
        trigger(ids: $ids, type: $type, value: $value)
      }
    `,
    variables: {
      ids: ["player_123"],
      type: "RELOAD",
      value: null,
    },
  }),
});

const { data, errors } = await response.json();
if ( !response.ok || errors?.length || data?.trigger !== true ) {
  throw new Error( errors?.[ 0 ]?.message || "Trigger was not published" );
}

GraphQL may return an errors array even when the HTTP request completes. Do not retry destructive triggers such as REBOOT, CLEAR, or update commands automatically.

Trigger types and values

value is omitted unless a value is shown below. For JSON values, stringify the object or array before passing it as the GraphQL variable. Player software varies by platform and release; use commands only with player families that support the intended action.

Production checklist

• Use HTTPS and send the bearer token only in the Authorization header.
• Obtain a token for the team whose players you intend to target.
• Grant only the modify players scope required for trigger publishing.
• Target explicit player IDs for disruptive commands whenever possible.
• Treat a true response as publication confirmation, not device completion.
• Handle GraphQL errors, 401, 403, and network timeouts explicitly.