GraphQL

The read-only GraphQL surface behind query_data: corrected examples, pagination, aggregate fields, and the full query catalog.

Agents query AssureSwarm through the query_data MCP tool, which accepts read-only GraphQL: mutations and subscriptions are rejected. The catalog below is the same one returned live by get_schema as queryReference; prefer the live version when in doubt, since item types and their fields are tenant-specific.

Ground Rules

Call get_schema first and reuse the exact item type slugs and field keys it returns.
Use GraphQL variables, not string interpolation, for any value that comes from user input or a prior tool result.
Select only the fields you need: tool responses are capped at 2 MB.
Item lists are paginated; read total and totalPages instead of assuming one page holds everything.
Prefer the aggregate and stats fields below for counting or summarizing: don’t page through every item to count it yourself.
Writes never happen through GraphQL; propose them with suggest_change instead.

Core Examples

These four shapes are verified against the live schema.

List item types:

query ListItemTypes {
  itemTypes {
    slug
    name
  }
}

Inspect one item type’s fields:

query ItemTypeFields($slug: String!) {
  itemType(slug: $slug) {
    slug
    name
    fields {
      fieldKey
      label
      fieldType
      required
    }
  }
}

List items: items returns a paginated object, select rows via the inner items field:

query OpenIssues($itemType: String!, $limit: Int) {
  items(itemType: $itemType, limit: $limit) {
    items {
      id
      title
      status
    }
    total
    page
    totalPages
  }
}

with variables:

{ "itemType": "issue", "limit": 10 }

total is always the full matching count, regardless of limit or page.

Count and break down without paging:

query ItemCounts($itemType: String) {
  itemStats(itemType: $itemType) {
    totalCount
    overdueCount
    byStatus {
      group
      label
      count
    }
  }
}

Aggregate and Report Fields

Six fields answer the questions you’d otherwise have to page through every record to answer by hand:

Field	Answers	Returns
`itemStats(itemType?)`	Counts and breakdowns by status, owner, and item type	`ItemStats { totalCount, overdueCount, byStatus, byOwner, byItemType }`
`workflowStats(itemType?, status?)`	Workflow and step progress, including overdue steps	`WorkflowStats { totalWorkflows, totalSteps, overdueSteps, byStatus, stepsByStatus, stepsByAssignee, averageStepsPerWorkflow }`
`suggestionStats(agentId?)`	Agent suggestion volume and approval rate	`SuggestionStats { totalCount, approvalRate, byStatus, byOperation, byAgent, byItemType }`
`timeEntryStats(weekStart?, userId?)`	Logged-time totals and breakdowns	`TimeEntryStats { totalHours, pendingApprovalCount, byUser, byItem, byWeek }`
`dueDateReport(daysAhead?, includeItems?, includeSteps?)`	What’s overdue or coming up	`DueDateReport { overdueItems, overdueSteps, upcomingItems, upcomingSteps }`
`teamWorkloadStats(itemTypes?)`	Open work broken down by person	`TeamWorkloadStats { totalSteps, stepsByStatus, stepsByAssignee, stepDetails }`

Breakdown (by*) entries are shaped { group, label, count }. Time breakdowns use value in place of count for hours.

Query Catalog

The complete set of queries the schema exposes, grouped by area and matching get_schema’s live queryReference.

Identity and Context

Signature	Purpose
`viewer`	The authenticated identity and auth metadata
`myContext`	The user’s most recent page context
`myPageAccess`	The user’s page grants
`hasPageAccess(pageName)`	Whether the user can access a given page

Schema

Signature	Purpose
`itemTypes(includeInactive?, includeInactiveFields?)`	List all item types
`itemType(slug, includeInactive?, includeInactiveFields?)`	One item type by slug
`itemTypeWithFields(slug, includeInactive?, includeInactiveFields?)`	One item type with its full field list

Items

Signature	Purpose
`items(itemType, status?, ownerId?, createdById?, search?, fieldFilters?, page?, limit?)`	Paginated item list; `fieldFilters` takes `[{ fieldKey, fieldType, values: [..] }]`
`item(id)`	One item by ID
`itemWithRelations(id)`	One item with its relationships
`itemActivityLogs(itemId, itemType, limit?)`	Activity history for an item
`searchItems(query?, search?, itemType?, page?, limit?, take?)`	Search across items
`myItems(page?, limit?)`	Items you own
`mySharedItems(page?, limit?)`	Items shared with you
`allItems(status?, ownerId?, overdue?, search?, skip?, take?)`	Items across item types
`itemStats(itemType?)`	Counts and breakdowns for items

Relationships and Links

Signature	Purpose
`itemRelationships(itemType, itemId)`	Relationships attached to an item
`stepItemLinks(stepId)`	Items linked to a step
`stepLinkedEntities(stepIds)`	Entities linked to a set of steps

Workflows and Steps

