Manage policy rules

Suggest Edits

Manage, optimize, and modify your images and short-form videos. With this customization, you can deliver a smooth, efficient, and visually engaging customer experience.

When working with the Image and Video Manager API, your contract should include images or videos or both depending on the media type you want to work with. You also need to have READ-WRITE access to the Property Manager API.

Create policy sets and policies

A policy set serves as a collection of policies with optimization and transformation configuration settings for your images and videos. You can create these policy set types:

An image policy set. Contains only image policies.
A video policy set. Contains only video policies.

New policy set

When creating a new policy set with the New-IVMPolicySet command, define the following:

Policy name
Region it applies to
Policy type (image or video)
Your contract ID

You can tab through the -Region and -Type parameters to see the acceptable values; they're prepopulated in the function.

Optionally, you define your own default settings in a variable as a hashtable, PSCustomObject, or JSON string, and then pass the variable to the -DefaultPolicy parameter. If you don't pass it, the policy set will use the system default.

See the New policy section for the full list of image and video policy properties you can pass in the -DefaultPolicy parameter.

$myDefaultPolicy = @{
  output = @{
    adaptiveQuality = 75
    perceptualQuality = "mediumHigh"
  }
  postBreakpointTransformations = @(
    @{
      color = "#ff6347"
      transformation = "BackgroundColor"
    }
  )
  breakpoints = @{
    widths = 320, 501, 1039, 2050, 5000
  }
  rolloutDuration = 5500
}

New-IVMPolicySet -Name 'my-policy-set' -Region 'US' -Type 'IMAGE' -DefaultPolicy $myDefaultPolicy -ContractID 'C-0N7RAC7'

$myDefaultPolicy = '{
  "output": {
    "adaptiveQuality": 75,
    "perceptualQuality": "mediumHigh"
  },
  "postBreakpointTransformations": [
    {
      "color": "#ff6347",
      "transformation": "BackgroundColor"
    }
  ],
  "breakpoints": {
    "widths": [
      320,
      501,
      1039,
      2050,
      5000
    ]
  },
  "rolloutDuration": 5500
}'

New-IVMPolicySet -Name 'my-policy-set' -Region 'US' -Type 'IMAGE' -DefaultPolicy $myDefaultPolicy -ContractID 'C-0N7RAC7'

id           : ivm_12345
name         : my-policy-set
region       : US
type         : IMAGE
properties   : {}
user         : 1abcdefgh2ijklmn
lastModified : 2024-12-04 11:59:05+0000

Instead of specifying the -Name, -Region, -Type, and -DefaultPolicy parameters individually, you can also use the -Body parameter to specify them within an object or you can pipe the object to the command.

$Body = @{
  name = "my-policy-set"
  region = "US"
  type = "IMAGE"
  defaultPolicy = $myDefaultPolicy
}

# Option 1: Pass the object in the `-Body` parameter
New-IVMPolicySet -Body $Body -ContractID 'C-0N7RAC7'

# Option 2: Pipe your object to the command
$Body | New-IVMPolicySet -ContractID 'C-0N7RAC7'

Each time you create a new policy set, the policy set is automatically activated on both staging and production networks and a default .auto policy with baseline settings is generated.

You can create as many policy sets and policies as you need on a single contract.

New policy

When creating a new policy within your policy set, specify its settings in a variable as a hashtable, PSCustomObject, or JSON string and then pass the variable in the -Body parameter of the New-IVMPolicy command. Define also the policy ID and network on which you want to activate your policy.

