> For the complete documentation index, see [llms.txt](https://developer.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.collibra.com/api/references/control-tower/controls.md).

# 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

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"parameters":{"offset":{"name":"offset","in":"query","required":false,"description":"The number of items to skip before returning results. Used for pagination. The default value is 0.\n","schema":{"type":"integer","default":0,"minimum":0}},"limit":{"name":"limit","in":"query","required":false,"description":"The maximum number of items to return. The default value is 50. The maximum value is 1000.","schema":{"type":"integer","maximum":1000,"default":50}}},"responses":{"ControlListResponse":{"description":"Response for listing controls.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlList"}}}},"BadRequest":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"ControlList":{"description":"A list of controls.","type":"object","required":["results"],"properties":{"results":{"description":"List of controls.","type":"array","items":{"$ref":"#/components/schemas/Control"}}}},"Control":{"description":"Schema for a control.","type":"object","properties":{"id":{"$ref":"#/components/schemas/ControlId"},"name":{"$ref":"#/components/schemas/ControlName"},"description":{"$ref":"#/components/schemas/ControlDescription"},"category":{"$ref":"#/components/schemas/ControlCategory"},"domainId":{"$ref":"#/components/schemas/ControlDomainId"},"severity":{"$ref":"#/components/schemas/ControlSeverity"},"controlType":{"$ref":"#/components/schemas/ControlType"},"owners":{"allOf":[{"$ref":"#/components/schemas/ControlOwners"}],"description":"The owners of the control. Can be users or user groups."},"enabled":{"$ref":"#/components/schemas/ControlEnabled"},"resolution":{"$ref":"#/components/schemas/Resolution"},"query":{"$ref":"#/components/schemas/ControlQuery"},"queryInvalid":{"description":"Whether the control's query is currently invalid.\n\nThis value is read-only: it reflects the last determination made for this control and cannot be set\ndirectly through this resource.\n","type":"boolean","readOnly":true},"executionSchedule":{"$ref":"#/components/schemas/ControlExecutionSchedule"},"notificationSettings":{"$ref":"#/components/schemas/ControlNotificationSettings"}},"required":["id","name","description","domainId","severity","controlType","owners","enabled","queryInvalid"]},"ControlId":{"description":"The ID of the control asset.","type":"string","format":"uuid"},"ControlName":{"description":"The name of the control.","type":"string","maxLength":255},"ControlDescription":{"description":"A brief description of the control.","type":"string","maxLength":2000},"ControlCategory":{"description":"The category of the control.","type":"string","maxLength":255},"ControlDomainId":{"description":"The ID of the domain to which the control belongs.","type":"string","format":"uuid"},"ControlSeverity":{"description":"The severity level of the control.\n\nPossible values are `Low`, `Medium`, and `High`.\n","type":"string","maxLength":255},"ControlType":{"description":"The type of control.\n\nPossible values are `Preventative`, `Detective`, `Corrective`, and `Directive`.\n","type":"string","maxLength":255},"ControlOwners":{"description":"The owners of the control. Can be users or user groups. Send an empty array to clear all owners.","type":["array","null"],"maxItems":50,"items":{"$ref":"#/components/schemas/ControlOwner"}},"ControlOwner":{"description":"The owner id of the control. Can be a user or a user group.","type":"string","format":"uuid"},"ControlEnabled":{"description":"If the control is enabled or not.","type":"boolean"},"Resolution":{"description":"Details the specific actions or steps required to address and resolve a control failure.","type":"string","maxLength":2000},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true},"ControlExecutionSchedule":{"description":"The schedule for executing the control.\n\nA control can be executed at different frequencies, such as hourly, daily, or weekly.\n","type":"object","required":["frequency"],"properties":{"frequency":{"description":"How often the control should be executed.\n\nPossible values are:\n- `Hourly`: Executes every hour.\n- `Daily`: Executes every day.\n- `Weekly`: Executes every week.\n","type":"string"},"timeOfDay":{"description":"The time of day when the control execution should start. This is in 24-hour format using the RFC 3339\nfull-time format. The minutes and seconds are ignored and will be set to zero.\n\nFormat: HH:MM:SS[.sss]Z or HH:MM:SS[.sss]±HH:MM\n\nValid examples:\n  * \"14:30:00Z\" (2:30 PM UTC)\n  * \"09:00:00+05:00\" (9:00:00 AM in UTC+5 timezone)\n  * \"23:00:00-08:00\" (11:00:00 PM in UTC-8 timezone)\n  * \"12:00:00.500Z\" (12:00:00.500 PM UTC with milliseconds)\n  * \"18:00:00+02:00\" (6:00:00 PM in UTC+2 timezone)\n\n  Key components:\n  * Time in 24-hour format (HH:MM:SS)\n  * Required timezone offset (Z for UTC, or ±HH:MM for other timezones)\n\nThis property is required if the frequency is set to `Daily` or `Weekly`, and is ignored otherwise.\n","type":"string","format":"time"},"daysOfWeek":{"description":"The days of the week when the control should be executed.\n\nThis property is required if the frequency is set to `Weekly`, and is ignored otherwise. It must contain\nat least one day.\n\nPossible values are:\n- `Monday`\n- `Tuesday`\n- `Wednesday`\n- `Thursday`\n- `Friday`\n- `Saturday`\n- `Sunday`\n","type":"array","maxItems":7,"items":{"type":"string"}}}},"ControlNotificationSettings":{"description":"The notification settings of the control.\n","type":"object","required":["recipients"],"properties":{"message":{"type":"string","description":"The custom message to be used in the notification mail."},"recipients":{"type":"array","description":"The list of notification recipients.","maxItems":50,"items":{"$ref":"#/components/schemas/NotificationRecipient"}}}},"NotificationRecipient":{"description":"The recipient of the control notification.","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"Resource type name.\n\nPossible values are `User` and `Role`.\n"},"id":{"type":"string","format":"uuid","description":"The resource id."},"name":{"type":"string","description":"The resource name.","readOnly":true}}},"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]}}},"paths":{"/controls":{"get":{"tags":["Controls"],"summary":"List all controls","description":"Returns a paginated list of controls, including the full details of each control.\n\nBy default, results are sorted alphabetically by name. Filtering is not currently supported.\n","operationId":"listControls","parameters":[{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/limit"}],"responses":{"200":{"$ref":"#/components/responses/ControlListResponse"},"400":{"$ref":"#/components/responses/BadRequest"}}}}}}
```

## Create a control

> 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\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"requestBodies":{"CreateControlRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateControl"}}},"required":true}},"schemas":{"CreateControl":{"description":"Schema for creating a new control.","type":"object","properties":{"name":{"$ref":"#/components/schemas/ControlName"},"description":{"$ref":"#/components/schemas/ControlDescription"},"category":{"$ref":"#/components/schemas/ControlCategory"},"domainId":{"$ref":"#/components/schemas/ControlDomainId"},"owners":{"$ref":"#/components/schemas/ControlOwners"},"severity":{"$ref":"#/components/schemas/ControlSeverity"},"controlType":{"$ref":"#/components/schemas/ControlType"},"resolution":{"$ref":"#/components/schemas/Resolution"},"executionSchedule":{"$ref":"#/components/schemas/ControlExecutionSchedule"},"query":{"description":"The query that defines the logic for finding\nnon-compliant assets.\n\nMay be null.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]},"notificationSettings":{"$ref":"#/components/schemas/ControlNotificationSettings"}},"required":["name","domainId","severity"]},"ControlName":{"description":"The name of the control.","type":"string","maxLength":255},"ControlDescription":{"description":"A brief description of the control.","type":"string","maxLength":2000},"ControlCategory":{"description":"The category of the control.","type":"string","maxLength":255},"ControlDomainId":{"description":"The ID of the domain to which the control belongs.","type":"string","format":"uuid"},"ControlOwners":{"description":"The owners of the control. Can be users or user groups. Send an empty array to clear all owners.","type":["array","null"],"maxItems":50,"items":{"$ref":"#/components/schemas/ControlOwner"}},"ControlOwner":{"description":"The owner id of the control. Can be a user or a user group.","type":"string","format":"uuid"},"ControlSeverity":{"description":"The severity level of the control.\n\nPossible values are `Low`, `Medium`, and `High`.\n","type":"string","maxLength":255},"ControlType":{"description":"The type of control.\n\nPossible values are `Preventative`, `Detective`, `Corrective`, and `Directive`.\n","type":"string","maxLength":255},"Resolution":{"description":"Details the specific actions or steps required to address and resolve a control failure.","type":"string","maxLength":2000},"ControlExecutionSchedule":{"description":"The schedule for executing the control.\n\nA control can be executed at different frequencies, such as hourly, daily, or weekly.\n","type":"object","required":["frequency"],"properties":{"frequency":{"description":"How often the control should be executed.\n\nPossible values are:\n- `Hourly`: Executes every hour.\n- `Daily`: Executes every day.\n- `Weekly`: Executes every week.\n","type":"string"},"timeOfDay":{"description":"The time of day when the control execution should start. This is in 24-hour format using the RFC 3339\nfull-time format. The minutes and seconds are ignored and will be set to zero.\n\nFormat: HH:MM:SS[.sss]Z or HH:MM:SS[.sss]±HH:MM\n\nValid examples:\n  * \"14:30:00Z\" (2:30 PM UTC)\n  * \"09:00:00+05:00\" (9:00:00 AM in UTC+5 timezone)\n  * \"23:00:00-08:00\" (11:00:00 PM in UTC-8 timezone)\n  * \"12:00:00.500Z\" (12:00:00.500 PM UTC with milliseconds)\n  * \"18:00:00+02:00\" (6:00:00 PM in UTC+2 timezone)\n\n  Key components:\n  * Time in 24-hour format (HH:MM:SS)\n  * Required timezone offset (Z for UTC, or ±HH:MM for other timezones)\n\nThis property is required if the frequency is set to `Daily` or `Weekly`, and is ignored otherwise.\n","type":"string","format":"time"},"daysOfWeek":{"description":"The days of the week when the control should be executed.\n\nThis property is required if the frequency is set to `Weekly`, and is ignored otherwise. It must contain\nat least one day.\n\nPossible values are:\n- `Monday`\n- `Tuesday`\n- `Wednesday`\n- `Thursday`\n- `Friday`\n- `Saturday`\n- `Sunday`\n","type":"array","maxItems":7,"items":{"type":"string"}}}},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true},"ControlNotificationSettings":{"description":"The notification settings of the control.\n","type":"object","required":["recipients"],"properties":{"message":{"type":"string","description":"The custom message to be used in the notification mail."},"recipients":{"type":"array","description":"The list of notification recipients.","maxItems":50,"items":{"$ref":"#/components/schemas/NotificationRecipient"}}}},"NotificationRecipient":{"description":"The recipient of the control notification.","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"Resource type name.\n\nPossible values are `User` and `Role`.\n"},"id":{"type":"string","format":"uuid","description":"The resource id."},"name":{"type":"string","description":"The resource name.","readOnly":true}}},"ControlCreated":{"description":"Response schema for a successfully created control.","type":"object","properties":{"id":{"description":"The unique identifier of the created control.","type":"string","format":"uuid"}},"required":["id"]},"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]}},"responses":{"CreateControlResponse":{"description":"Confirm the control was created successfully.","headers":{"Location":{"schema":{"type":"string","format":"uri-reference"},"description":"URL of the created control."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlCreated"}}}},"BadRequestOrInvalidQuery":{"description":"The request is not valid.\n\nWhen the control query is the reason, the `query` field carries it back with the issues found.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"Forbidden":{"description":"The user is forbidden to execute the requested action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/controls":{"post":{"tags":["Controls"],"summary":"Create a control","description":"Creates a new control with the specified properties. The control is disabled by default and must\nbe enabled separately once a valid query has been configured.\n\nRequires `Activate and Run` or `Add Asset` on the target domain. A caller who cannot view the domain, or\nholds neither right on it, receives `403 Forbidden`.\n","operationId":"createControl","requestBody":{"$ref":"#/components/requestBodies/CreateControlRequest"},"responses":{"201":{"$ref":"#/components/responses/CreateControlResponse"},"400":{"$ref":"#/components/responses/BadRequestOrInvalidQuery"},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```

## Retrieve a control by ID

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

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"responses":{"ControlResponse":{"description":"Response for retrieving a control.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Control"}}}},"NotFound":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"Control":{"description":"Schema for a control.","type":"object","properties":{"id":{"$ref":"#/components/schemas/ControlId"},"name":{"$ref":"#/components/schemas/ControlName"},"description":{"$ref":"#/components/schemas/ControlDescription"},"category":{"$ref":"#/components/schemas/ControlCategory"},"domainId":{"$ref":"#/components/schemas/ControlDomainId"},"severity":{"$ref":"#/components/schemas/ControlSeverity"},"controlType":{"$ref":"#/components/schemas/ControlType"},"owners":{"allOf":[{"$ref":"#/components/schemas/ControlOwners"}],"description":"The owners of the control. Can be users or user groups."},"enabled":{"$ref":"#/components/schemas/ControlEnabled"},"resolution":{"$ref":"#/components/schemas/Resolution"},"query":{"$ref":"#/components/schemas/ControlQuery"},"queryInvalid":{"description":"Whether the control's query is currently invalid.\n\nThis value is read-only: it reflects the last determination made for this control and cannot be set\ndirectly through this resource.\n","type":"boolean","readOnly":true},"executionSchedule":{"$ref":"#/components/schemas/ControlExecutionSchedule"},"notificationSettings":{"$ref":"#/components/schemas/ControlNotificationSettings"}},"required":["id","name","description","domainId","severity","controlType","owners","enabled","queryInvalid"]},"ControlId":{"description":"The ID of the control asset.","type":"string","format":"uuid"},"ControlName":{"description":"The name of the control.","type":"string","maxLength":255},"ControlDescription":{"description":"A brief description of the control.","type":"string","maxLength":2000},"ControlCategory":{"description":"The category of the control.","type":"string","maxLength":255},"ControlDomainId":{"description":"The ID of the domain to which the control belongs.","type":"string","format":"uuid"},"ControlSeverity":{"description":"The severity level of the control.\n\nPossible values are `Low`, `Medium`, and `High`.\n","type":"string","maxLength":255},"ControlType":{"description":"The type of control.\n\nPossible values are `Preventative`, `Detective`, `Corrective`, and `Directive`.\n","type":"string","maxLength":255},"ControlOwners":{"description":"The owners of the control. Can be users or user groups. Send an empty array to clear all owners.","type":["array","null"],"maxItems":50,"items":{"$ref":"#/components/schemas/ControlOwner"}},"ControlOwner":{"description":"The owner id of the control. Can be a user or a user group.","type":"string","format":"uuid"},"ControlEnabled":{"description":"If the control is enabled or not.","type":"boolean"},"Resolution":{"description":"Details the specific actions or steps required to address and resolve a control failure.","type":"string","maxLength":2000},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true},"ControlExecutionSchedule":{"description":"The schedule for executing the control.\n\nA control can be executed at different frequencies, such as hourly, daily, or weekly.\n","type":"object","required":["frequency"],"properties":{"frequency":{"description":"How often the control should be executed.\n\nPossible values are:\n- `Hourly`: Executes every hour.\n- `Daily`: Executes every day.\n- `Weekly`: Executes every week.\n","type":"string"},"timeOfDay":{"description":"The time of day when the control execution should start. This is in 24-hour format using the RFC 3339\nfull-time format. The minutes and seconds are ignored and will be set to zero.\n\nFormat: HH:MM:SS[.sss]Z or HH:MM:SS[.sss]±HH:MM\n\nValid examples:\n  * \"14:30:00Z\" (2:30 PM UTC)\n  * \"09:00:00+05:00\" (9:00:00 AM in UTC+5 timezone)\n  * \"23:00:00-08:00\" (11:00:00 PM in UTC-8 timezone)\n  * \"12:00:00.500Z\" (12:00:00.500 PM UTC with milliseconds)\n  * \"18:00:00+02:00\" (6:00:00 PM in UTC+2 timezone)\n\n  Key components:\n  * Time in 24-hour format (HH:MM:SS)\n  * Required timezone offset (Z for UTC, or ±HH:MM for other timezones)\n\nThis property is required if the frequency is set to `Daily` or `Weekly`, and is ignored otherwise.\n","type":"string","format":"time"},"daysOfWeek":{"description":"The days of the week when the control should be executed.\n\nThis property is required if the frequency is set to `Weekly`, and is ignored otherwise. It must contain\nat least one day.\n\nPossible values are:\n- `Monday`\n- `Tuesday`\n- `Wednesday`\n- `Thursday`\n- `Friday`\n- `Saturday`\n- `Sunday`\n","type":"array","maxItems":7,"items":{"type":"string"}}}},"ControlNotificationSettings":{"description":"The notification settings of the control.\n","type":"object","required":["recipients"],"properties":{"message":{"type":"string","description":"The custom message to be used in the notification mail."},"recipients":{"type":"array","description":"The list of notification recipients.","maxItems":50,"items":{"$ref":"#/components/schemas/NotificationRecipient"}}}},"NotificationRecipient":{"description":"The recipient of the control notification.","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"Resource type name.\n\nPossible values are `User` and `Role`.\n"},"id":{"type":"string","format":"uuid","description":"The resource id."},"name":{"type":"string","description":"The resource name.","readOnly":true}}},"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]}}},"paths":{"/controls/{controlId}":{"get":{"tags":["Controls"],"summary":"Retrieve a control by ID","description":"Returns the full details of the control with the specified ID.","operationId":"getControlById","responses":{"200":{"$ref":"#/components/responses/ControlResponse"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Delete a control by ID

> Deletes the control with the specified ID. If the control does not exist, the response is still\
> \`204 No Content\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"responses":{"Forbidden":{"description":"The user is forbidden to execute the requested action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true}}},"paths":{"/controls/{controlId}":{"delete":{"tags":["Controls"],"summary":"Delete a control by ID","description":"Deletes the control with the specified ID. If the control does not exist, the response is still\n`204 No Content`.\n","operationId":"deleteControlById","responses":{"204":{"description":"The control was either deleted successfully or does not exist."},"403":{"$ref":"#/components/responses/Forbidden"}}}}}}
```

## Update a control by ID

> 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\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"requestBodies":{"UpdateControlRequest":{"description":"Update a control. This method allows you to override specified fields of a control. All null values will be\nignored.\n","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateControl"}}}}},"schemas":{"UpdateControl":{"type":"object","description":"Schema for updating a control","properties":{"name":{"$ref":"#/components/schemas/ControlName"},"description":{"$ref":"#/components/schemas/ControlDescription"},"category":{"$ref":"#/components/schemas/ControlCategory"},"domainId":{"$ref":"#/components/schemas/ControlDomainId"},"severity":{"$ref":"#/components/schemas/ControlSeverity"},"controlType":{"$ref":"#/components/schemas/ControlType"},"owners":{"$ref":"#/components/schemas/ControlOwners"},"resolution":{"$ref":"#/components/schemas/Resolution"},"query":{"description":"The query that defines the logic for finding\nnon-compliant assets.\n\nMay be null.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]},"executionSchedule":{"$ref":"#/components/schemas/ControlExecutionSchedule"},"notificationSettings":{"$ref":"#/components/schemas/ControlNotificationSettings"}}},"ControlName":{"description":"The name of the control.","type":"string","maxLength":255},"ControlDescription":{"description":"A brief description of the control.","type":"string","maxLength":2000},"ControlCategory":{"description":"The category of the control.","type":"string","maxLength":255},"ControlDomainId":{"description":"The ID of the domain to which the control belongs.","type":"string","format":"uuid"},"ControlSeverity":{"description":"The severity level of the control.\n\nPossible values are `Low`, `Medium`, and `High`.\n","type":"string","maxLength":255},"ControlType":{"description":"The type of control.\n\nPossible values are `Preventative`, `Detective`, `Corrective`, and `Directive`.\n","type":"string","maxLength":255},"ControlOwners":{"description":"The owners of the control. Can be users or user groups. Send an empty array to clear all owners.","type":["array","null"],"maxItems":50,"items":{"$ref":"#/components/schemas/ControlOwner"}},"ControlOwner":{"description":"The owner id of the control. Can be a user or a user group.","type":"string","format":"uuid"},"Resolution":{"description":"Details the specific actions or steps required to address and resolve a control failure.","type":"string","maxLength":2000},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true},"ControlExecutionSchedule":{"description":"The schedule for executing the control.\n\nA control can be executed at different frequencies, such as hourly, daily, or weekly.\n","type":"object","required":["frequency"],"properties":{"frequency":{"description":"How often the control should be executed.\n\nPossible values are:\n- `Hourly`: Executes every hour.\n- `Daily`: Executes every day.\n- `Weekly`: Executes every week.\n","type":"string"},"timeOfDay":{"description":"The time of day when the control execution should start. This is in 24-hour format using the RFC 3339\nfull-time format. The minutes and seconds are ignored and will be set to zero.\n\nFormat: HH:MM:SS[.sss]Z or HH:MM:SS[.sss]±HH:MM\n\nValid examples:\n  * \"14:30:00Z\" (2:30 PM UTC)\n  * \"09:00:00+05:00\" (9:00:00 AM in UTC+5 timezone)\n  * \"23:00:00-08:00\" (11:00:00 PM in UTC-8 timezone)\n  * \"12:00:00.500Z\" (12:00:00.500 PM UTC with milliseconds)\n  * \"18:00:00+02:00\" (6:00:00 PM in UTC+2 timezone)\n\n  Key components:\n  * Time in 24-hour format (HH:MM:SS)\n  * Required timezone offset (Z for UTC, or ±HH:MM for other timezones)\n\nThis property is required if the frequency is set to `Daily` or `Weekly`, and is ignored otherwise.\n","type":"string","format":"time"},"daysOfWeek":{"description":"The days of the week when the control should be executed.\n\nThis property is required if the frequency is set to `Weekly`, and is ignored otherwise. It must contain\nat least one day.\n\nPossible values are:\n- `Monday`\n- `Tuesday`\n- `Wednesday`\n- `Thursday`\n- `Friday`\n- `Saturday`\n- `Sunday`\n","type":"array","maxItems":7,"items":{"type":"string"}}}},"ControlNotificationSettings":{"description":"The notification settings of the control.\n","type":"object","required":["recipients"],"properties":{"message":{"type":"string","description":"The custom message to be used in the notification mail."},"recipients":{"type":"array","description":"The list of notification recipients.","maxItems":50,"items":{"$ref":"#/components/schemas/NotificationRecipient"}}}},"NotificationRecipient":{"description":"The recipient of the control notification.","type":"object","required":["type","id"],"properties":{"type":{"type":"string","description":"Resource type name.\n\nPossible values are `User` and `Role`.\n"},"id":{"type":"string","format":"uuid","description":"The resource id."},"name":{"type":"string","description":"The resource name.","readOnly":true}}},"Control":{"description":"Schema for a control.","type":"object","properties":{"id":{"$ref":"#/components/schemas/ControlId"},"name":{"$ref":"#/components/schemas/ControlName"},"description":{"$ref":"#/components/schemas/ControlDescription"},"category":{"$ref":"#/components/schemas/ControlCategory"},"domainId":{"$ref":"#/components/schemas/ControlDomainId"},"severity":{"$ref":"#/components/schemas/ControlSeverity"},"controlType":{"$ref":"#/components/schemas/ControlType"},"owners":{"allOf":[{"$ref":"#/components/schemas/ControlOwners"}],"description":"The owners of the control. Can be users or user groups."},"enabled":{"$ref":"#/components/schemas/ControlEnabled"},"resolution":{"$ref":"#/components/schemas/Resolution"},"query":{"$ref":"#/components/schemas/ControlQuery"},"queryInvalid":{"description":"Whether the control's query is currently invalid.\n\nThis value is read-only: it reflects the last determination made for this control and cannot be set\ndirectly through this resource.\n","type":"boolean","readOnly":true},"executionSchedule":{"$ref":"#/components/schemas/ControlExecutionSchedule"},"notificationSettings":{"$ref":"#/components/schemas/ControlNotificationSettings"}},"required":["id","name","description","domainId","severity","controlType","owners","enabled","queryInvalid"]},"ControlId":{"description":"The ID of the control asset.","type":"string","format":"uuid"},"ControlEnabled":{"description":"If the control is enabled or not.","type":"boolean"},"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]}},"responses":{"ControlResponse":{"description":"Response for retrieving a control.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Control"}}}},"BadRequestOrInvalidQuery":{"description":"The request is not valid.\n\nWhen the control query is the reason, the `query` field carries it back with the issues found.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"Forbidden":{"description":"The user is forbidden to execute the requested action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFound":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}}},"paths":{"/controls/{controlId}":{"patch":{"tags":["Controls"],"summary":"Update a control by ID","description":"Updates a control. This method allows you to override specified fields of a control. All null values will be\nignored.\n\nRequires `Activate and Run` on the control. Supplying a `domainId` that differs from the control's current\ndomain moves the control, and additionally requires `Activate and Run` or `Add Asset` on the target domain.\nA caller missing either right receives `403 Forbidden`.\n","operationId":"updateControlById","requestBody":{"$ref":"#/components/requestBodies/UpdateControlRequest"},"responses":{"200":{"$ref":"#/components/responses/ControlResponse"},"400":{"$ref":"#/components/responses/BadRequestOrInvalidQuery"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Retrieve the requirements of a control

> 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\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"parameters":{"controlId":{"name":"controlId","in":"path","required":true,"description":"The unique identifier of the control.","schema":{"type":"string","format":"uuid"}}},"responses":{"ControlRequirementsResponse":{"description":"The requirements of a control.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlRequirements"}}}},"NotFound":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"ControlRequirements":{"type":"array","description":"An array of requirements.\n","items":{"$ref":"#/components/schemas/ControlRequirement"}},"ControlRequirement":{"type":"object","description":"A requirement defined by the query of a given `Control`.\n\nA requirement is composed of:\n - An `id`, which identifies the filter within a specific query.\n - A `targetType`, which defines the type of the assets filtered by the filter.\n - The `filter` marked as a requirement inside the query of the `Control`\n","properties":{"id":{"$ref":"#/components/schemas/ControlRequirementId"},"targetType":{"$ref":"#/components/schemas/AssetType"},"filter":{"$ref":"#/components/schemas/AssetFilter"}}},"ControlRequirementId":{"type":"string","minLength":17,"maxLength":17,"description":"The ID of a requirement is a 17 characters string that combines the `versionHash` of the parent `ControlQuery`\nwith the `versionHash` of the `AssetFilter` marked as a requirement.\n\nThe 2 hashes are separated by a `-` character.\n\nFor example:\n  - If the `versionHash` of the `ControlQuery` is `ba7816bf`\n  - If the `versionHash` of the `Filter` is `cd294a01`\n  - The identifier of the requirement is `ba7816bf-cd294a01`\n"},"AssetType":{"description":"An asset type or asset type group resource.\n","allOf":[{"type":"object","required":["type"],"properties":{"type":{"$ref":"#/components/schemas/AssetTypeResourceType"},"symbolData":{"$ref":"#/components/schemas/SymbolData"}}},{"$ref":"#/components/schemas/OperatingModelResource"}]},"AssetTypeResourceType":{"type":"string","description":"The type of asset type (asset type or asset type group).\n\nThe possible values are:\n- `AssetType`\n- `AssetTypeGroup`\n","default":"AssetType"},"SymbolData":{"description":"The symbol data of the type.","required":["acronymCode","color","symbolType"],"properties":{"acronymCode":{"type":"string","description":"The acronym code of the symbol.\n"},"color":{"type":"string","description":"The hex color code of the symbol.\n"},"iconCode":{"type":"string","description":"The icon code of the symbol.\n"},"symbolType":{"$ref":"#/components/schemas/SymbolDataType"}},"type":"object"},"SymbolDataType":{"enum":["NONE","ICON_CODE","ACRONYM_CODE"],"type":"string"},"OperatingModelResource":{"type":"object","description":"A resource of the Operating Model.\nThose resources are identified by their public ID.\n","required":["publicId"],"properties":{"publicId":{"type":"string","description":"The public ID of the operating model resource."},"name":{"type":"string","description":"The name of the operating model resource.\n\nFor a relation type:\n- If the direction is `to_target`, the value is the `role` of the relation type.\n- If the direction is `to_source`, the value is the `co-role` of the inverse relation type.\n"}}},"AssetFilter":{"description":"A filter applied to candidate assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API and published on https://developer.collibra.com/.","type":"object","additionalProperties":true},"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true}}},"paths":{"/controls/{controlId}/requirements":{"get":{"tags":["Controls"],"summary":"Retrieve the requirements of a control","description":"Returns the requirements (if any) defined for a given `Control`.\n\nThe `requirements` of a `Control` are `AssetFilter` objects defined in the query of the `Control`\nand that define `isRequirement` as `true`.\n","operationId":"getControlRequirements","parameters":[{"$ref":"#/components/parameters/controlId"}],"responses":{"200":{"$ref":"#/components/responses/ControlRequirementsResponse"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Enable a control

> 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\`.<br>

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"responses":{"BadRequest":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"Forbidden":{"description":"The user is forbidden to execute the requested action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFound":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true}}},"paths":{"/controls/{controlId}/enable":{"post":{"tags":["Controls"],"summary":"Enable a control","description":"Enables a control by setting its enabled status to `true`.\n\nBefore you can enable a control, the following conditions must be met:\n- The control must have a control query defined.\n- The control query must be valid.\n- All the mandatory properties of the control have been defined, such as `name` and `severity`.\n","operationId":"enableControl","responses":{"204":{"description":"The control was enabled successfully."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Disable a control

> Disables a control by setting its enabled status to \`false\`.

```json
{"openapi":"3.1.0","info":{"title":"Collibra Control Tower Management API","version":"1.0.0"},"tags":[{"name":"Controls","description":"Create, retrieve, update, delete, enable, and disable controls. Use these endpoints to manage the full\nlifecycle of a control, including its query, notification settings, and execution schedule.\n"}],"servers":[{"url":"/rest/controlManagement/v1"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"description":"This API requires Basic HTTP authentication.","type":"http","scheme":"basic"}},"responses":{"BadRequest":{"description":"The request is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"Forbidden":{"description":"The user is forbidden to execute the requested action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}},"NotFound":{"description":"The resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardErrorResponse"}}}}},"schemas":{"StandardErrorResponse":{"description":"A standard error response object.","type":"object","properties":{"statusCode":{"description":"HTTP response code.","type":"integer"},"titleMessage":{"description":"The title of the error message.","type":"string"},"helpMessage":{"description":"A message containing actions you can take regarding the error.","type":"string"},"userMessage":{"description":"A user friendly error message.","type":"string"},"errorCode":{"description":"An error code identifier.","type":"string"},"query":{"description":"The rejected control query, with each issue attached to the part of the query it applies to\nand `isValid` set to `false`.\n\nOnly present when the request was refused because of its query.\n","allOf":[{"$ref":"#/components/schemas/ControlQuery"}]}},"required":["statusCode","errorCode","userMessage"]},"ControlQuery":{"description":"The query that defines the logic for finding non-compliant assets.\n\nThe shape of this object is defined by the `Collibra Control Tower Query Model`, which is versioned\nseparately from this API. Its specification is published on https://developer.collibra.com/, both as an\nOpenAPI document and as a JSON Schema you can validate a query against.","type":"object","additionalProperties":true}}},"paths":{"/controls/{controlId}/disable":{"post":{"tags":["Controls"],"summary":"Disable a control","description":"Disables a control by setting its enabled status to `false`.","operationId":"disableControl","responses":{"204":{"description":"The control was disabled successfully."},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.collibra.com/api/references/control-tower/controls.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
