Skip to content

Create a Policy

Create a Control Change Policy to set the default retries, retry interval, queueing mode and completion checks for the Control Changes sent to an Asset / Data Stream pair.

Each Asset / Data Stream pair can have one policy. Fields that you do not set use the platform default.

Reference:

Field Option Description
resource KRN The Asset / Data Stream pair the policy applies to. Required.
policy.retries Integer, 0 or more The number of retry attempts after the initial delivery. Corresponds to the Control Change request's retries field.
policy.retry_interval Integer, 1 or more The time in seconds between retry attempts. Corresponds to the Control Change request's older, deprecated timeout field.
policy.queueing.mode enqueue, next or immediate How a new Control Change is queued for the same Asset / Data Stream pair. See Queueing Mode.
policy.resource_value_check[].resource KRN The Asset / Data Stream pair observed to evaluate completion. It must belong to the same Asset and have the same data type as the policy resource.
policy.resource_value_check[].tolerance Number, 0 or more The allowed deviation (±) from the requested value.

Note

If a policy already exists for the Asset / Data Stream pair, the request returns a 409 error. Use the update guide instead.

API cURL Example
curl -X 'POST' \
'https://<url.kelvin.ai>/api/v4/control-changes/policies/create' \
-H "Authorization: Bearer <Your Current Token>" \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"resource": "krn:ad:doc_demo_plunger_01/doc_demo_closed_time_sp",
"policy": {
    "resource_value_check": [
    {
        "resource": "krn:ad:doc_demo_plunger_01/doc_demo_closed_time",
        "tolerance": 1
    }
    ],
    "retries": 3,
    "retry_interval": 150,
    "queueing": {
    "mode": "enqueue"
    }
}
}'

You will get a response with a status code of 201, similar to this;

API cURL Example Response
{
"resource": "krn:ad:doc_demo_plunger_01/doc_demo_closed_time_sp",
"policy": {
    "resource_value_check": [
    {
        "resource": "krn:ad:doc_demo_plunger_01/doc_demo_closed_time",
        "tolerance": 1
    }
    ],
    "retries": 3,
    "retry_interval": 150,
    "queueing": {
    "mode": "enqueue"
    }
},
"created": "2026-01-01T00:00:00Z",
"created_by": "krn:user:user@example.com",
"updated": "2026-01-01T00:00:00Z",
"updated_by": "krn:user:user@example.com"
}

You can set only the fields you need. This example sets only the queueing mode;

API cURL Minimal Example
curl -X 'POST' \
'https://<url.kelvin.ai>/api/v4/control-changes/policies/create' \
-H "Authorization: Bearer <Your Current Token>" \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"resource": "krn:ad:doc_demo_plunger_01/doc_demo_speed_sp",
"policy": {
    "queueing": {
    "mode": "immediate"
    }
}
}'
API Client (Python) Example
from kelvin.api.client import Client

# Login
client = Client(url="https://<url.kelvin.ai>", username="<your_username>")
client.login(password="<your_password>")

# Create Control Change Policy
response = client.control_change.create_control_change_policy(
    data={
        "resource": "krn:ad:doc_demo_plunger_01/doc_demo_closed_time_sp",
        "policy": {
            "resource_value_check": [
                {
                    "resource": "krn:ad:doc_demo_plunger_01/doc_demo_closed_time",
                    "tolerance": 1,
                }
            ],
            "retries": 3,
            "retry_interval": 150,
            "queueing": {"mode": "enqueue"},
        },
    }
)

print(response)