1. docs
  2. api
  3. resources
  4. alerts
Start Monitoring

Alerts

Create and manage alerts for email, Slack, Discord, and webhook notifications. Maximum 10 per team.Last updated: 2026-02-14

Alerts notify you when monitors detect issues. Each team can have up to 10 alerts with different notification strategies: email, webhook, Slack, or Discord.

Sensitive data such as webhook URLs and secrets are never returned in API responses for security.

GET /v1/alerts

Returns all alerts for your team.

Required Scope

alerts:read

Example Request

cURL

curl https://api.uptime.example.com/v1/alerts \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"alerts": [
		{
			"id": "alt_abc123",
			"name": "Email Alert",
			"strategy": "email",
			"notifyOnRecovery": true,
			"cooldownMinutes": 5,
			"monitorId": null,
			"createdAt": "2026-02-14T10:00:00Z",
			"updatedAt": "2026-02-14T10:00:00Z"
		},
		{
			"id": "alt_def456",
			"name": "Slack Notifications",
			"strategy": "slack",
			"notifyOnRecovery": true,
			"cooldownMinutes": 0,
			"monitorId": "mon_abc123",
			"createdAt": "2026-02-14T11:00:00Z",
			"updatedAt": "2026-02-14T11:00:00Z"
		}
	]
}

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have alerts:read scope
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["alerts"],
	"properties": {
		"alerts": {
			"type": "array",
			"items": {
				"type": "object",
				"required": [
					"id",
					"name",
					"strategy",
					"notifyOnRecovery",
					"cooldownMinutes",
					"monitorId",
					"createdAt",
					"updatedAt"
				],
				"properties": {
					"id": {
						"type": "string",
						"pattern": "^alt_[a-zA-Z0-9]+$"
					},
					"name": {
						"type": "string",
						"minLength": 1,
						"maxLength": 100
					},
					"strategy": {
						"type": "string",
						"enum": ["email", "webhook", "slack", "discord"]
					},
					"notifyOnRecovery": {
						"type": "boolean"
					},
					"cooldownMinutes": {
						"type": "integer",
						"minimum": 0,
						"maximum": 1440
					},
					"monitorId": {
						"type": ["string", "null"],
						"pattern": "^mon_[a-zA-Z0-9]+$"
					},
					"createdAt": {
						"type": "string",
						"format": "date-time"
					},
					"updatedAt": {
						"type": "string",
						"format": "date-time"
					}
				}
			}
		}
	}
}

POST /v1/alerts

Creates a new alert. The request body varies based on the notification strategy.

Required Scope

alerts:write

Common Fields

FieldTypeRequiredDescription
namestringYesDisplay name for the alert
strategystringYesOne of: email, webhook, slack, discord
notifyOnRecoverybooleanNoSend notification when monitor recovers (default: true)
cooldownMinutesintegerNoMinimum minutes between notifications, 0-1440 (default: 0)
monitorIdstringNoLimit alert to a specific monitor

Strategy: Email

FieldTypeRequiredDescription
emailstringYesEmail address to notify
subjectPrefixstringNoPrefix for email subject lines

Strategy: Webhook

FieldTypeRequiredDescription
urlstringYesWebhook URL to POST notifications to
secretstringNoSecret for HMAC signature verification

Strategy: Slack

FieldTypeRequiredDescription
webhookUrlstringYesSlack incoming webhook URL
channelstringNoOverride the default channel

Strategy: Discord

FieldTypeRequiredDescription
webhookUrlstringYesDiscord webhook URL

Example Request (Email)

cURL

curl -X POST https://api.uptime.example.com/v1/alerts \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Email Alert",
    "strategy": "email",
    "email": "alerts@example.com",
    "subjectPrefix": "[Uptime]",
    "notifyOnRecovery": true,
    "cooldownMinutes": 5
  }'

Example Request (Webhook)

cURL

curl -X POST https://api.uptime.example.com/v1/alerts \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PagerDuty Integration",
    "strategy": "webhook",
    "url": "https://events.pagerduty.com/integration/abc123/enqueue",
    "secret": "whsec_your_secret_key"
  }'

Example Request (Slack)

cURL

curl -X POST https://api.uptime.example.com/v1/alerts \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack #incidents",
    "strategy": "slack",
    "webhookUrl": "https://hooks.slack.com/services/T00/B00/xxx",
    "channel": "#incidents"
  }'

Example Request (Discord)

cURL

curl -X POST https://api.uptime.example.com/v1/alerts \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discord Server Alert",
    "strategy": "discord",
    "webhookUrl": "https://discord.com/api/webhooks/123/abc"
  }'

Response

