Create, preview, and evaluate Ad Hoc Rules

After completing this workflow, you can use the API to create, preview, and evaluate an Ad Hoc Rule for automated workflows, such as CI/CD pipelines, and generate a Report and Annotations.

Before you begin

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

How Ad Hoc Rules differ from Rules

An Ad Hoc Rule is a Rule intended for automated workflows such as CI/CD pipelines, where you create and evaluate the Rule in a single pipeline step.

Setting isExternal to true when you create a Rule marks it as an Ad Hoc Rule instead of a Rule managed through the UI.
Ad Hoc Rules don’t appear in the Rules tab, unlike Rules that aren’t Ad Hoc.
Because of that, any Report generated from an Ad Hoc Rule displays the Rule’s logic directly, so reviewers can see what was evaluated without looking it up elsewhere.
Ad Hoc Rules are always immutable once created, since they’re meant to be defined externally in source control and re-applied through your pipeline rather than edited in place. Rules that aren’t Ad Hoc stay editable.

See Rules vs Ad Hoc Rules for the full comparison and when to use each.

Other clients: You can also create and evaluate Ad Hoc 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 an Ad Hoc Rule

Call the BatchUpdateRules endpoint with isExternal set to true. Use assetConfiguration to scope the Rule to the Asset whose Channels the condition references.

curl -X PUT -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" $SIFT_REST_URL/api/v1/rules:batchUpdate -d '{
  "rules": [
    {
      "name": "YOUR_AD_HOC_RULE_NAME",
      "description": "YOUR_AD_HOC_RULE_DESCRIPTION",
      "isExternal": true,
      "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
}'

# To run these examples, install the client: pip install sift-stack-py
# These examples are written for sift-stack-py v0.19.1
import os
from dotenv import load_dotenv
from sift_client import SiftClient
from sift_client.sift_types.channel import ChannelReference
from sift_client.sift_types.rule import RuleAction, RuleActionType, RuleAnnotationType, RuleCreate

load_dotenv()

client = SiftClient(
    api_key=os.getenv("SIFT_API_KEY"),
    grpc_url=os.getenv("SIFT_GRPC_URI"),
    rest_url=os.getenv("SIFT_REST_URI"),
)

rule = client.rules.create(
    RuleCreate(
        name="YOUR_AD_HOC_RULE_NAME",
        description="YOUR_AD_HOC_RULE_DESCRIPTION",
        is_external=True,
        asset_ids=["YOUR_ASSET_ID"],
        expression="$1 > 100",
        channel_references=[
            ChannelReference(channel_reference="$1", channel_identifier="YOUR_CHANNEL_NAME"),
        ],
        action=RuleAction(
            action_type=RuleActionType.ANNOTATION,
            annotation_type=RuleAnnotationType.DATA_REVIEW,
        ),
    )
)

print(rule)

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 an Ad Hoc Rule

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.

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 an Ad Hoc Rule evaluation. Support is coming soon.

Evaluate an Ad Hoc Rule

Call the EvaluateRules endpoint with a Run ID and the Rule ID from the previous step.

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"
}'

# To run these examples, install the client: pip install sift-stack-py
# These examples are written for sift-stack-py v0.19.1
import os
from dotenv import load_dotenv
from sift_client import SiftClient

load_dotenv()

client = SiftClient(
    api_key=os.getenv("SIFT_API_KEY"),
    grpc_url=os.getenv("SIFT_GRPC_URI"),
    rest_url=os.getenv("SIFT_REST_URI"),
)

job = client.reports.create_from_rules(
    name="REPORT_NAME",
    run="RUN_ID",
    rules=["RULE_ID"],
)

report = client.reports.wait_until_complete(job=job)

print(report)

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.

Authenticate

Clients

Review

Export

Reference

Create, preview, and evaluate Ad Hoc Rules

Before you begin

How Ad Hoc Rules differ from Rules

Create an Ad Hoc Rule

Preview an Ad Hoc Rule

Evaluate an Ad Hoc Rule

Verify

​Before you begin

​How Ad Hoc Rules differ from Rules

​Create an Ad Hoc Rule

​Preview an Ad Hoc Rule

​Evaluate an Ad Hoc Rule

​Verify

Before you begin

How Ad Hoc Rules differ from Rules

Create an Ad Hoc Rule

Preview an Ad Hoc Rule

Evaluate an Ad Hoc Rule

Verify