Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Controls

Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full lifecycle of a control, including its query, notification settings, and execution schedule.

List all controls

get

Returns a paginated list of controls, including the full details of each control.

By default, results are sorted alphabetically by name. Filtering is not currently supported.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Query parameters
offsetintegerOptional

The number of items to skip before returning results. Used for pagination. The default value is 0.

Default: 0Example: 0
limitinteger · max: 1000Optional

The maximum number of items to return. The default value is 50. The maximum value is 1000.

Default: 50Example: 10
Responses
200

Response for listing controls.

application/json

A list of controls.

get/controls
GET /rest/controlManagement/v1/controls HTTP/1.1
Authorization: Basic username:password
Accept: */*
{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Data Encryption Control",
      "description": "This control ensures that data is encrypted at rest.",
      "domainId": "123e4567-e89b-12d3-a456-426614174001",
      "severity": "Medium",
      "controlType": "Preventative",
      "owners": [
        "123e4567-e89b-12d3-a456-426614174002"
      ],
      "enabled": true
    }
  ]
}

Create a control

post

Creates a new control with the specified properties. The control is disabled by default and must be enabled separately once a valid query has been configured.

Requires Activate and Run or Add Asset on the target domain. A caller who cannot view the domain, or holds neither right on it, receives 403 Forbidden.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Body

Schema for creating a new control.

namestring · max: 255Required

The name of the control.

Example: Data Encryption Control
descriptionstring · max: 2000Optional

A brief description of the control.

Example: This control ensures that data is encrypted at rest.
categorystring · max: 255Optional

The category of the control.

Example: Data Quality
domainIdstring · uuidRequired

The ID of the domain to which the control belongs.

Example: 123e4567-e89b-12d3-a456-426614174000
ownersstring · uuid[] · max: 50 · nullableOptional

The owners of the control. Can be users or user groups. Send an empty array to clear all owners.

Example: 123e4567-e89b-12d3-a456-426614174000
severitystring · max: 255Required

The severity level of the control.

Possible values are Low, Medium, and High.

Example: Medium
controlTypestring · max: 255Optional

The type of control.

Possible values are Preventative, Detective, Corrective, and Directive.

Example: Preventative
resolutionstring · max: 2000Optional

Details the specific actions or steps required to address and resolve a control failure.

Example: Ensure all data is encrypted using AES-256.
Responses
201

Confirm the control was created successfully.

application/json
post/controls
POST /rest/controlManagement/v1/controls HTTP/1.1
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 688

{
  "name": "Data Encryption Control",
  "description": "This control ensures that data is encrypted at rest.",
  "category": "Data Quality",
  "domainId": "123e4567-e89b-12d3-a456-426614174000",
  "owners": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "severity": "Medium",
  "controlType": "Preventative",
  "resolution": "Ensure all data is encrypted using AES-256.",
  "executionSchedule": {
    "frequency": "Daily",
    "timeOfDay": "12:00:00Z",
    "daysOfWeek": [
      "Monday",
      "Tuesday"
    ]
  },
  "query": {
    "version": 1,
    "assetSelector": {
      "targetType": {
        "publicId": "Column",
        "type": "AssetType"
      }
    }
  },
  "notificationSettings": {
    "message": "Message rich text example.",
    "recipients": [
      {
        "type": "User",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "John Doe"
      }
    ]
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Retrieve a control by ID

get

Returns the full details of the control with the specified ID.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Path parameters
controlIdstring · uuidRequired

The unique identifier of the control.

Responses
200

Response for retrieving a control.

application/json

Schema for a control.

idstring · uuidRequired

The ID of the control asset.

Example: 123e4567-e89b-12d3-a456-426614174000
namestring · max: 255Required

The name of the control.

Example: Data Encryption Control
descriptionstring · max: 2000Required

A brief description of the control.

Example: This control ensures that data is encrypted at rest.
categorystring · max: 255Optional

The category of the control.

Example: Data Quality
domainIdstring · uuidRequired

The ID of the domain to which the control belongs.

Example: 123e4567-e89b-12d3-a456-426614174000
severitystring · max: 255Required

The severity level of the control.

Possible values are Low, Medium, and High.

Example: Medium
controlTypestring · max: 255Required

The type of control.

Possible values are Preventative, Detective, Corrective, and Directive.

Example: Preventative
ownersstring · uuid[] · max: 50 · nullableRequired

The owners of the control. Can be users or user groups. Send an empty array to clear all owners.

Example: 123e4567-e89b-12d3-a456-426614174000
enabledbooleanRequired

If the control is enabled or not.

resolutionstring · max: 2000Optional

Details the specific actions or steps required to address and resolve a control failure.

Example: Ensure all data is encrypted using AES-256.
queryInvalidbooleanRead-onlyRequired

Whether the control's query is currently invalid.

This value is read-only: it reflects the last determination made for this control and cannot be set directly through this resource.

Example: false
get/controls/{controlId}
GET /rest/controlManagement/v1/controls/{controlId} HTTP/1.1
Authorization: Basic username:password
Accept: */*
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Data Encryption Control",
  "description": "This control ensures that data is encrypted at rest.",
  "category": "Data Quality",
  "domainId": "123e4567-e89b-12d3-a456-426614174000",
  "severity": "Medium",
  "controlType": "Preventative",
  "owners": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "enabled": true,
  "resolution": "Ensure all data is encrypted using AES-256.",
  "query": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "queryInvalid": false,
  "executionSchedule": {
    "frequency": "Daily",
    "timeOfDay": "12:00:00Z",
    "daysOfWeek": [
      "Monday",
      "Tuesday"
    ]
  },
  "notificationSettings": {
    "message": "Message rich text example.",
    "recipients": [
      {
        "type": "User",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "John Doe"
      }
    ]
  }
}

