ControlUp Alerts API
Alerts let you receive notifications or automatically run an action when certain conditions occur on a device.
OpenAPI Specification
openapi: 3.2.0
info:
title: Controlup Alerts API
version: '1.0'
description: 'Operations tagged Alerts across 3 of this provider''s published API definitions: controlup-desktops-openapi.yml, controlup-dex-alerts-openapi.yml, controlup-synthetic-monitoring-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.controlup.com/edge/api
- url: https://api.controlup.com/events/v1/alerts
- url: https://api.controlup.com/synthetic-monitoring/v2/
tags:
- name: Alerts
description: Alerts let you receive notifications or automatically run an action when certain conditions occur on a device.
paths:
/alerts:
servers:
- url: https://api.controlup.com/edge/api
get:
summary: List all Alerts
tags:
- Alerts
description: "Returns a list of configured alerts.\n\nYou can either:\n * Use `query` to use an OpenSearch query. Note that you can't create an OpenSearch query using the request builder built into the documentation.\n * Use the remaining query parameters to query alerts.\n"
operationId: get-alerts
parameters:
- in: query
name: query
description: An OpenSearch query.
schema:
type: object
default: false
- in: query
name: size
description: The number of rows returned per page.
schema:
type: integer
default: 10000
maximum: 10000
- in: query
name: page
description: The page returned. The number of rows per page is set with the `size` parameter.
schema:
type: integer
default: 1
- in: query
name: from
description: The index of the `rows` array to start returning data from. The array index starts at 0. For example, if you set `from` = 2, the first two rows are excluded.
schema:
type: integer
example: 2
- $ref: '#/components/parameters/FilterField'
- $ref: '#/components/parameters/FilterType'
- $ref: '#/components/parameters/FilterValue'
- $ref: '#/components/parameters/SorterField'
- $ref: '#/components/parameters/SorterDir'
responses:
'200':
description: List of configured alerts.
content:
application/json:
schema:
type: object
properties:
rows:
type: array
items:
allOf:
- type: object
properties:
_id:
type: string
description: Unique identifier for the alert.
example: izWJPJcBOClmoe-Yecr0
- $ref: '#/components/schemas/Alert'
'400':
description: The provided query is invalid.
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
security:
- bearerAuth: []
post:
summary: Create an Alert
description: Creates a new Alert.
tags:
- Alerts
operationId: create-alert
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- platform
- index
- filters
- results_threshold
- results_threshold_seconds
- retrigger_interval
- severity
properties:
name:
$ref: '#/components/schemas/Alert/properties/name'
description:
$ref: '#/components/schemas/Alert/properties/description'
severity:
$ref: '#/components/schemas/Alert/properties/severity'
enabled:
$ref: '#/components/schemas/Alert/properties/enabled'
platform:
$ref: '#/components/schemas/Alert/properties/platform'
results_threshold_seconds:
$ref: '#/components/schemas/Alert/properties/results_threshold_seconds'
results_threshold:
$ref: '#/components/schemas/Alert/properties/results_threshold'
retrigger_interval:
$ref: '#/components/schemas/Alert/properties/retrigger_interval'
index:
$ref: '#/components/schemas/Alert/properties/index'
filters:
$ref: '#/components/schemas/Alert/properties/filters'
webhook_url:
$ref: '#/components/schemas/Alert/properties/webhook_url'
script_id:
$ref: '#/components/schemas/Alert/properties/script_id'
user_script_id:
$ref: '#/components/schemas/Alert/properties/user_script_id'
survey_id:
$ref: '#/components/schemas/Alert/properties/survey_id'
email_addresses:
$ref: '#/components/schemas/Alert/properties/email_addresses'
servicenow_raise_incident:
$ref: '#/components/schemas/Alert/properties/servicenow_raise_incident'
servicenow_ticket_type:
$ref: '#/components/schemas/Alert/properties/servicenow_ticket_type'
servicenow_impact:
$ref: '#/components/schemas/Alert/properties/servicenow_impact'
servicenow_urgency:
$ref: '#/components/schemas/Alert/properties/servicenow_urgency'
servicenow_autoclose_interval:
$ref: '#/components/schemas/Alert/properties/servicenow_autoclose_interval'
responses:
'200':
description: Alert created.
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
security:
- bearerAuth: []
/alerts/{id}:
servers:
- url: https://api.controlup.com/edge/api
get:
summary: Retrieve Alert
tags:
- Alerts
description: 'Returns an alert by its ID.
'
operationId: get-alert
parameters:
- in: path
name: id
description: ID of the alert to retrieve.
required: true
schema:
type: string
responses:
'200':
description: Alert details.
content:
application/json:
schema:
allOf:
- type: object
properties:
_id:
type: string
description: Unique identifier for the alert.
example: izWJPJcBOClmoe-Yecr0
- $ref: '#/components/schemas/Alert'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
security:
- bearerAuth: []
post:
summary: Edit alert
description: Edits an existing alert by its ID. Any parameters not passed are unchanged.
tags:
- Alerts
operationId: edit-alert
parameters:
- in: path
name: id
description: ID of the alert to edit.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Alert'
responses:
'200':
description: Alert edited
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
security:
- bearerAuth: []
delete:
summary: Delete alert
description: Deletes an existing alert by its ID.
tags:
- Alerts
operationId: delete-alert
parameters:
- in: path
name: id
description: ID of the alert to delete.
required: true
schema:
type: string
responses:
'200':
description: Alert deleted
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
security:
- bearerAuth: []
/organizations/{orgId}/alert-configs:
servers:
- url: https://api.controlup.com/events/v1/alerts
get:
operationId: AlertsConfigsController_getAll
responses:
'200':
description: Ok
content:
application/json:
schema:
$ref: '#/components/schemas/APIPaginatedResponse_AlertMetadataDTO-Array_'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
'401':
description: 'Unauthorized: Access is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
'403':
description: 'Forbidden: Access to this resource is denied'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
'404':
description: 'Not Found: The requested resource could not be found'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
description: Returns a list of configured alerts.
summary: List all Alerts
tags:
- Alerts
security:
- apiKey: []
parameters:
- description: 'The page of results to return.
The first page is page number 1.'
in: query
name: _page
required: false
schema:
default: '1'
format: int32
type: integer
minimum: 1
example: 1
style: form
- description: The number of results returned per page.
in: query
name: _limit
required: false
schema:
default: '10'
format: int32
type: integer
minimum: 1
example: 10
style: form
- description: Sorts results according to the specified field.
in: query
name: _sortBy
required: false
schema:
default: id
type: string
example: id
style: form
- description: The sort order (ascending / descending) of the field specified by the `_sortBy` parameter.
in: query
name: _order
required: false
schema:
default: asc
type: string
enum:
- asc
- desc
example: asc
style: form
- description: 'A search filter that is applied to all fields.
Only results that contain the specified string are returned.'
in: query
name: _search
required: false
schema:
type: string
style: form
- description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
in: path
name: orgId
required: true
schema:
$ref: '#/components/schemas/UUID'
- description: "JSON filter for narrowing results. Send this value as a URL-encoded JSON string.\n\nExample:\n```\n%7B%22and%22%3A%20%5B%7B%22filter%22%3A%20%7B%22key%22%3A%20%22type%22%2C%20%22op%22%3A%20%22equals%22%2C%20%22value%22%3A%20%22anomaly%22%7D%7D%2C%7B%22filter%22%3A%20%7B%22key%22%3A%20%22severity%22%2C%20%22op%22%3A%20%22equals%22%2C%20%22value%22%3A%20%22low%22%7D%7D%5D%7D\n```\n\nDecoded value:\n```\n{\n \"and\": [\n {\n \"filter\": {\n \"key\": \"type\",\n \"op\": \"equals\",\n \"value\": \"anomaly\"\n }\n },\n {\n \"filter\": {\n \"key\": \"severity\",\n \"op\": \"equals\",\n \"value\": \"low\"\n }\n }\n ]\n}\n```"
in: query
name: filters
required: false
schema:
type: string
style: form
/alerts/scouts:
servers:
- url: https://api.controlup.com/synthetic-monitoring/v2/
get:
summary: List Scout IDs with alerts
description: 'Returns a list of Scout IDs that have triggered an alert within the specified time frame. The default time frame is the last 24 hours.
'
operationId: honeycomb.api.get_scout_alerts
security:
- ApiKeyAuth:
- read
parameters:
- in: query
name: start
description: Start date and time of the search.
schema:
type: string
format: date-time
example: '2021-01-01 13:21:55'
- in: query
name: end
description: End date and time of the search.
schema:
type: string
format: date-time
example: '2021-02-01 10:24:55'
tags:
- Alerts
responses:
'200':
$ref: '#/components/responses/AlertList'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
x-codeSamples:
- lang: cURL
source: 'curl -X GET ''https://api.scoutbees.io/honeycomb/v2/alerts/scouts?start=2023-09-26 08:00:00&end=2023-09-27 01:30:00'' \
-H ''x-scoutbees-key: API-key-here''
'
/alerts/{scoutId}:
servers:
- url: https://api.controlup.com/synthetic-monitoring/v2/
get:
summary: List alerts for a Scout
description: Returns alerts generated within the specified time frame for a Scout. The default time frame is the last 24 hours.
operationId: app.get_alert_for_scout
security:
- ApiKeyAuth:
- read
parameters:
- name: scoutId
in: path
description: ID of the Scout.
schema:
type: string
required: true
- name: start
in: query
description: Start date and time of the search. The start date can be up to 1 year in the past. The total search duration from the start time to the end time can be a maximum of 24 hours.
schema:
type: string
format: date-time
example: '2023-09-26 08:00:00'
- name: end
in: query
description: End date and time of the search.
schema:
type: string
format: date-time
example: '2023-09-27 01:30:00'
- name: page
in: query
description: The page of alerts to return. Each page contains up to 100 alerts. If your request returns more than 100 alerts, then the response is paginated.
schema:
type: integer
tags:
- Alerts
responses:
'200':
$ref: '#/components/responses/AlertItem'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/ServerError'
x-codeSamples:
- lang: cURL
source: 'curl -X GET ''https://api.scoutbees.io/honeycomb/v2/alerts/7852?start=2023-09-26 08:00:00&end=2023-09-27 01:30:00'' \
-H ''x-scoutbees-key: API-key-here''
'
/scouts/{scoutId}/alerts:
servers:
- url: https://api.controlup.com/synthetic-monitoring/v2/
get:
summary: List alert policies for a Scout
description: Returns all alert policies configured for a Scout. Currently, each Scout supports only a single alert policy.
operationId: app.get_scout_alert_policies
security:
- ApiKeyAuth:
- read
parameters:
- name: scoutId
in: path
description: ID of the Scout.
schema:
type: integer
required: true
tags:
- Alerts
responses:
'200':
$ref: '#/components/responses/AlertSummaryList'
'400':
$ref: '#/components/responses/New400'
'401':
$ref: '#/components/responses/New401'
'404':
$ref: '#/components/responses/New404'
'500':
$ref: '#/components/responses/New500'
x-codeSamples:
- lang: cURL
source: 'curl -X GET ''https://api.scoutbees.io/honeycomb/v2/scouts/7852/alerts'' \
-H ''x-scoutbees-key: API-key-here''
'
post:
summary: Create alert policy
description: Creates a new alert policy for a Scout. A Scout can have only one alert policy. If one already exists, you can update it or delete it. Alerts trigger when the Scout's test results meet certain conditions.
operationId: app.create_scout_alert
security:
- ApiKeyAuth:
- write
parameters:
- name: scoutId
in: path
description: ID of the Scout.
schema:
type: integer
required: true
requestBody:
$ref: '#/components/requestBodies/AlertCreate'
tags:
- Alerts
responses:
'201':
description: Alert created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the request was successful.
data:
type: object
properties:
alertId:
type: integer
description: ID of the created alert.
'400':
$ref: '#/components/responses/New400'
'401':
$ref: '#/components/responses/New401'
'404':
$ref: '#/components/responses/New404'
'500':
$ref: '#/components/responses/New500'
x-codeSamples:
- lang: cURL
source: "curl -X POST 'https://api.scoutbees.io/honeycomb/v2/scouts/7852/alerts' \\\n-H 'x-scoutbees-key: API-key-here' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"conditions\": {\n \"field\": \"status\",\n \"operator\": \"==\",\n \"value\": \"failure\"\n },\n \"settings\": {\n \"consecutiveMatchCount\": 2\n }\n}'\n"
/scouts/{scoutId}/alerts/{alertId}:
servers:
- url: https://api.controlup.com/synthetic-monitoring/v2/
get:
summary: Get alert policy details
description: Returns detailed information about a specific alert policy for a Scout, including settings, notifications, and status.
operationId: app.get_scout_alert
security:
- ApiKeyAuth:
- read
parameters:
- name: scoutId
in: path
description: ID of the Scout.
schema:
type: integer
required: true
- name: alertId
in: path
description: ID of the Scout's alert policy. Currently, each Scout supports only a single alert policy.
schema:
type: integer
required: true
tags:
- Alerts
responses:
'200':
$ref: '#/components/responses/AlertDetails'
'400':
$ref: '#/components/responses/New400'
'401':
$ref: '#/components/responses/New401'
'404':
$ref: '#/components/responses/New404'
'500':
$ref: '#/components/responses/New500'
x-codeSamples:
- lang: cURL
source: 'curl -X GET ''https://api.scoutbees.io/honeycomb/v2/scouts/7852/alerts/123'' \
-H ''x-scoutbees-key: API-key-here''
'
patch:
summary: Update alert policy
description: Updates an existing alert policy for a specific Scout. Any object not passed is unchanged.
operationId: app.update_scout_alert
security:
- ApiKeyAuth:
- write
parameters:
- name: scoutId
in: path
description: ID of the Scout.
schema:
type: integer
required: true
- name: alertId
in: path
description: 'ID of the Scout''s alert policy. Currently, each Scout supports only a single alert policy.
You can use [GET /scouts/{scoutId}/alerts](appget_scout_alert_policies) to get the ID of a Scout''s alert policy.
'
schema:
type: integer
required: true
requestBody:
$ref: '#/components/requestBodies/AlertUpdate'
tags:
- Alerts
responses:
'200':
description: Alert was updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Whether the request was successful.
data:
type: object
properties:
alertId:
type: integer
description: ID of the updated alert.
'400':
$ref: '#/components/responses/New400'
'401':
$ref: '#/components/responses/New401'
'404':
$ref: '#/components/responses/New404'
'500':
$ref: '#/components/responses/New500'
x-codeSamples:
- lang: cURL
source: "curl -X PATCH 'https://api.scoutbees.io/honeycomb/v2/scouts/7852/alerts/123' \\\n-H 'x-scoutbees-key: API-key-here' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n \"disabled\": true,\n \"conditions\": {\n \"field\": \"status\",\n \"operator\": \"==\",\n \"value\": \"failure\"\n },\n \"settings\": {\n \"consecutiveMatchCount\": 2\n }\n}'\n"
delete:
summary: Delete alert policy
description: Deletes an Scout's alert policy.
operationId: app.delete_scout_alert
security:
- ApiKeyAuth:
- write
parameters:
- name: scoutId
in: path
description: ID of the Scout.
schema:
type: integer
required: true
- name: alertId
in: path
description: ID of the Scout's alert policy. Currently, each Scout supports only a single alert policy.
schema:
type: integer
required: true
tags:
- Alerts
responses:
'204':
description: Alert was deleted successfully
'400':
$ref: '#/components/responses/New400'
'401':
$ref: '#/components/responses/New401'
'404':
$ref: '#/components/responses/New404'
'500':
$ref: '#/components/responses/New500'
x-codeSamples:
- lang: cURL
source: "curl -X DELETE 'https://api.scoutbees.io/honeycomb/v2/scouts/7852/alerts/123' \\\n-H 'x-scoutbees-key: API-key-here' \\\n-H 'Content-Type: application/json' \n"
components:
schemas:
AlertConditionGroupTraceroute:
title: Condition Group
description: 'Group of conditions or condition groups with AND/OR operators. Supports nesting up to 5 levels deep.
'
type: object
required:
- operator
- rules
properties:
operator:
type: string
description: Logical operator for combining rules in this group.
enum:
- AND
- OR
example: AND
rules:
type: array
description: "List of conditions or condition groups. Must contain at least \n1 and at most 5 items.\n"
minItems: 1
maxItems: 5
items:
$ref: '#/components/schemas/AlertConditionObjectTraceroute'
example:
- field: status
operator: ==
value: failure
- operator: OR
rules:
- field: latency
operator: '>'
value: 80
- field: packetLoss
operator: '>'
value: 90
AlertSummary:
title: Alert Summary
description: Summary information about an alert policy for a Scout.
type: object
properties:
alertId:
type: integer
description: ID of the alert policy.
example: 123
scoutId:
type: integer
description: ID of the Scout.
example: 7852
subType:
type: string
description: Scout platform/subtype.
enum:
- citrix_gateway
- citrix_cloud
- citrix_storefront
- avd
- vmware_horizon
- vmware_cloud
- vmware_w1
- vmware_secsrv
- net_ping
- net_traceroute
- net_dns
- net_http
- siteload
- shell
- entra_id
- ms_exchange
- ms_teams
- web_transactions
example: net_http
conditions:
$ref: '#/components/schemas/AlertTerminalRuleResponse'
description: "Alert conditions that must be met for the alert to trigger. \n\nThe response structure can vary as an alert policy can have multiple nested conditions in condition groups with AND/OR operators. \nSee the [POST /scouts/{scoutId}/alerts](appcreate_scout_alert) request body for more detailed information about the conditions object.\n"
readableConditions:
type: string
description: Human-readable representation of the alert conditions.
example: status == failure
required:
- alertId
- scoutId
- subType
- conditions
Alert:
type: object
properties:
enabled:
type: boolean
description: Indicates if the alert is enabled.
example: true
platform:
type: integer
format: int32
description: "OS platform. This determines which scripts are available to select as a followup action when the alert is triggered. This does not determine which devices can trigger the script. \n* 0 - No platform selected\n* 1 - Windows\n* 2 - macOS\n* 3 - Linux\n* 4 - ChromeOS \n"
example: 1
servicenow_raise_incident:
type: string
description: Indicates if the Alert raises a ServiceNow ticket when it activates. "true" means that a ticket is raised.
example: 'true'
servicenow_ticket_type:
type: integer
format: int32
description: 'Type of ServiceNow ticket.
* `1` = Incident
* `2` = Event
'
example: 1
servicenow_impact:
type: integer
format: int32
description: 'Impact level for the ServiceNow ticket.
* `1` = High
* `2` = Medium
* `3` = Low
'
example: 2
servicenow_urgency:
type: integer
format: int32
description: 'Urgency level for the ServiceNow ticket.
* `1` = High
* `2` = Medium
* `3` = Low
'
example: 2
servicenow_autoclose_interval:
type: integer
format: int32
description: Auto-close interval for the ServiceNow ticket in seconds.
example: 300
name:
type: string
description: Name of the alert.
example: My first alert
description:
type: string
description: Description of the alert.
example: Description of my first alert goes here
index:
type: string
description: Index associated with the alert. The alerts conditions (located in `filters) must be based off of fields in the data index.
example: device_status
filters:
type: array
description: List of conditions for the alert to activate. Multiple conditions are combined using AND operators.
items:
type: object
properties:
field:
type: string
description: Field to filter on.
example: cpuload
type:
type: string
description: Type of comparison. Note that if you are filtering on a string field, you must use the "like" filter type.
example: '>'
enum:
- '='
- '!='
- '>='
- '>'
- <=
- <
- like
value:
type: string
description: Value to compare against. Numbers can be passed as strings.
example: '1'
results_threshold:
type: integer
format: int32
description: The number of times that the conditions must be met within the time window (`results_threshold_seconds`) for the trigger to activate.
example: 5
results_threshold_seconds:
type: integer
format: int32
description: The length of time in seconds that the alert system searches back to check whether the alert's activation conditions were met.
example: 600
retrigger_interval:
type: integer
format: int32
description: The minimum duration between subsequent alert activations. If the retrigger interval duration has not passed since the last alert activation, then the alert won't activate even if all conditions are met.
example: 3600
severity:
type: integer
format: int32
description: 'Severity level of the alert.
* 1 - Informational
* 2 - Low
* 3 - Medium
* 4 - High
* 5 - Critical
'
example: 4
evaluation_mode:
type: integer
format: int32
description: Internal use only.
example: 1
webhook_url:
type:
- string
- 'null'
format: uri
description: URL for a webhook to be triggered.
example: https://your-domain.com/webhook-endpoint
script_id:
type:
- string
- 'null'
description: ID of a system script to run on devices that trigger the alert. You can use [GET /scripts](list-all-scripts) to see script IDs.
example: fpwG-4oB1426LInH16YF
user_script_id:
type:
- string
- 'null'
description: ID of a user script to run on devices that trigger the alert. You can use [GET /scripts](list-all-scripts) to see script IDs.
example: fpwG-4oB1426LInH16YF
script_arguments:
type:
- string
- 'null'
description: Internal use only.
survey_id:
type:
- string
- 'null'
description: ID of an on-demand survey to run on devices that trigger the alert. You can use [GET /surveys](get-surveys) to see survey IDs.
example: fpwG-4oB1426LInH16YF
email_addresses:
type: string
description: A semicolon-separated list of email addresses to receive an email when the alert triggers.
example: firstemail@gmail.com;secondemail@gmail.com
SubType:
type: object
title: List of sub types of the
properties:
subType:
description: The Scout's sub-type.
type: string
enum:
- citrix
- citrix_cloud
- storefront
- euc_avd
- vmware
- vmware_cloud
- vmware_ws_one
- vmware_sec_server
- net_ping
- net_traceroute
- net_dns
- net_http
- net_siteload
- app_shell
- app_azure_ad
- app_ms_exchange
- app_ms_teams
# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/controlup/refs/heads/main/openapi/controlup-alerts-api-openapi.yml