Eyemagnet Media API v1 — Integration Guide

Eyemagnet Media API v1 is a GraphQL API for reading media-player, scheduling, content, media-library, and reporting data. It uses an Eyemagnet bearer token to identify the caller and restrict access through scopes.

Before you start

Eyemagnet will provide the base URL and the bearer-token arrangement for the environment you are integrating with. Use the base URL exactly as supplied:

For example, if the supplied base URL is https://media.example.com/media/v1, send GraphQL requests to that URL and check https://media.example.com/media/v1/health for service health.

Authentication and scopes

Send the bearer token received from Eyemagnet in the Authorization header. The token determines both the accessible media tenant and the scopes available to the request.

Authorization: Bearer <access-token> 

Use a token issued for the media integration and request only the scopes your application needs. Common scopes are:

The API rate-limits requests per client IP. Design callers to handle 429 responses with bounded exponential backoff, and do not retry invalid tokens or credentials automatically.

Calling GraphQL

Send a JSON query and optional variables object. This JavaScript example lists players:

const response = await fetch("https://media.example.com/media/v1", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`,
  },
  body: JSON.stringify({
    query: `
      query Players($offset: Int!, $limit: Int!) {
        players(offset: $offset, limit: $limit) {
          id
          name
          width
          height
          volume
          channel { id name }
          location { id name }
        }
      }
    `,
    variables: { offset: 0, limit: 50 },
  }),
});

const { data, errors } = await response.json();
if ( !response.ok || errors?.length ) throw new Error( errors?.[ 0 ]?.message || "Media request failed" );

const players = data.players;

GraphQL responses may contain an errors array even when the HTTP request completed. Treat the requested result as successful only when it is present in data and there is no relevant error. Error objects include a numeric code, a type, message, and (where applicable) a GraphQL path.

Pagination

List operations use offset pagination. Pass offset and limit; the default limit is 100 when omitted. Start at offset: 0, then advance the offset by the number of records received. Keep page sizes practical for the requested object depth.

query Channels($offset: Int!, $limit: Int!) {
  channels(offset: $offset, limit: $limit) {
    id
    name
    ecoMode
    volume
  }
}

Common operations

Players and channels

query Player($id: ID!) {
  player(id: $id) {
    id
    name
    width
    height
    orientation
    volume
    channel { id name }
    onDemandChannels { id name }
    tags { id name }
  }
}

Content and playlists

Content is composed from templates, layers, playlists, and playlist entries. The following read operations are available:

Media library and delivery metadata

Media sources represent images, videos, messages, and websites. Use an inline fragment when requesting fields specific to a source type.

query Sources($offset: Int!, $limit: Int!) {
  sources(offset: $offset, limit: $limit) {
    id
    name
    type
    ... on Image { width height file { id name path mime } }
    ... on Video { width height duration(unit: SECONDS) file { id name path mime } }
    ... on Website { url }
    ... on Message { entries { id body(format: PLAIN) } }
  }
}

Supporting catalogues and audit data

Data and time values

IDs are GraphQL ID values and should be treated as opaque strings. Date and time fields are formatted by the API as strings. When providing date/time inputs, include an ISO-8601 offset where the operation accepts a date-time; use the API’s Date, Time, and DateTimeZone scalar definitions exposed through introspection for the exact field type.

Production checklist

• Use the base URL and media-scoped bearer token provided for the environment.
• Send the token only over HTTPS and never log it.
• Enforce least privilege: request only the scopes needed by the integration.
• Handle GraphQL errors and 429 responses explicitly.
• Use offset pagination for list operations rather than requesting an unbounded result set.
• Treat media path values as data returned by the API; do not construct or assume storage URLs from IDs.