Delete a control by ID

delete

Deletes the control with the specified ID. If the control does not exist, the response is still 204 No Content.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Path parameters
controlIdstring · uuidRequired

The unique identifier of the control.

Responses
204

The control was either deleted successfully or does not exist.

No content

delete/controls/{controlId}
DELETE /rest/controlManagement/v1/controls/{controlId} HTTP/1.1
Authorization: Basic username:password
Accept: */*

No content

Update a control by ID

patch

Updates a control. This method allows you to override specified fields of a control. All null values will be ignored.

Requires Activate and Run on the control. Supplying a domainId that differs from the control's current domain moves the control, and additionally requires Activate and Run or Add Asset on the target domain. A caller missing either right receives 403 Forbidden.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Path parameters
controlIdstring · uuidRequired

The unique identifier of the control.

Body

Schema for updating a control

namestring · max: 255Optional

The name of the control.

Example: Data Encryption Control
descriptionstring · max: 2000Optional

A brief description of the control.

Example: This control ensures that data is encrypted at rest.
categorystring · max: 255Optional

The category of the control.

Example: Data Quality
domainIdstring · uuidOptional

The ID of the domain to which the control belongs.

Example: 123e4567-e89b-12d3-a456-426614174000
severitystring · max: 255Optional

The severity level of the control.

Possible values are Low, Medium, and High.

Example: Medium
controlTypestring · max: 255Optional

The type of control.

Possible values are Preventative, Detective, Corrective, and Directive.

Example: Preventative
ownersstring · uuid[] · max: 50 · nullableOptional

The owners of the control. Can be users or user groups. Send an empty array to clear all owners.

Example: 123e4567-e89b-12d3-a456-426614174000
resolutionstring · max: 2000Optional

Details the specific actions or steps required to address and resolve a control failure.

Example: Ensure all data is encrypted using AES-256.
Responses
200

Response for retrieving a control.

application/json

Schema for a control.

idstring · uuidRequired

The ID of the control asset.

Example: 123e4567-e89b-12d3-a456-426614174000
namestring · max: 255Required

The name of the control.

Example: Data Encryption Control
descriptionstring · max: 2000Required

A brief description of the control.

Example: This control ensures that data is encrypted at rest.
categorystring · max: 255Optional

The category of the control.

Example: Data Quality
domainIdstring · uuidRequired

The ID of the domain to which the control belongs.

Example: 123e4567-e89b-12d3-a456-426614174000
severitystring · max: 255Required

The severity level of the control.

Possible values are Low, Medium, and High.

Example: Medium
controlTypestring · max: 255Required

The type of control.

Possible values are Preventative, Detective, Corrective, and Directive.

Example: Preventative
ownersstring · uuid[] · max: 50 · nullableRequired

The owners of the control. Can be users or user groups. Send an empty array to clear all owners.

Example: 123e4567-e89b-12d3-a456-426614174000
enabledbooleanRequired

If the control is enabled or not.

resolutionstring · max: 2000Optional

Details the specific actions or steps required to address and resolve a control failure.

Example: Ensure all data is encrypted using AES-256.
queryInvalidbooleanRead-onlyRequired

Whether the control's query is currently invalid.

This value is read-only: it reflects the last determination made for this control and cannot be set directly through this resource.

Example: false
patch/controls/{controlId}
PATCH /rest/controlManagement/v1/controls/{controlId} HTTP/1.1
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 688

{
  "name": "Data Encryption Control",
  "description": "This control ensures that data is encrypted at rest.",
  "category": "Data Quality",
  "domainId": "123e4567-e89b-12d3-a456-426614174000",
  "severity": "Medium",
  "controlType": "Preventative",
  "owners": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "resolution": "Ensure all data is encrypted using AES-256.",
  "query": {
    "version": 1,
    "assetSelector": {
      "targetType": {
        "publicId": "Column",
        "type": "AssetType"
      }
    }
  },
  "executionSchedule": {
    "frequency": "Daily",
    "timeOfDay": "12:00:00Z",
    "daysOfWeek": [
      "Monday",
      "Tuesday"
    ]
  },
  "notificationSettings": {
    "message": "Message rich text example.",
    "recipients": [
      {
        "type": "User",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "John Doe"
      }
    ]
  }
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Data Encryption Control",
  "description": "This control ensures that data is encrypted at rest.",
  "category": "Data Quality",
  "domainId": "123e4567-e89b-12d3-a456-426614174000",
  "severity": "Medium",
  "controlType": "Preventative",
  "owners": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "enabled": true,
  "resolution": "Ensure all data is encrypted using AES-256.",
  "query": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "queryInvalid": false,
  "executionSchedule": {
    "frequency": "Daily",
    "timeOfDay": "12:00:00Z",
    "daysOfWeek": [
      "Monday",
      "Tuesday"
    ]
  },
  "notificationSettings": {
    "message": "Message rich text example.",
    "recipients": [
      {
        "type": "User",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "John Doe"
      }
    ]
  }
}

Retrieve the requirements of a control

get

Returns the requirements (if any) defined for a given Control.

The requirements of a Control are AssetFilter objects defined in the query of the Control and that define isRequirement as true.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Path parameters
controlIdstring · uuidRequired

The unique identifier of the control.

Responses
200

The requirements of a control.

application/json

An array of requirements.

idstring · min: 17 · max: 17Optional

The ID of a requirement is a 17 characters string that combines the versionHash of the parent ControlQuery with the versionHash of the AssetFilter marked as a requirement.

The 2 hashes are separated by a - character.

For example:

  • If the versionHash of the ControlQuery is ba7816bf
  • If the versionHash of the Filter is cd294a01
  • The identifier of the requirement is ba7816bf-cd294a01
Example: ba7816bf-cd294a01
get/controls/{controlId}/requirements
GET /rest/controlManagement/v1/controls/{controlId}/requirements HTTP/1.1
Authorization: Basic username:password
Accept: */*
[
  {
    "id": "ba7816bf-cd294a01",
    "targetType": {
      "type": "AssetType",
      "publicId": "Column",
      "name": "Column",
      "symbolData": {
        "acronymCode": "COL",
        "color": "#0072BC",
        "iconCode": "uf-additional-icon-document_newspaper",
        "symbolType": "ICON_CODE"
      }
    },
    "filter": {
      "predicates": [
        {
          "operandType": "status",
          "operator": "equals",
          "value": [
            {
              "id": "1360b0a7-9497-479f-8079-09358c259b8a",
              "name": "Approved",
              "type": "Status"
            }
          ]
        }
      ]
    }
  },
  {
    "id": "ba7816bf-cd294a02",
    "targetType": {
      "type": "AssetType",
      "publicId": "Table",
      "name": "Table",
      "symbolData": {
        "acronymCode": "TAB",
        "color": "#0072BC",
        "iconCode": "uf-additional-icon-document_newspaper",
        "symbolType": "ICON_CODE"
      }
    },
    "filter": {
      "predicates": [
        {
          "operandType": "status",
          "operator": "equals",
          "value": [
            {
              "id": "1360b0a7-9497-479f-8079-09358c259b8a",
              "name": "Approved",
              "type": "Status"
            }
          ]
        }
      ]
    }
  }
]

Enable a control

post

Enables a control by setting its enabled status to true.

Before you can enable a control, the following conditions must be met:

  • The control must have a control query defined.

  • The control query must be valid.

  • All the mandatory properties of the control have been defined, such as name and severity.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Path parameters
controlIdstring · uuidRequired

The unique identifier of the control.

Responses
204

The control was enabled successfully.

No content

post/controls/{controlId}/enable
POST /rest/controlManagement/v1/controls/{controlId}/enable HTTP/1.1
Authorization: Basic username:password
Accept: */*

No content

Disable a control

post

Disables a control by setting its enabled status to false.

Authorizations
AuthorizationstringRequired

This API requires Basic HTTP authentication.

Path parameters
controlIdstring · uuidRequired

The unique identifier of the control.

Responses
204

The control was disabled successfully.

No content

post/controls/{controlId}/disable
POST /rest/controlManagement/v1/controls/{controlId}/disable HTTP/1.1
Authorization: Basic username:password
Accept: */*

No content

Last updated

Was this helpful?