Create, preview, and evaluate Rules programmatically

Create, preview, and evaluate Rules programmatically against a Run or Asset to generate a Report and Annotations.

After completing this workflow, you can create Rules programmatically and evaluate them against a Run or Assets with a time range to generate a Report containing the resulting Annotations. You can also preview the evaluation first to confirm the result before committing to it.

Before you begin

• You have a Sift API key and your base URLs.
• You have either the ID of the Run to evaluate Rules against, or the IDs of the Assets and the time range to evaluate Rules over.

How Rule creation and evaluation works

You create Rules using the BatchUpdateRules endpoint, then evaluate them using EvaluateRulesPreview or EvaluateRules from the Rule Evaluation Service. Rules created programmatically appear in the Rules tab and are editable through the UI or the API.

Each evaluation request specifies exactly one time option (a Run, or Assets with a time range) and exactly one mode option (current Rule versions, specific Rule versions, or a Report Template).

Other clients: You can also create and evaluate Rules using the official Python, Go, or Rust client, or generate a client for another language with Buf, since all of them use the same Protocol Buffers that back the REST API.

Create a Rule

Call the BatchUpdateRules endpoint to create a Rule programmatically. Use assetConfiguration to scope the Rule to the Asset whose Channels the condition references.

curl

curl -X PUT -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" $SIFT_REST_URL/api/v1/rules:batchUpdate -d '{
  "rules": [
    {
      "name": "YOUR_RULE_NAME",
      "description": "YOUR_RULE_DESCRIPTION",
      "assetConfiguration": {
        "assetIds": ["YOUR_ASSET_ID"]
      },
      "conditions": [
        {
          "expression": {
            "calculatedChannel": {
              "expression": "$1 > 100",
              "channelReferences": {
                "$1": { "name": "YOUR_CHANNEL_NAME" }
              }
            }
          },
          "actions": [
            {
              "actionType": "ANNOTATION",
              "configuration": {
                "annotation": {
                  "annotationType": "ANNOTATION_TYPE_DATA_REVIEW"
                }
              }
            }
          ]
        }
      ]
    }
  ],
  "overrideExpressionValidation": false
}'

annotationType:

• ANNOTATION_TYPE_DATA_REVIEW creates an issue-tracking Annotation with a status workflow, the right choice for most Rule actions like this one. It can be assigned to a user, and starts as Open by default until someone marks it Failed or Accepted during review.
• ANNOTATION_TYPE_PHASE creates an informational milestone marker with no status instead, and won’t behave the same way for a condition like this.

Preview a Rule evaluation

Call the EvaluateRulesPreview endpoint to see what Annotations it would generate, without creating a Report or saving any Annotations. Use the Rule ID from the previous step, or any existing Rule you want to evaluate.

curl

curl -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" $SIFT_REST_URL/api/v1/rules/evaluate-rules:preview -d '{
  "run": {
    "id": "RUN_ID"
  },
  "rules": {
    "rules": { "ids": { "ids": ["RULE_ID"] } }
  }
}'

Ingestion ordering: If you create a Run, stream Channel data to it, and immediately call EvaluateRulesPreview, the preview can run before the streamed data finishes processing, causing a “no matching Channels found for Rule” error. To guarantee the Channels are available before evaluation, use a data import instead of streaming. The Channels are available once the import completes.

Python: Unlike the Create and Evaluate steps, the official Python client doesn’t yet have a method to preview a Rule evaluation. Support is coming soon.

Evaluate Rules against a run

Call the EvaluateRules endpoint with a Run ID and the Rule IDs from the previous steps, or any existing Rule you want to evaluate.

curl

curl -X POST -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" $SIFT_REST_URL/api/v1/rules/evaluate-rules -d '{
  "run": {
    "id": "RUN_ID"
  },
  "rules": {
    "rules": { "ids": { "ids": ["RULE_ID"] } }
  },
  "reportName": "REPORT_NAME"
}'

Asynchronous processing: It’s common for EvaluateRules to return a jobId, even when reportId is already set. This means the evaluation is still processing and createdAnnotationCount in this response isn’t final yet. Poll ListJobs with a job_id filter until the job completes to get the actual count.

Verify