{
	"id": "alt_abc123",
	"name": "Team Email Alert",
	"strategy": "email",
	"notifyOnRecovery": true,
	"cooldownMinutes": 5,
	"monitorId": null,
	"createdAt": "2026-02-14T12:00:00Z",
	"updatedAt": "2026-02-14T12:00:00Z"
}

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid request body or missing required fields
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have alerts:write scope
409LIMIT_EXCEEDEDTeam already has 10 alerts
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Request Body Schema (Email)

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["name", "strategy", "email"],
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"strategy": {
			"const": "email"
		},
		"email": {
			"type": "string",
			"format": "email"
		},
		"subjectPrefix": {
			"type": "string",
			"maxLength": 50
		},
		"notifyOnRecovery": {
			"type": "boolean",
			"default": true
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440,
			"default": 0
		},
		"monitorId": {
			"type": "string",
			"pattern": "^mon_[a-zA-Z0-9]+$"
		}
	}
}

Request Body Schema (Webhook)

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["name", "strategy", "url"],
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"strategy": {
			"const": "webhook"
		},
		"url": {
			"type": "string",
			"format": "uri"
		},
		"secret": {
			"type": "string"
		},
		"notifyOnRecovery": {
			"type": "boolean",
			"default": true
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440,
			"default": 0
		},
		"monitorId": {
			"type": "string",
			"pattern": "^mon_[a-zA-Z0-9]+$"
		}
	}
}

Request Body Schema (Slack)

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["name", "strategy", "webhookUrl"],
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"strategy": {
			"const": "slack"
		},
		"webhookUrl": {
			"type": "string",
			"format": "uri"
		},
		"channel": {
			"type": "string"
		},
		"notifyOnRecovery": {
			"type": "boolean",
			"default": true
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440,
			"default": 0
		},
		"monitorId": {
			"type": "string",
			"pattern": "^mon_[a-zA-Z0-9]+$"
		}
	}
}

Request Body Schema (Discord)

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["name", "strategy", "webhookUrl"],
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"strategy": {
			"const": "discord"
		},
		"webhookUrl": {
			"type": "string",
			"format": "uri"
		},
		"notifyOnRecovery": {
			"type": "boolean",
			"default": true
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440,
			"default": 0
		},
		"monitorId": {
			"type": "string",
			"pattern": "^mon_[a-zA-Z0-9]+$"
		}
	}
}

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": [
		"id",
		"name",
		"strategy",
		"notifyOnRecovery",
		"cooldownMinutes",
		"monitorId",
		"createdAt",
		"updatedAt"
	],
	"properties": {
		"id": {
			"type": "string",
			"pattern": "^alt_[a-zA-Z0-9]+$"
		},
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"strategy": {
			"type": "string",
			"enum": ["email", "webhook", "slack", "discord"]
		},
		"notifyOnRecovery": {
			"type": "boolean"
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440
		},
		"monitorId": {
			"type": ["string", "null"],
			"pattern": "^mon_[a-zA-Z0-9]+$"
		},
		"createdAt": {
			"type": "string",
			"format": "date-time"
		},
		"updatedAt": {
			"type": "string",
			"format": "date-time"
		}
	}
}

GET /v1/alerts/:id

Returns a single alert by ID.

Required Scope

alerts:read

Example Request

cURL

curl https://api.uptime.example.com/v1/alerts/alt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"id": "alt_abc123",
	"name": "Team Email Alert",
	"strategy": "email",
	"notifyOnRecovery": true,
	"cooldownMinutes": 5,
	"monitorId": null,
	"createdAt": "2026-02-14T12:00:00Z",
	"updatedAt": "2026-02-14T12:00:00Z"
}

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have alerts:read scope
404NOT_FOUNDAlert not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": [
		"id",
		"name",
		"strategy",
		"notifyOnRecovery",
		"cooldownMinutes",
		"monitorId",
		"createdAt",
		"updatedAt"
	],
	"properties": {
		"id": {
			"type": "string",
			"pattern": "^alt_[a-zA-Z0-9]+$"
		},
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"strategy": {
			"type": "string",
			"enum": ["email", "webhook", "slack", "discord"]
		},
		"notifyOnRecovery": {
			"type": "boolean"
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440
		},
		"monitorId": {
			"type": ["string", "null"],
			"pattern": "^mon_[a-zA-Z0-9]+$"
		},
		"createdAt": {
			"type": "string",
			"format": "date-time"
		},
		"updatedAt": {
			"type": "string",
			"format": "date-time"
		}
	}
}

PUT /v1/alerts/:id

Updates an existing alert. You cannot change the strategy field.

Required Scope

alerts:write

Request Body

Include only the fields you want to update. The strategy field cannot be changed.

Example Request

cURL

curl -X PUT https://api.uptime.example.com/v1/alerts/alt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Alert Name",
    "cooldownMinutes": 10,
    "notifyOnRecovery": false
  }'

Response

