How to create, preview, and evaluate an external Rule using the Sift API
Overview
The Sift API allows you to create external Rules programmatically. External Rules are ideal for automated workflows such as CI/CD pipelines, where external Rules are managed and evaluated programmatically. An external Rule can be created using the BatchUpdateRules endpoint with the isExternal flag set to true. External Rules are not shown in the Rules section of the Sift web application.
A Report containing an external Rule displays the Rule's logic, and any Annotations generated are visible from the Annotations tab or the Explore view.
You can use the following two endpoints to evaluate an external Rule:
EvaluateRulesPreview: Previews (simulates) external or internal Rules against a Run and returns the Annotations that would be created, without saving any results.EvaluateRules: Evaluates external or internal Rules against a Run or Asset and generates persistent results, including a Report with Annotations triggered by the Rules.
Note
This guide uses the Sift REST API for all examples. The same functionality is also available through the gRPC API, which supports official client libraries in Python, Go, and Rust.
- For full message schemas and service definitions, see gRPC API.
- For client installation details (Python, Go, Rust), see Client Libraries.
Step 1: Create an external Rule
To create an external Rule, use the BatchUpdateRules endpoint and set the isExternal flag to true. This enables a Rule to be created and evaluated ad hoc and simultaneously, which is ideal for a Rule triggered by CI/CD workflows.
Note
Once an external Rule is created, it cannot be edited through the UI or API. Only non-external Rules can be modified.
Step 2: Preview an external Rule
Before evaluating an external Rule, you can preview what Annotations would be generated using the EvaluateRulesPreview endpoint. This allows you to validate an external Rule's logic without creating a Report or saving any Annotations.
Step 3: Evaluate an external Rule
To apply an external Rule to a specific Run or Asset, use the EvaluateRules endpoint. This evaluates the Rule logic, generating a Report and potential Annotations.