Alerts API

The Alerts API allows you to manage alerts and contact points in Quave Cloud. Alerts notify you when your applications experience issues like high CPU, memory problems, or other conditions.

Make sure to read the Get Started document to understand how the API works.

Overview

The alerting system consists of two main components:

Contact Points - Notification destinations (Slack, PagerDuty, Webhook, Email) where alerts are sent
Alerts - Conditions that trigger notifications when met (e.g., CPU above 80% for 5 minutes)

Contact points are account-level resources, while alerts are scoped to specific app environments.

Contact Points

Contact points define where alert notifications are sent. They are created at the account level and can be used by alerts in any app environment within that account.

Supported Contact Point Types

Type	Required Fields	Optional Fields	Description
`slack`	`webhookUrl`	`channel`, `mentionUsers`	Slack webhook notifications
`pagerduty`	`integrationKey`	`severity`	PagerDuty incident notifications
`webhook`	`url`	`httpMethod`, `username`, `password`	Custom webhook notifications
`email`	`addresses`	-	Email notifications (array of emails)

List Contact Points

Lists all contact points for an account.

Endpoint: GET /api/public/v1/contact-points

Query Parameters:

Field	Type	Required	Description
`accountId`	String	Yes	The ID of the account.

Example:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/contact-points?accountId=YOUR_ACCOUNT_ID'

Example Response:

