REST API Endpoints for Argus Alert Rules

Alert rules trigger notifications whenever Argus detects a condition matching the rule’s criteria — for example, a new issue being created or an error rate crossing a threshold. You configure each rule with at least one delivery channel: an email address, a webhook URL, or both. You can create multiple rules per project to route notifications to different people or services.

Authentication

All alert endpoints require an active session. Requests without a valid session cookie return 401 Unauthorized.

List Alert Rules

Retrieve all alert rules configured for a project, ordered by creation date descending.

GET /api/v1/projects/:projectId/alerts

Path Parameters

projectId

string

required

The ID of the project whose alert rules you want to list.

Example Request

curl https://your-domain.com/api/v1/projects/clxk2m9ab0000qw8e3f7t1pz2/alerts \
  -H 'Cookie: session=YOUR_SESSION_COOKIE'

Example Response

{
  "statusCode": 200,
  "status": "success",
  "message": "Alerts fetched",
  "data": [
    {
      "id": "clxk5c9de0004qw8e6j1x5td7",
      "projectId": "clxk2m9ab0000qw8e3f7t1pz2",
      "name": "Notify on new issues",
      "type": "NEW_ISSUE",
      "threshold": null,
      "windowMinutes": null,
      "notifyEmail": "oncall@example.com",
      "webhookUrl": null,
      "enabled": true,
      "lastTriggeredAt": "2024-07-15T14:05:34.000Z",
      "createdAt": "2024-07-01T10:00:00.000Z",
      "updatedAt": "2024-07-15T14:05:34.000Z"
    }
  ]
}

Create an Alert Rule

Add a new alert rule to a project. You must provide at least one delivery channel (notifyEmail or webhookUrl).

POST /api/v1/projects/:projectId/alerts

Path Parameters

projectId

string

required

The ID of the project to add the alert rule to.

Request Body

name

string

required

A descriptive name for the alert rule, e.g. "Notify on-call for new errors".

type

string

The trigger condition. Accepted values:

NEW_ISSUE — fires when a new unique issue is first seen. This is the default.
ERROR_RATE — fires when the error rate exceeds a threshold within a time window. Requires threshold and windowMinutes.

Defaults to NEW_ISSUE.

notifyEmail

string

The email address to send alert notifications to. Must be a valid email address. At least one of notifyEmail or webhookUrl is required.

webhookUrl

string

A URL to POST alert payloads to. Must be a valid URL. At least one of notifyEmail or webhookUrl is required.

threshold

integer

For ERROR_RATE rules only: the number of errors that must occur within windowMinutes to trigger the alert. Must be a positive integer.

windowMinutes

integer

For ERROR_RATE rules only: the rolling time window in minutes. Must be a positive integer.

enabled

boolean

Whether the rule is active. Defaults to true. Set to false to create a rule in a disabled state.

Example Request — Email notification on new issue

curl -X POST https://your-domain.com/api/v1/projects/clxk2m9ab0000qw8e3f7t1pz2/alerts \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=YOUR_SESSION_COOKIE' \
  -d '{
    "name": "Notify on-call for new issues",
    "type": "NEW_ISSUE",
    "notifyEmail": "oncall@example.com"
  }'

Example Request — Webhook on error rate spike

curl -X POST https://your-domain.com/api/v1/projects/clxk2m9ab0000qw8e3f7t1pz2/alerts \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=YOUR_SESSION_COOKIE' \
  -d '{
    "name": "Webhook on high error rate",
    "type": "ERROR_RATE",
    "threshold": 50,
    "windowMinutes": 5,
    "webhookUrl": "https://hooks.example.com/argus-alerts"
  }'

Example Response

{
  "statusCode": 201,
  "status": "success",
  "message": "Alert created",
  "data": {
    "id": "clxk5c9de0004qw8e6j1x5td7",
    "projectId": "clxk2m9ab0000qw8e3f7t1pz2",
    "name": "Notify on-call for new issues",
    "type": "NEW_ISSUE",
    "threshold": null,
    "windowMinutes": null,
    "notifyEmail": "oncall@example.com",
    "webhookUrl": null,
    "enabled": true,
    "lastTriggeredAt": null,
    "createdAt": "2024-07-15T16:00:00.000Z",
    "updatedAt": "2024-07-15T16:00:00.000Z"
  }
}

Update an Alert Rule

Update any subset of fields on an existing alert rule. You only need to include the fields you want to change.

PATCH /api/v1/projects/:projectId/alerts/:id

Path Parameters

projectId

string

required

The ID of the project the alert rule belongs to.

string

required

The ID of the alert rule to update.

Request Body

All fields are optional. Supply only the fields you want to change. The same field rules from Create an Alert Rule apply.

Example Request — Disable an alert

curl -X PATCH https://your-domain.com/api/v1/projects/clxk2m9ab0000qw8e3f7t1pz2/alerts/clxk5c9de0004qw8e6j1x5td7 \
  -H 'Content-Type: application/json' \
  -H 'Cookie: session=YOUR_SESSION_COOKIE' \
  -d '{ "enabled": false }'

Example Response

{
  "statusCode": 200,
  "status": "success",
  "message": "Alert updated",
  "data": {
    "id": "clxk5c9de0004qw8e6j1x5td7",
    "projectId": "clxk2m9ab0000qw8e3f7t1pz2",
    "name": "Notify on-call for new issues",
    "type": "NEW_ISSUE",
    "threshold": null,
    "windowMinutes": null,
    "notifyEmail": "oncall@example.com",
    "webhookUrl": null,
    "enabled": false,
    "lastTriggeredAt": "2024-07-15T14:05:34.000Z",
    "createdAt": "2024-07-15T16:00:00.000Z",
    "updatedAt": "2024-07-15T16:30:00.000Z"
  }
}

Delete an Alert Rule

Permanently remove an alert rule from a project. This action is irreversible.

DELETE /api/v1/projects/:projectId/alerts/:id

Path Parameters

projectId

string

required

The ID of the project the alert rule belongs to.

string

required

The ID of the alert rule to delete.

Example Request

curl -X DELETE https://your-domain.com/api/v1/projects/clxk2m9ab0000qw8e3f7t1pz2/alerts/clxk5c9de0004qw8e6j1x5td7 \
  -H 'Cookie: session=YOUR_SESSION_COOKIE'

Example Response

{
  "statusCode": 200,
  "status": "success",
  "message": "Alert deleted"
}

Response Codes

Status	Meaning
`200`	Request succeeded.
`201`	Alert rule created successfully.
`400`	Validation error — check that at least one delivery channel is provided.
`401`	Not authenticated — no valid session.
`404`	Project or alert rule not found.

​Authentication

​List Alert Rules

​Path Parameters

​Example Request

​Example Response

​Create an Alert Rule

​Path Parameters

​Request Body

​Example Request — Email notification on new issue

​Example Request — Webhook on error rate spike

​Example Response

​Update an Alert Rule

​Path Parameters

​Request Body

​Example Request — Disable an alert

​Example Response

​Delete an Alert Rule

​Path Parameters

​Example Request

​Example Response

​Response Codes

Authentication

List Alert Rules

Path Parameters

Example Request

Example Response

Create an Alert Rule

Path Parameters

Request Body

Example Request — Email notification on new issue

Example Request — Webhook on error rate spike

Example Response

Update an Alert Rule

Path Parameters

Request Body

Example Request — Disable an alert

Example Response

Delete an Alert Rule

Path Parameters

Example Request

Example Response

Response Codes