Argument	Description
Image policy
`breakpoints`	The list of breakpoint `widths` in pixels to use to create derivative images.
`hosts`	The hosts allowed for image URLs within transformations or variables.
`output`	The output quality and formats created for each resized image. If unspecified, image formats are created to support all browsers at the default quality level (`85`) including formats such as WEBP, JPEG2000, and JPEG-XR for specific browsers. Contains: `adaptiveQuality`. The quality value applied to an image when Image and Video Manager detects a slow connection (RTT > 300 ms). This value (1-100) overrides the derivative quality value. Specifying a lower value can reduce load times for users with slow connections without impacting the quality of images for users with standard connections. `perceptualQuality`. The perceptual quality to use when comparing resulting images. Perceptual quality tunes each image format's quality parameter dynamically based on the human-perceived quality of the output image. The visual quality of derivative videos after they have been compressed to maximize byte savings. You can select one of these perceptual quality values: `high` `mediumHigh` `medium` `mediumLow` `low` `high` results in the highest visual quality with the least byte savings, while `low` results in lower visual quality with the greatest byte savings. You can set either `perceptualQuality` or `quality`, but not both. If setting a variable for this argument, use `var` inside it instead of a direct value. `perceptualQualityFloor`. Applies only when `perceptualQuality` is set. The minimum image quality to respect when perceptual quality is set. Image quality will not be reduced below this value even if it's determined that a further compressed image would be acceptably visually similar. Set a value between 1-100. `quality`. The specified quality of the output images expressed as a value from 1-100. You can set either `perceptualQuality` or `quality`, but not both. If neither is set, `quality` is the default. If setting a variable for this argument, use `var` inside it instead of a direct value.
`postBreakpointTransformations`	The set of post-processing transformations applied to the image after image and quality settings have been applied. This is a subset of the complete list of transformations and includes: `BackgroundColor` `Blur` `ChromaKey` `Composite` `Compound` `Contrast` `Goop` `Grayscale` `HSL` `HSV` `IfDimension` `IfOrientation` `MaxColors` `Mirror` `MonoHue` `Opacity` `RemoveColor` `UnsharpMask` For information about these transformations and their supporting arguments, see the Transform images guide.
`rolloutDuration`	The amount of time in seconds that it takes for the policy to roll out. During the rollout, the proportion of images with the new policy applied continually increases until cached videos associated with the previous version of the policy are no longer being served. The default is `3600` seconds.
`transformations`	The set of image transformations applied to the original image. If unspecified, no operations are performed. For information about available transformations and their supporting arguments, see the Transform images guide.
`variables`	The variables available for the policy. Any variable declared here can be invoked in transformations. You can also pass in these variable names and values dynamically as query parameters in the image's request URL. See Variables for more information. `name`. Required. The name of the variable. It's also available as the query parameter name to set the variable's value dynamically. Can be up to 50 alphanumeric characters. `type`. Required. The type of value for the variable. Value is one of: `bool` `number` `url` `color` `gravity` `placement` `scaleDimension` `grayscaleType` `aspect` `resizeType` `dimension` `perceptualQuality` `string` `focus` `defaultValue`. Required. The default value of the variable if no query parameter is provided. It needs to be one of the `enumOptions` if any are provided. `enumOptions`. Limits the set of possible values for a variable. Contains: `id`Required. The ID for each enum value. Can be up to 50 alphanumeric characters. `value`Required. The value of the variable when the `id` is provided. `postfix`. A postfix added to the value provided for the variable or to the default value. `prefix`. A prefix added to the value provided for the variable or to the default value.
Video policy
`breakpoints`	The list of breakpoint `widths` in pixels used to create derivative videos.
`hosts`	The hosts allowed for video URLs within variables.
`output`	The output quality of each resized video. Contains: `perceptualQuality`. The visual quality of derivative videos after they have been compressed to maximize byte savings. You can select one of these perceptual quality values: `high` `mediumHigh` `medium` `mediumLow` `low` `high` results in the highest visual quality with the least byte savings, while `low` results in lower visual quality with the greatest byte savings. If setting a variable for this argument, use `var` inside it instead of a direct value. `placeholderVideoUrl`. The URL for a specific placeholder video that appears when you first request a video, and Image and Video Manager is still processing the derivative video. If no placeholder video is specified, the original video plays while the derivative video is processed. If setting a variable for this argument, use `var` inside it instead of a direct value. `videoAdaptiveQuality`. The quality value applied to a video when Image and Video Manager detects a slow connection (RTT > 300 ms). This value overrides the derivative quality value. Specifying a lower value can reduce load times for users with slow connections without impacting the quality of videos for users with standard connections. If setting a variable for this argument, use `var` inside it instead of a direct value.
`rolloutDuration`	The amount of time in seconds that it takes for the policy to roll out. During the rollout, the proportion of videos with the new policy applied continually increases until cached videos associated with the previous version of the policy are no longer being served.
`variables`	The variables available for the policy. Any variable declared here can be invoked in transformations. You can also pass in these variable names and values dynamically as query parameters in the image's request URL. See Variables for more information. `name`. Required. The name of the variable. It's also available as the query parameter name to set the variable's value dynamically. Can be up to 50 alphanumeric characters. `type`. Required. The type of value for the variable. Value is one of: `bool` `number` `url` `color` `gravity` `placement` `scaleDimension` `grayscaleType` `aspect` `resizeType` `dimension` `perceptualQuality` `string` `focus` `defaultValue`. Required. The default value of the variable if no query parameter is provided. It needs to be one of the `enumOptions` if any are provided. `enumOptions`. Limits the set of possible values for a variable. Contains: `id`Required. The ID for each enum value. Can be up to 50 alphanumeric characters. `value`Required. The value of the variable when the `id` is provided. `postfix`. A postfix added to the value provided for the variable or to the default value. `prefix`. A prefix added to the value provided for the variable or to the default value.