{
  "contactPoints": [
    {
      "contactPointId": "abc123",
      "name": "Slack Alerts",
      "type": "slack",
      "accountId": "account123",
      "grafanaDeployments": [
        { "region": "us-5", "grafanaContactPointUid": "graf123" }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Get Contact Point

Gets details of a specific contact point. Use showSecrets=true to view the configuration (requires admin permission).

Endpoint: GET /api/public/v1/contact-point

Query Parameters:

Field	Type	Required	Description
`contactPointId`	String	Yes	The ID of the contact point.
`showSecrets`	Boolean	No	Include config field (requires admin permission).

Example:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/contact-point?contactPointId=abc123&showSecrets=true'

Example Response:

{
  "contactPointId": "abc123",
  "name": "Slack Alerts",
  "type": "slack",
  "config": {
    "webhookUrl": "https://hooks.slack.com/services/...",
    "channel": "#alerts"
  },
  "accountId": "account123",
  "grafanaDeployments": [
    { "region": "us-5", "grafanaContactPointUid": "graf123" }
  ],
  "createdAt": "2024-01-15T10:30:00Z"
}

Create Contact Point

Creates a new contact point for alert notifications.

Endpoint: POST /api/public/v1/contact-point

Request Body:

Field	Type	Required	Description
`accountId`	String	Yes	The ID of the account.
`name`	String	Yes	Name for the contact point (1-50 characters).
`type`	String	Yes	Type: `slack`, `pagerduty`, `webhook`, `email`.
`config`	Object	Yes	Type-specific configuration (see above).

Example: Create Slack Contact Point

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "accountId": "account123",
        "name": "Slack Alerts",
        "type": "slack",
        "config": {
            "webhookUrl": "https://hooks.slack.com/services/...",
            "channel": "#alerts"
        }
    }' \
    https://api.quave.cloud/api/public/v1/contact-point

Example: Create PagerDuty Contact Point

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "accountId": "account123",
        "name": "PagerDuty Oncall",
        "type": "pagerduty",
        "config": {
            "integrationKey": "your-integration-key"
        }
    }' \
    https://api.quave.cloud/api/public/v1/contact-point

Example Response:

{
  "message": "Contact point created successfully",
  "contactPoint": {
    "contactPointId": "abc123",
    "name": "Slack Alerts",
    "type": "slack",
    "accountId": "account123",
    "grafanaDeployments": [],
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Update Contact Point

Updates a contact point name or configuration. Changes are propagated to all deployed Grafana instances.

Endpoint: PATCH /api/public/v1/contact-point

Request Body:

Field	Type	Required	Description
`contactPointId`	String	Yes	The ID of the contact point to update.
`name`	String	No	New name for the contact point.
`config`	Object	No	Updated configuration object.

Example:

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "contactPointId": "abc123",
        "name": "Slack Production Alerts",
        "config": {
            "webhookUrl": "https://hooks.slack.com/services/...",
            "channel": "#production-alerts"
        }
    }' \
    https://api.quave.cloud/api/public/v1/contact-point

Delete Contact Point

Deletes a contact point. Cannot delete if alerts are using this contact point.

Endpoint: DELETE /api/public/v1/contact-point

Query Parameters:

Field	Type	Required	Description
`contactPointId`	String	Yes	The ID of the contact point to delete.

Example:

curl -X DELETE \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/contact-point?contactPointId=abc123'

Example Response:

{
  "message": "Contact point deleted successfully"
}

Note: If alerts are using the contact point, you will receive an error:

{
  "error": "Contact point in use",
  "details": "3 alert(s) are using this contact point. Delete or update them first."
}

Alerts

Alerts monitor your app environments and send notifications when conditions are met.

Alert Metrics

Metric	Description	Default Threshold
`cpu_percent`	CPU % (combined) - CPU usage as percentage of allocated limit	80%
`memory_percent`	Memory % (combined) - Memory usage as percentage of allocated limit	80%
`cpu_usage`	CPU millicores (combined) - CPU usage in millicores (1000 millicores = 1 CPU core)	500m
`memory_usage`	Memory MB (combined) - Memory usage in megabytes	512MB
`cpu_percent_per_pod`	CPU % (individual) - CPU usage per pod - use with max aggregation to find busiest pod	80%
`memory_percent_per_pod`	Memory % (individual) - Memory usage per pod - use with max aggregation to find busiest pod	80%
`cpu_usage_per_pod`	CPU millicores (individual) - CPU usage per pod in millicores	500m
`memory_usage_per_pod`	Memory MB (individual) - Memory usage per pod in MB	512MB

Alert Operators

Operator	Symbol	Description
`gt`	>	Greater than
`lt`	<	Less than

Alert Durations

Duration	Description
`1m`	1 minute
`5m`	5 minutes (default)
`10m`	10 minutes
`15m`	15 minutes
`30m`	30 minutes
`1h`	1 hour

Alert Aggregations

When multiple containers exist, aggregation determines how to combine their values:

Value	Label	Description
`mean`	Average	Average across all containers (default)
`max`	Worst (Max)	Highest value among containers
`min`	Best (Min)	Lowest value among containers
`last`	Last	Most recent value

Alert Query Ranges

How far back to look for metric data when evaluating the alert:

Range	Description
`5m`	Last 5 minutes
`10m`	Last 10 minutes (default)
`15m`	Last 15 minutes
`30m`	Last 30 minutes
`1h`	Last 1 hour
`2h`	Last 2 hours

Alert States

State	Description
`Normal`	Alert condition is not met
`Pending`	Alert condition met, waiting for duration
`Firing`	Alert is active and notifications sent
`NoData`	No data received for alert query
`Error`	Error evaluating alert query

List Alerts

Lists all alerts for an app environment.

Endpoint: GET /api/public/v1/app-env/alerts

Query Parameters:

Field	Type	Required	Description
`appEnvId`	String	Yes	The ID of the app environment.

Example:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/app-env/alerts?appEnvId=YOUR_APP_ENV_ID'

Example Response:

{
  "alerts": [
    {
      "alertId": "alert123",
      "appEnvId": "env123",
      "accountId": "account123",
      "name": "High CPU Alert",
      "description": "Alert when CPU exceeds 80%",
      "metric": "cpu_percent",
      "operator": "gt",
      "threshold": 80,
      "duration": "5m",
      "aggregation": "mean",
      "queryRange": "10m",
      "contactPointIds": ["cp123"],
      "contactPoints": [
        { "contactPointId": "cp123", "name": "Slack Alerts", "type": "slack" }
      ],
      "enabled": true,
      "lastKnownState": "Normal",
      "lastStateCheck": "2024-01-15T10:30:00Z",
      "region": "us-5",
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Get Alert

Gets detailed information about a specific alert.

Endpoint: GET /api/public/v1/alert

Query Parameters:

Field	Type	Required	Description
`alertId`	String	Yes	The ID of the alert.

Example:

curl -X GET \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/alert?alertId=alert123'

Create Alert

Creates a new alert for an app environment. The contact point(s) must already exist.

Endpoint: POST /api/public/v1/app-env/alert

Request Body:

Field	Type	Required	Description
`appEnvId`	String	Yes	The ID of the app environment.
`name`	String	Yes	Name for the alert (1-100 characters).
`description`	String	No	Description of the alert (max 500 characters).
`metric`	String	Yes	Metric to alert on (see table above).
`operator`	String	Yes	Comparison operator (see table above).
`threshold`	Number	Yes	Threshold value.
`duration`	String	Yes	Duration condition must be true (see table above).
`aggregation`	String	No	How to aggregate values (see table above). Default: `mean`.
`queryRange`	String	No	How far back to look for data (see table above). Default: `10m`.
`contactPointIds`	String[]	Yes	Array of contact point IDs for notifications.

Example: Create CPU Alert

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "appEnvId": "env123",
        "name": "High CPU Alert",
        "description": "Alert when CPU usage exceeds 80% for 5 minutes",
        "metric": "cpu_percent",
        "operator": "gt",
        "threshold": 80,
        "duration": "5m",
        "aggregation": "mean",
        "queryRange": "10m",
        "contactPointIds": ["cp123"]
    }' \
    https://api.quave.cloud/api/public/v1/app-env/alert

Example Response:

{
  "message": "Alert created successfully",
  "alert": {
    "alertId": "alert123",
    "name": "High CPU Alert",
    "metric": "cpu_percent",
    "operator": "gt",
    "threshold": 80,
    "duration": "5m",
    "aggregation": "mean",
    "queryRange": "10m",
    "enabled": true,
    "lastKnownState": "Normal",
    "contactPoints": [
      { "contactPointId": "cp123", "name": "Slack Alerts", "type": "slack" }
    ]
  }
}

Update Alert

Updates an alert configuration.

Endpoint: PATCH /api/public/v1/alert

Request Body:

Field	Type	Required	Description
`alertId`	String	Yes	The ID of the alert to update.
`name`	String	No	New name for the alert.
`description`	String	No	New description.
`metric`	String	No	New metric.
`operator`	String	No	New operator.
`threshold`	Number	No	New threshold value.
`duration`	String	No	New duration.
`aggregation`	String	No	New aggregation method.
`queryRange`	String	No	New query range.
`contactPointIds`	String[]	No	New array of contact point IDs.
`enabled`	Boolean	No	Enable or disable the alert.

Example:

curl -X PATCH \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "alertId": "alert123",
        "threshold": 90,
        "duration": "10m"
    }' \
    https://api.quave.cloud/api/public/v1/alert

Delete Alert

Permanently deletes an alert.

Endpoint: DELETE /api/public/v1/alert

Query Parameters:

Field	Type	Required	Description
`alertId`	String	Yes	The ID of the alert to delete.

Example:

curl -X DELETE \
    -H 'Authorization: YOUR_TOKEN' \
    'https://api.quave.cloud/api/public/v1/alert?alertId=alert123'

Toggle Alert

Enables or disables an alert. When disabled, the alert rule is paused in Grafana, which means:

The alert condition is no longer evaluated
No notifications will be sent
The alert state stops updating

This is useful for temporarily silencing alerts during maintenance windows or known issues without deleting the alert configuration.

Endpoint: POST /api/public/v1/alert/toggle

Request Body:

Field	Type	Required	Description
`alertId`	String	Yes	The ID of the alert.
`enabled`	Boolean	Yes	`true` to enable (unpause), `false` to disable (pause).

Example:

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "alertId": "alert123",
        "enabled": false
    }' \
    https://api.quave.cloud/api/public/v1/alert/toggle

Example Response:

{
  "message": "Alert disabled successfully",
  "enabled": false
}

Refresh Alert State

Fetches the current alert state directly from Grafana and updates the cached state. This is useful when:

You want to verify an alert is back to normal after fixing an issue
You want the latest state without waiting for the next automatic refresh
The cached state seems outdated

Endpoint: POST /api/public/v1/alert/refresh

Request Body:

Field	Type	Required	Description
`alertId`	String	Yes	The ID of the alert.

Possible States:

State	Description
`Normal`	Alert condition is not met
`Pending`	Alert condition met, waiting for duration
`Firing`	Alert is active and notifications sent
`NoData`	No data received for alert query
`Error`	Error evaluating alert query

Example:

curl -X POST \
    -H 'Authorization: YOUR_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{
        "alertId": "alert123"
    }' \
    https://api.quave.cloud/api/public/v1/alert/refresh

Example Response:

{
  "state": "Normal",
  "previousState": "Firing",
  "lastStateCheck": "2024-01-15T10:35:00Z"
}

Error Responses

All endpoints may return the following error responses:

Status	Description
`400`	Invalid request (missing required fields, invalid values).
`401`	User not authenticated.
`403`	User doesn't have permission (admin permission required for create/update/delete).
`404`	Resource not found (contact point, alert, or app environment).

Alerts API

Overview​

Contact Points​

Supported Contact Point Types​

List Contact Points​

Get Contact Point​

Create Contact Point​

Update Contact Point​

Delete Contact Point​

Alerts​

Alert Metrics​

Alert Operators​

Alert Durations​

Alert Aggregations​

Alert Query Ranges​

Alert States​

List Alerts​

Get Alert​

Create Alert​

Update Alert​

Delete Alert​

Toggle Alert​

Refresh Alert State​

Error Responses​

Overview

Contact Points

Supported Contact Point Types

List Contact Points

Get Contact Point

Create Contact Point

Update Contact Point

Delete Contact Point

Alerts

Alert Metrics

Alert Operators

Alert Durations

Alert Aggregations

Alert Query Ranges

Alert States

List Alerts

Get Alert

Create Alert

Update Alert

Delete Alert

Toggle Alert

Refresh Alert State

Error Responses