Instead of defining your monitor placement specifications in the UI, you can also provide a YML file to specify where to place monitors programmatically. This is beneficial if you prefer to manage monitor placement through code, e.g., enforce it through your CI/CD development process.
Authenticate. For interactive use, synqcli auth login opens a browser; for CI, set up an API Client by clicking Add client with the following scopes
Edit SQL Tests
Edit Automatic Monitors
Edit Custom Monitorsand pass them as QUALITY_CLIENT_ID / QUALITY_CLIENT_SECRET
Run synqcli deploy against your YAML
Every command and flag is in the CLI reference.YAML is one of three ways to manage monitors outside the app. The
public API drives the same services directly, and an AI
assistant can create and change monitors over
MCP. A monitor deployed from YAML stays
managed by its config: the app will not edit it, and an MCP write that would
overwrite it takes an explicit extra confirmation.
Create a YAML file where you’ll be managing the monitor setup, for example, synq_monitors.yml. You can split your configuration up into multiple files and use namespaces to manage individual domains or data products independently.
Using NamespacesMonitors in one namespace are isolated from those in another, which helps you:
Avoid conflicts when multiple teams manage monitors in parallel.
Keep different pipelines or environments separate (e.g., transformation models in CI vs. external tables in prod).
Apply ownership, defaults, and alerts consistently within a group.
You can define a namespace at the top of your YAML file.
Example content of the file
version: v1beta2 is the current format. A file with no version: key is read as the
legacy flat monitors: layout, which exists for compatibility only — do not author new
files in it.
Each entry under entities: is one asset, and its id: is the full table identifier as represented in the platform. You can locate this ID by navigating to a table in the UI (using the catalog or search functionality) and copying the ID from the URL.In the example below, bq-synq-demo::nyc_taxi::financial_statement will be the ID.
Every configurable parameter, with its type and validation rules, is in the configuration reference. The same schema drives editor autocompletion — put the # yaml-language-server: line from the example above at the top of your own file.For more examples of configuring individual monitors, see the examples directory.
A monitor or test under an entities[].id targets one asset. To cover many assets by a
rule instead of naming each one, write a top-level deployment_rules: list: each entry
carries a selection, and every asset matching it is covered, including assets that start
matching later. A rule’s type: says what it deploys — table_stats for monitors,
sql_tests for the tests listed under the rule itself. See
deployment rules.deployment_rules: is read only under version: v1beta2. A file with no version: key
is read as the flat layout, which has no such key — the list is accepted, no rule
is created, and synqcli deploy reports success. Declare the version at the top of the
file before adding a rule to it.
If you navigate to the Settings menu for a monitor, you can verify that it’s created by code by seeing the Monitor was created via API and can't be managed in APP label.