$myNewPolicy = @{
  output = @{
    adaptiveQuality = 75
    quality = 86
  }
  postBreakpointTransformations = @(
    @{
      color = "#000000"
      transformation = "BackgroundColor"
    },
    @{
      sigma = 5
      transformation = "Blur"
    }
  )
  breakpoints = @{
    widths = 501, 1050, 5000
  }
  rolloutDuration = 5500
}

New-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '1234' -Network 'Staging' -Body $myNewPolicy -ContractID 'C-0N7RAC7'

$myNewPolicy = '{
  "output": {
    "adaptiveQuality": 75,
    "quality": 86
  },
  "postBreakpointTransformations": [
    {
      "color": "#000000",
      "transformation": "BackgroundColor"
    },
    {
      "transformation": "Blur",
      "sigma": 5
    }
  ],
  "breakpoints": {
    "widths": [
      501,
      1050,
      5000
    ]
  },
  "rolloutDuration": 5500
}'

New-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '1234' -Network 'Staging' -Body $myNewPolicy -ContractID 'C-0N7RAC7'

operationPerformed description          id
------------------ -----------          --
CREATED            Policy 1234 created. 1234

You can also define your custom policy settings in a JSON file, load the file into a variable, convert it into a PowerShell object, and pipe it to the command.

$myCustomPolicy = Get-Content ./myCustomPolicy.json | ConvertFrom-Json -Depth 100

$myCustomPolicy | New-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '1234' -Network 'Staging' -ContractID 'C-0N7RAC7'

Update your policy set

For an existing policy set, you can only update its name and region.

If you don't know your policy set ID, use the Get-IVMPolicySet command to return a list of policy sets available to you. For a specific policy set, pass also the -PolicySetID parameter in the command.

 # Get all
 Get-IVMPolicySet

 # Get one
 Get-IVMPolicySet -PolicySetID 'ivm_12345'

id           : ivm_12345
name         : my-policy-set-1
region       : EMEA
type         : IMAGE
properties   : {my.property1.com}
user         : jsmith
lastModified : 2024-12-04 11:59:05+0000

id           : ivm_98765
name         : my-policy-set-2
region       : US
type         : IMAGE
properties   : {my.property2.com}
user         : josmith
lastModified : 2024-06-02 14:06:53+0000

id           : ivm_12345
name         : my-policy-set-1
region       : EMEA
type         : IMAGE
properties   : {my.property1.com}
user         : jsmith
lastModified : 2024-12-04 11:59:05+0000

Once you have the policy set you need, make appropriate changes to the policy set using the Set-IVMPolicySet command.

Set-IVMPolicySet -PolicySetID 'ivm_12345' -Name 'my-updated-policy-set' -Region 'ASIA'

 id           : ivm_12345
 name         : my-updated-policy-set
 region       : ASIA
 type         : IMAGE
 properties   : {}
 user         : jsmith
 lastModified : 2024-12-05 16:43:54+0000

Update your policy

To update an existing policy with your policy set, set the policy settings you want to change to a variable and make your changes.

If you don't know your policy ID, use the Get-IVMPolicy command to return a list of policies within a given policy set. In this command, specify the policy set ID you want to retrieve all policies for, the contract ID, and the network type. For a specific policy, pass also a policy ID in the command.

 # Get all
 Get-IVMPolicy -PolicySetID 'ivm_12345' -Network 'Staging' -ContractID 'C-0N7RAC7'

 # Get one
 Get-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '.auto' -Network 'Staging' -ContractID 'C-0N7RAC7'

