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

  1. introspect_schema — discover operations, arguments, and exact field names (case-sensitive). Always call this first.
  2. build_query or quick_query — construct the query.
  3. 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:

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
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 Currently active schedules
permissions Current user / API-key capabilities and allowed mutations
display_commands Device commands available for this account

Back to Home