Skip to content

Update a Policy

Update the Control Change Policy of an Asset / Data Stream pair.

Warning

An update replaces the full policy. Any field you leave out of the request is unset in the policy and is resolved at runtime from the Control Change request or the platform default. Leaving out resource_value_check removes all its completion checks.

Reference:

Field Option Description
resource KRN The Asset / Data Stream pair of the policy, in the path of the request. In the Kelvin API request it must be URL-encoded. 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.

The KRN in the path must be URL-encoded. In this example krn:ad:doc_demo_plunger_01/doc_demo_closed_time_sp becomes krn%3Aad%3Adoc_demo_plunger_01%2Fdoc_demo_closed_time_sp.

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

You will get a response with a status code of 200, 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": "next"
    }
},
"created": "2026-01-01T00:00:00Z",
"created_by": "krn:user:user@example.com",
"updated": "2026-01-02T00:00:00Z",
"updated_by": "krn:user:user@example.com"
}

To remove all completion checks and keep only the retries, send an empty resource_value_check list;

API cURL Remove Checks Example
curl -X 'POST' \
'https://<url.kelvin.ai>/api/v4/control-changes/policies/krn%3Aad%3Adoc_demo_plunger_01%2Fdoc_demo_closed_time_sp/update' \
-H "Authorization: Bearer <Your Current Token>" \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"policy": {
    "resource_value_check": [],
    "retries": 2
}
}'

The Kelvin API Client URL-encodes the resource for you.

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>")

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

print(response)