id              : .auto
version         : 1
previousVersion : 0
rolloutInfo     : @{startTime=1654179539; endTime=1654179540; rolloutDuration=1; serveStaleEndTime=1654179539}
video           : False
user            : jsmith
dateCreated     : 2022-06-02 14:18:58+0000

id              : 1234
version         : 1
previousVersion : 0
rolloutInfo     : @{startTime=1654187793; endTime=1654187794; rolloutDuration=1; serveStaleEndTime=1654187793}
output          : @{quality=85; allowedFormats=System.Object[]}
video           : False
user            : jsmith
dateCreated     : 2022-06-02 16:36:32+0000

id              : .auto
version         : 1
previousVersion : 0
rolloutInfo     : @{startTime=1654179539; endTime=1654179540; rolloutDuration=1; serveStaleEndTime=1654179539}
video           : False
user            : jsmith
dateCreated     : 2022-06-02 14:18:58+0000

To update a specific policy, get a specific record, save its output locally, and edit it according to your needs.

Get-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '.auto' -Network 'Staging' -ContractID 'C-0N7RAC7' | ConvertTo-Json -Depth 100 | Out-File -FilePath ./myPolicy.json

{
  "id": ".auto",
  "version": 1,
  "previousVersion": 0,
  "rolloutInfo": {
    "startTime": 1740163087,
    "endTime": 1740163088,
    "rolloutDuration": 1,
    "serveStaleEndTime": 1740163087
  },
  "breakpoints": {
    "widths": [
      300,
      451,
      2039,
      5000
    ]
  },
  "output": {
    "quality": 94,
    "adaptiveQuality": 70
  },
  "transformations": [
    {
      "transformation": "Contrast",
      "brightness": 0.5,
      "contrast": 0.2
    },
    {
      "gravity": "SouthWest",
      "image": {
        "url": "www.example.com/image.png"
      },
      "transformation": "Composite",
      "xPosition": 0,
      "yPosition": 0
    }
  ],
  "postBreakpointTransformations": [
    {
      "color": "#ffffff",
      "transformation": "BackgroundColor"
    },
    {
      "transformation": "Blur",
      "sigma": 5
    }
  ],
  "video": false,
  "user": "1abcdefghi2jklmn",
  "dateCreated": "2025-02-20 14:38:06+0000"
}

Then convert it back to a PowerShell object and pipe it to the Set-IVMPolicy command along with the required ID and network type.

$myPolicy = Get-Content ./myPolicy.json | ConvertFrom-Json -Depth 100

$myPolicy | Set-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '.auto' -Network 'Staging' -ContractID 'C-0N7RAC7'

operationPerformed description           id
------------------ -----------           --
UPDATED            Policy .auto updated. .auto

Alternatively, you can save the result of the Get-IVMPolicy command in a variable and update specific attributes of your policy, then pipe the whole object back to the Set-IVMPolicy command to make your changes effective.

$myPolicy = Get-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '.auto' -Network 'Staging' -ContractID 'C-0N7RAC7'

$myPolicy.breakpoints.widths = @(200, 100, 500, 3000)
$myPolicy.output.quality = 98
$myPolicy.postBreakpointTransformations[0].color = '#d9a61a'
$myPolicy.transformations[1].gravity = 'Center'

$myPolicy | Set-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '.auto' -Network 'Staging' -ContractID 'C-0N7RAC7'

Update your property rule tree

You need to add one or more imaging policy behaviors to the JSON rule tree file for each property you're adding image policies to.

Get your property's rule tree as a JSON file. The output is a JSON file at your current location containing your rule's configurations.
```
Get-PropertyRules -PropertyName 'my-property' -PropertyVersion 'latest' -OutputToFile
```

Depending on the policy set type you're adding, add appropriate behaviors to your property rules' main.json. When adding these behaviors, make sure to use the correct policy set ID.