Signature	Purpose
`myWorkflows(includeCompleted?, take?)`	Workflows you’re involved in
`myAssignedSteps(includeCompleted?, take?)`	Steps awaiting your approval: assignment is via approvals, not an assignee
`workflow(id)`	One workflow by ID
`workflows(itemType, itemId, skip?, take?)`	Workflows for an item
`workflowTemplate(id)`	One workflow template by ID
`workflowTemplates(skip?, take?, itemTypeId?, isActive?, isPublic?)`	List workflow templates: `take` is capped at 100; page with `skip`
`step(id)`	One step by ID
`stepByDiagramNode(workflowId, diagramNodeId)`	The step for a diagram node
`stepApprovers(stepId)`	The approvers for a step
`workflowNodeState(workflowId, nodeId)`	State of a diagram node
`allSteps(status?, nameContains?, overdue?, workflowStatus?, skip?, take?)`	Steps across workflows
`allWorkflows(itemType?, status?, ownerId?, skip?, take?)`	Workflows across item types
`workflowStats(itemType?, status?)`	Workflow and step progress

Documents

Signature	Purpose
`stepDocumentDownloadUrl(documentId)`	A download URL for a step document
`stepDocumentDownload(documentId)`	Download data for a step document

Forms

Signature	Purpose
`myFormAssignments`	Forms assigned to you
`formAssignmentsByStep(stepId)`	Form assignments for a step
`previewFormAssignments(stepId, emails)`	Preview form assignments before sending
`formStatusReport`	Status of form assignments

Suggestions

Signature	Purpose
`suggestion(id)`	One suggestion by ID
`mySuggestions(status?, itemType?, skip?, take?)`	Suggestions you created
`myPendingSuggestions(skip?, take?)`	Your suggestions still pending review
`suggestionsForItem(itemType, itemId, skip?, take?)`	Suggestions targeting an item
`myPendingSuggestionCount`	Count of your pending suggestions
`mySuggestionStatusCounts`	Your suggestion counts by status
`suggestionStats(agentId?)`	Suggestion volume and approval rate
`suggestionsByUser`	Suggestion counts by user
`suggestionsTimeline`	Suggestion activity over time

Dashboards and Visualization

Signature	Purpose
`dashboards(skip?, take?)`	List dashboards
`dashboard(id)`	One dashboard by ID
`activityTimeline(itemTypes?, actions?, fieldFilters?, startDate?, endDate?, limit?, offset?)`	Activity events over a date range
`universeData(includeSteps?)`	Data behind the Universe dashboard
`universeActivity(startDate, endDate)`	Universe activity over a date range

Time Keeping

Signature	Purpose
`myTimeEntries(weekStart)`	Your time entries for a week
`myWeeklyTimesheet(weekStart)`	Your timesheet for a week
`timeEntry(id)`	One time entry by ID
`timeEntries(userId?, itemId?, weekStart?, status?, skip?, take?)`	Time entries across users and items
`pendingTimeApprovals(skip?, take?)`	Time entries awaiting your approval
`timeEntryStats(weekStart?, userId?)`	Logged-time totals and breakdowns

People

Signature	Purpose
`users(itemType?, itemId?, search?, searchQuery?, skip?, take?, role?, includeInactive?, includeExternal?)`	List users
`entityPersonnel(entityType, entityId)`	People associated with an entity
`itemRoles(itemType, itemId)`	Roles on an item
`itemRoleCount(itemType, itemId)`	Count of roles on an item

Custom Lists

Signature	Purpose
`customList(id)`	One custom list by ID
`customLists(category?, includeInactive?, isSystem?, searchQuery?, skip?, take?)`	List custom lists
`customListValues(category)`	Values in a custom list category
`customListCategories`	All custom list categories
`customListByValue(category, value)`	Look up a custom list entry by its value

Settings and Administration

Signature	Purpose
`systemSettings(category?)`	System settings, optionally by category
`systemSetting(key)`	One system setting by key
`systemSettingCategories`	Available setting categories
`brandingSettings`	Tenant branding settings
`featureSettings`	Feature toggles
`allowedSsoDomains`	Email domains allowed to sign in via SSO
`oauthClients(includeInactive?)`	Registered OAuth clients
`oauthClient(id)`	One OAuth client by ID
`popularOAuthClients`	Commonly used OAuth clients
`adminActivityLogs(entityTypes?, actionTypes?, userId?, startDate?, endDate?, limit?, offset?)`	Admin activity history
`adminEntityTypes`	Entity types available to admin activity filters
`userPageAccess(userId)`	A user’s page access grants
`userItemPermissions(userId)`	A user’s item permissions

Reports and Exports

Signature	Purpose
`dueDateReport(daysAhead?, includeItems?, includeSteps?)`	What’s overdue or coming up
`teamWorkloadStats(itemTypes?)`	Open work broken down by person
`dataExport(exportId)`	Fresh signed download link for a prior query_data export

Access Notes

Every query runs as the connected user, under their permissions and the token’s scopes. Some fields are admin-flavored and require access you may not have: they fail or return nothing for non-admins. Treat those denials as expected, not as bugs.