Skip to main content

Queries, Mutations, And Filtering

Most SVRunner API resources follow a consistent GraphQL pattern for reading lists, reading a single object, and creating or updating data. This page explains those patterns so you can move across domains without relearning the API each time.

Common Resource Pattern​

Many resource groups expose:

  • a single-item query by id
  • a list or list-like query with pagination and filtering
  • create, update, and delete mutations

Examples include users, assets, asset blocks, tags, players, and other core resources.

Single-Item Queries​

Single-item queries usually look like this:

query GetUser($id: Int!) {
  user(id: $id) {
    id
    username
    role
  }
}

The important pattern is:

  • the field name is usually the singular resource name
  • the lookup argument is commonly id: Int!

List Queries​

List-style queries commonly accept some or all of these arguments:

  • where
  • offset
  • limit
  • sort

Example:

query ListUsers(
  $where: UsersWhereInput
  $offset: Int
  $limit: Int
  $sort: SortInput
) {
  users(where: $where, offset: $offset, limit: $limit, sort: $sort) {
    items {
      id
      username
      role
    }
    count
  }
}

The return shape often includes:

  • items: the current page of resources
  • count: the total number of matching resources

Pagination​

Pagination is generally offset-based.

  • offset selects the starting position
  • limit controls the number of results returned

Example variables:

{
  "offset": 0,
  "limit": 25
}

Filtering​

Filtering is typically done through a resource-specific where input.

The exact shape varies by resource type, but the pattern is consistent: pass a nested input object describing the fields to match.

Example:

{
  "where": {
    "firstName": {
      "contains": "Nat"
    }
  }
}

Not every resource supports the same fields or operators, so check the schema for the specific *WhereInput type you are using.

Sorting​

Sorting is commonly exposed through a shared SortInput.

Typical usage includes:

  • a field or key name
  • an order direction such as ascending or descending

Because the exact structure is schema-driven, inspect the generated schema or GraphQL explorer when building a new integration.

Mutations​

Create and update mutations usually follow one of these shapes:

mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    id
    username
  }
}
mutation UpdateUser($id: Int!, $input: UpdateUserInput!) {
  updateUser(id: $id, input: $input) {
    id
    username
  }
}

Delete mutations commonly take an id, and some resources also expose batch deletion patterns.

Resource Groups To Expect​

The schema is organized around product domains rather than a small generic object set. Major areas include:

  • content: assets, asset blocks, tags, extensions, filter presets
  • scheduling: events, sequences, actions, schedule preview, Quick Play
  • playback topology: players, screens, targets, outputs, layouts
  • administration: users, projects, licenses, systems, logs

Domain-Specific Queries And Mutations​

Some API operations are more specialized than basic CRUD.

Examples include:

  • schedulePreview for generated playlist inspection
  • Quick Play enable and disable mutations
  • license activation flows
  • log and reporting queries
  • schema-driven extension and action helpers

These are the operations most likely to matter to integrators automating production behavior rather than just managing records.

Practical Guidance For Integrators​

When exploring a new SVRunner resource:

  1. find the singular query
  2. find the list query
  3. inspect the where input type
  4. inspect the create and update input types
  5. confirm whether the resource also exposes subscriptions or domain-specific helpers

API Query Filtering Example Stub screenshot: code sample from GraphQL Playground or another API client showing a list query with where, offset, limit, and sort. Save final image at packages/docs/screenshots/api-query-filtering-example.png.

This approach works well across most of the schema.

Common Mistakes​

  • assuming all list fields return the same result shape without checking the schema
  • guessing filter operators instead of inspecting the specific where input
  • assuming every resource supports batch operations
  • treating domain-specific operations like schedulePreview as if they were normal CRUD endpoints