{
  "name": "Image and Video Manager (Images)",
  "children": [],
  "behaviors": [
    {
      "name": "caching",
      "options": {
        "behavior": "MAX_AGE",
        "mustRevalidate": false,
        "ttl": "30d"
      }
    },
    {
      "name": "imageManager",
      "options": {
        "apiReferenceTitle": "",
        "applyBestFileType": true,
        "enabled": true,
        "resize": false,
        "settingsTitle": "",
        "useExistingPolicySet": true,
        "trafficTitle": "",
        "cpCodeOriginal": {
          "id": 12345,
          "description": "My CP code",
          "products": [
            "Obj_Delivery"
          ],
          "createdDate": 1708507581000,
          "cpCodeLimits": null,
          "name": "My CP code"
        },
        "cpCodeTransformed": {
          "id": 98765,
          "description": "My other CP code",
          "products": [
            "Obj_Delivery"
          ],
          "createdDate": 1708523914000,
          "cpCodeLimits": null,
          "name": "My other CP code"
        },
        "policySet": "ivm_12345"
      }
    }
  ],
  "criteria": [
    {
      "name": "fileExtension",
      "options": {
        "matchCaseSensitive": false,
        "matchOperator": "IS_ONE_OF",
        "values": [
          "jpg",
          "gif",
          "jpeg",
          "png",
          "imviewer"
        ]
      }
    }
  ],
  "criteriaMustSatisfy": "all",
  "comments": ""
}

{
  "name": "Image and Video Manager (Videos)",
  "children": [],
  "behaviors": [
    {
      "name": "caching",
      "options": {
        "behavior": "MAX_AGE",
        "mustRevalidate": false,
        "ttl": "30d"
      }
    },
    {
      "name": "imageManagerVideo",
      "options": {
        "apiReferenceTitle": "",
        "applyBestFileType": true,
        "enabled": true,
        "resize": false,
        "settingsTitle": "",
        "useExistingPolicySet": false,
        "trafficTitle": "",
        "cpCodeOriginal": {
          "id": 12345,
          "description": "My CP code",
          "products": [
            "Obj_Delivery"
          ],
          "createdDate": 1708507581000,
          "cpCodeLimits": null,
          "name": "My CP code"
        },
        "cpCodeTransformed": {
          "id": 98765,
          "description": "My other CP code",
          "products": [
            "Obj_Delivery"
          ],
          "createdDate": 1708523914000,
          "cpCodeLimits": null,
          "name": "My other CP code"
        },
        "superCacheRegion": "US",
        "advanced": false,
        "policyTokenDefault": "my-default-policy"
      }
    }
  ],
  "criteria": [
    {
      "name": "fileExtension",
      "options": {
        "matchCaseSensitive": false,
        "matchOperator": "IS_ONE_OF",
        "values": [
          "mp4"
        ]
      }
    }
  ],
  "criteriaMustSatisfy": "all",
  "comments": ""
}

Additional considerations:

To apply these behaviors, you also need to add the fileExtension match criteria and the caching behavior.
The imageManager behavior includes its own CP code settings. Make sure not to include it in the same rule with the cpCode behavior.
Place your imageManager or imageManagerVideo behavior at the end of your property rules to ensure it works correctly.

Update your property's rules, pointing to the appropriate file.

Send your entire rule tree back. Rules not returned are removed from your property.
```
Set-PropertyRules -PropertyName 'my-property' -PropertyVersion latest -InputFile './main.json' -VersionNotes 'Adding a video policy'
```
The output returns your rule tree along with any errors or warnings on upload.

Activate your property

To activate the property containing your newly added imaging or video policies, provide a value for the network, staging or production, and activate your property.

New-PropertyActivation -PropertyName 'my-property' -PropertyVersion 'latest' -Network 'Staging' -NotifyEmails 'jsmith@email.com'

activationLink                                                                                      activationId
--------------                                                                                      ------------
/papi/v1/properties/prp_12345/activations/atv_67890?contractId=ctr_C-0N7RAC7&groupId=grp_12345      atv_67890

Delete policy sets and policies

To delete a policy set and its related policies from both staging and production networks, pass the policy set and contract IDs in the Remove-IVMPolicySet command.

Remove-IVMPolicySet -PolicySetID 'ivm_12345' -ContractID 'C-0N7RAC7'

To delete a policy from a policy set, pass the policy, policy set, and contract IDs in the Remove-IVMPolicy command. Also, include the network type from which you want to remove the policy.

You can't delete a default .auto policy with this command, You can delete it only when you remove the whole policy set.

Remove-IVMPolicy -PolicySetID 'ivm_12345' -PolicyID '1234' -Network 'Staging' -ContractID 'C-0N7RAC7'

Updated about 14 hours ago