GraphQL Queries

GraphQL is the preferred path for reading data from Revel Digital. Unlike the REST list_* / get_* tools, a single GraphQL query supports field selection, filtering, sorting, and combined lookups in one round-trip — so the AI fetches exactly what it needs and nothing more.

The REST read tools still work, but where GraphQL covers them they are marked [DEPRECATED] and steer you here. Mutations (create / update / delete) remain on REST, except for a few GraphQL-only operations with no REST equivalent.

Workflow

introspect_schema — discover operations, arguments, and exact field names (case-sensitive). Always call this first.
build_query or quick_query — construct the query.
execute_query — run it. Large responses are automatically trimmed to fit the AI context window.

introspect_schema

Discover available GraphQL operations, types, fields, and arguments. Call this before building queries — field names are case-sensitive and differ between types. Three modes:

No arguments → list all operations with their arguments and filter types.
operation → details for one operation (arguments, return type, field presets).
typeName → live schema introspection for a GraphQL type (fields, args, enums).

Parameter	Type	Required	Description
`operation`	string	No	Operation name, e.g. `device`, `mediaPlayStats` — returns its args, return type, and field presets
`typeName`	string	No	GraphQL type name, e.g. `Device`, `Media` — returns the live field list

build_query

Construct an optimized GraphQL query with field selection, filtering, and sorting. Returns { query, variables } ready to pass to execute_query. Filter operators: eq, neq, contains, startsWith, endsWith, in, gt, gte, lt, lte; combine with { "and": [...] } / { "or": [...] }.

Parameter	Type	Required	Description
`operation`	enum	Yes	The operation, e.g. `device`, `media`, `playlist`, `schedule`, `deviceMetrics`, `playLogs`, `dataTableRows`
`fields`	string[]	No	Fields to select. Dot notation (`pingData.cpuUsage`) or nested syntax (`pingData { cpuUsage }`)
`preset`	enum	No	Predefined field set: `minimal`, `basic`, `status`, `location`, `full`
`filter`	object	No	Filter conditions, e.g. `{"isOnline": {"eq": true}}`
`orderBy`	string	No	Field to sort by
`orderDirection`	`ASC` \| `DESC`	No	Sort direction (default `ASC`)
`limit`	number	No	Maximum results
`startDate` / `endDate`	string	No	Full ISO 8601 datetimes — required for analytics and raw-log operations
`deviceId` / `fileId`	string[]	No	Filter analytics/log operations by device or file ID(s)
`interval`	enum	No	Aggregation interval: `MINUTE`, `HOUR`, `DAY`, `WEEK`, `MONTH`
`tableId` / `rowId` / `version`	string / number	No	Data-table row operations
`timeZone`	string	No	`dataTableRows` only — Windows or IANA time zone id used to evaluate the relative date filters (`isToday`, `beforeNow`, `afterNow`). Defaults to the account time zone
`tag`	string[]	No	Filter content operations by tag(s)

Many operations accept additional arguments (groupByDevice, eventName, minDwellThreshold, gender, type, pagination, …). Run introspect_schema with the operation parameter to see the full list for a given operation.

execute_query

Execute a GraphQL query against the Revel Digital API. Typically you produce the query with build_query or quick_query first. Large responses are optimized to fit AI context windows; metadata flags any truncation so you can narrow the query.

Parameter	Type	Required	Description
`query`	string	Yes	The GraphQL query string to execute
`variables`	object	No	Query variables as a JSON object
`operationName`	string	No	Required only if the query contains multiple operations

quick_query

Execute a pre-built query for a common task — faster than building a custom query when one of these shapes fits.

Parameter	Type	Required	Description
`queryType`	enum	Yes	One of the pre-built queries below
`limit`	number	No	Max results (applies to `recent_media`, default 50)

Available queryType values:

Value	Returns
`device_counts`	Aggregated totals: total / online / offline / inSync / outOfSync / active / deactivated
`devices_status`	Device health overview with ping data
`online_devices`	Currently connected devices
`in_sync_devices` / `out_of_sync_devices`	Devices by content sync state
`recent_media`	Most recently uploaded media
`active_schedules`	`PLAYLIST` / `TEMPLATE` schedules whose `startDate`..`endDate` window covers today (UTC) and whose weekday flag is not `false`. Evaluated in the MCP, since `Schedule` has no `isActive` field and string dates cannot be range-filtered. Time-of-day is not considered. Disclaimer: `CAMPAIGN` (Smart) schedules are rule-driven and are not evaluated — they are returned as-is and counted in `metadata.campaignSchedulesNotEvaluated`
`permissions`	Current user / API-key capabilities and allowed mutations
`display_commands`	Device commands available for this account

Back to Home