{
	"id": "alt_abc123",
	"name": "Updated Alert Name",
	"strategy": "email",
	"notifyOnRecovery": false,
	"cooldownMinutes": 10,
	"monitorId": null,
	"createdAt": "2026-02-14T12:00:00Z",
	"updatedAt": "2026-02-14T13:00:00Z"
}

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid request body or attempted to change strategy
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have alerts:write scope
404NOT_FOUNDAlert not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Request Body Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"properties": {
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"email": {
			"type": "string",
			"format": "email"
		},
		"subjectPrefix": {
			"type": "string",
			"maxLength": 50
		},
		"url": {
			"type": "string",
			"format": "uri"
		},
		"secret": {
			"type": "string"
		},
		"webhookUrl": {
			"type": "string",
			"format": "uri"
		},
		"channel": {
			"type": "string"
		},
		"notifyOnRecovery": {
			"type": "boolean"
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440
		},
		"monitorId": {
			"type": ["string", "null"],
			"pattern": "^mon_[a-zA-Z0-9]+$"
		}
	}
}

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": [
		"id",
		"name",
		"strategy",
		"notifyOnRecovery",
		"cooldownMinutes",
		"monitorId",
		"createdAt",
		"updatedAt"
	],
	"properties": {
		"id": {
			"type": "string",
			"pattern": "^alt_[a-zA-Z0-9]+$"
		},
		"name": {
			"type": "string",
			"minLength": 1,
			"maxLength": 100
		},
		"strategy": {
			"type": "string",
			"enum": ["email", "webhook", "slack", "discord"]
		},
		"notifyOnRecovery": {
			"type": "boolean"
		},
		"cooldownMinutes": {
			"type": "integer",
			"minimum": 0,
			"maximum": 1440
		},
		"monitorId": {
			"type": ["string", "null"],
			"pattern": "^mon_[a-zA-Z0-9]+$"
		},
		"createdAt": {
			"type": "string",
			"format": "date-time"
		},
		"updatedAt": {
			"type": "string",
			"format": "date-time"
		}
	}
}

DELETE /v1/alerts/:id

Deletes an alert.

Required Scope

alerts:write

Example Request

cURL

curl -X DELETE https://api.uptime.example.com/v1/alerts/alt_abc123 \
  -H "Authorization: Bearer uptime_your_api_key"

Response

Returns 204 No Content on success.

Possible Errors

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have alerts:write scope
404NOT_FOUNDAlert not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

Returns 204 No Content with no response body on success.

GET /v1/alerts/:id/events

Returns the event history for an alert.

Required Scope

alerts:read

Query Parameters

ParameterTypeRequiredDescription
limitintegerNoNumber of events to return, 1-200 (default: 50)

Example Request

cURL

curl "https://api.uptime.example.com/v1/alerts/alt_abc123/events?limit=10" \
  -H "Authorization: Bearer uptime_your_api_key"

Response

{
	"events": [
		{
			"id": "evt_abc123",
			"alertId": "alt_abc123",
			"monitorId": "mon_def456",
			"type": "triggered",
			"status": "delivered",
			"createdAt": "2026-02-14T10:30:00Z"
		},
		{
			"id": "evt_def456",
			"alertId": "alt_abc123",
			"monitorId": "mon_def456",
			"type": "recovered",
			"status": "delivered",
			"createdAt": "2026-02-14T10:35:00Z"
		}
	]
}

Event Fields

FieldTypeDescription
idstringUnique event identifier
alertIdstringThe alert that was triggered
monitorIdstringThe monitor that caused the event
typestringEvent type: triggered or recovered
statusstringDelivery status: pending, delivered, or failed
createdAtstringISO 8601 timestamp of when the event occurred

Possible Errors

StatusCodeDescription
400VALIDATION_ERRORInvalid limit parameter
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENAPI key doesn't have alerts:read scope
404NOT_FOUNDAlert not found
429RATE_LIMITEDToo many requests
500INTERNAL_ERRORServer error

Response Schema

{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"type": "object",
	"required": ["events"],
	"properties": {
		"events": {
			"type": "array",
			"items": {
				"type": "object",
				"required": ["id", "alertId", "monitorId", "type", "status", "createdAt"],
				"properties": {
					"id": {
						"type": "string",
						"pattern": "^evt_[a-zA-Z0-9]+$"
					},
					"alertId": {
						"type": "string",
						"pattern": "^alt_[a-zA-Z0-9]+$"
					},
					"monitorId": {
						"type": "string",
						"pattern": "^mon_[a-zA-Z0-9]+$"
					},
					"type": {
						"type": "string",
						"enum": ["triggered", "recovered"]
					},
					"status": {
						"type": "string",
						"enum": ["pending", "delivered", "failed"]
					},
					"createdAt": {
						"type": "string",
						"format": "date-time"
					}
				}
			}
		}
	}
}