Alerts

Download schema

Problems Spectate or an alert source detected. An alert escalates along its escalation path until someone acknowledges it, and resolves on its own when the problem is over, or when someone resolves it by hand. Resolved alerts can be deleted. Alerts can lead to incidents.

List alerts

GET

https://api.spectate.net/v1

/alerts

Returns the team's alerts, most recently fired first unless you sort.

List alerts › query Parameters

page

integer

Page number, from 1.

Default: 1

per_page

integer

Alerts per page, 1 to 100.

Default: 25

filter[status]

AlertStatus · enum

Only firing or resolved alerts.

Whether an alert's problem is ongoing.


`firing` The problem is ongoing; it escalates until acknowledged.
`resolved` The problem is over.

Enum values:

firing

resolved

filter[severity]

Severity · enum

Only alerts of this severity.

How urgent an alert or incident is. Escalation paths can branch on it.


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

filter[source_type]

AlertSourceType · enum

Only alerts raised by this kind of check or integration.

What raised an alert.


`uptime` A monitor went down.
`certificate` A monitor's certificate is invalid or expires soon.
`performance` A monitor got slow.
`dns` The answer of a DNS monitor changed (when it alerts on changes).
`host_metric` A host's metric condition held, or it stopped sending data.
`domain` A domain expires soon, expired or its registration changed.
`external` An alert source (external tool) fired it.
`status_page` Visitor issue reports over the threshold or a traffic spike (`metadata.type`: `issue_reports`, `traffic_spike`).

Enum values:

uptime

certificate

performance

dns

host_metric

domain

external

status_page

filter[resource_id]

string · uuid

Only alerts about this resource (a monitor, host, domain, status page or alert source ID).

filter[acknowledged]

boolean

Only acknowledged (true) or unacknowledged (false) alerts.

sort

string

Sort by fired_at, resolved_at, severity or status. Prefix - for descending. Default -fired_at.

List alerts › Responses

Paginated set of Alert

current_page

integer · min: 1 · required

Alert[] · required

first_page_url

string | null · required

from

integer | null · min: 1 · required

last_page_url

string | null · required

last_page

integer · min: 1 · required

object[] · required

Generated paginator links.

next_page_url

string | null · required

path

string | null · required

Base path for paginator generated URLs.

per_page

integer · min: 0 · required

Number of items shown per page.

prev_page_url

string | null · required

to

integer | null · min: 1 · required

Number of the last item in the slice.

total

integer · min: 0 · required

Total number of items being paginated.

GET/alerts

curl https://api.spectate.net/v1/alerts \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "current_page": 1,
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "title": "Website is down",
      "description": "description",
      "status": "firing",
      "severity": "critical",
      "source_type": "uptime",
      "resource": {
        "type": "monitor",
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "Website"
      },
      "fired_at": "2024-08-25T15:00:00Z",
      "acknowledged_at": "2024-08-25T15:00:00Z",
      "acknowledged_by": "Jane Doe",
      "resolved_at": "2024-08-25T15:00:00Z",
      "resolved_by": "Jane Doe",
      "labels": {
        "key": "string"
      },
      "links": [
        {
          "label": "View issue in Sentry",
          "url": "https://www.example.com/path/to/resource"
        }
      ]
    }
  ],
  "first_page_url": "first_page_url",
  "from": 1,
  "last_page_url": "last_page_url",
  "last_page": 1,
  "links": [
    {
      "url": "url",
      "label": "label",
      "active": true
    }
  ],
  "next_page_url": "next_page_url",
  "path": "path",
  "per_page": 0,
  "prev_page_url": "prev_page_url",
  "to": 1,
  "total": 0
}

json

application/json

Get an alert

GET

https://api.spectate.net/v1

/alerts/{alert}

Returns the alert with the resource it's about and who acknowledged it.

Get an alert › path Parameters

alert

string · uuid · required

Alert ID.

Get an alert › Responses

The alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.

Alert

id

string · uuid · required

Alert ID

title

string · required

What's wrong

Example: Website is down

description

string | null · required

More about it, as the source described it

status

AlertStatus · enum · required

Whether the problem is ongoing


`firing` The problem is ongoing; it escalates until acknowledged.
`resolved` The problem is over.

Enum values:

firing

resolved

severity

Severity · enum · required

How urgent it is


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

source_type

AlertSourceType · enum · required

What raised it


`uptime` A monitor went down.
`certificate` A monitor's certificate is invalid or expires soon.
`performance` A monitor got slow.
`dns` The answer of a DNS monitor changed (when it alerts on changes).
`host_metric` A host's metric condition held, or it stopped sending data.
`domain` A domain expires soon, expired or its registration changed.
`external` An alert source (external tool) fired it.
`status_page` Visitor issue reports over the threshold or a traffic spike (`metadata.type`: `issue_reports`, `traffic_spike`).

Enum values:

uptime

certificate

performance

dns

host_metric

domain

external

status_page

required

fired_at

string · date-time · required

When it fired

acknowledged_at

string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by

string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe

resolved_at

string | null · date-time · required

When it resolved; null while firing

resolved_by

string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe

object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

AlertLink[] · required

Links the source sent along

GET/alerts/{alert}

curl https://api.spectate.net/v1/alerts/:alert \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "Website is down",
  "description": "description",
  "status": "firing",
  "severity": "critical",
  "source_type": "uptime",
  "resource": {
    "type": "monitor",
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Website"
  },
  "fired_at": "2024-08-25T15:00:00Z",
  "acknowledged_at": "2024-08-25T15:00:00Z",
  "acknowledged_by": "Jane Doe",
  "resolved_at": "2024-08-25T15:00:00Z",
  "resolved_by": "Jane Doe",
  "labels": {
    "key": "string"
  },
  "links": [
    {
      "label": "View issue in Sentry",
      "url": "https://www.example.com/path/to/resource"
    }
  ]
}

json

application/json

Delete an alert

DELETE

https://api.spectate.net/v1

/alerts/{alert}

Deletes a resolved alert for good, with its escalation history. Incidents and status page incidents it led to stay, without the link to it; messages already posted in Slack or Telegram stay in their channels. A firing alert can't be deleted: resolve it first.

Delete an alert › path Parameters

alert

string · uuid · required

Alert ID.

Delete an alert › Responses

No content

No data returned

Acknowledge an alert

POST

https://api.spectate.net/v1

/alerts/{alert}/acknowledge

Stops its escalation: nobody else is notified. The alert keeps firing until the problem is over. The dashboard, Slack and Telegram show it as acknowledged by the API token. Acknowledging an acknowledged or resolved alert changes nothing.

Acknowledge an alert › path Parameters

alert

string · uuid · required

Alert ID.

Acknowledge an alert › Responses

The acknowledged alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.

Alert

id

string · uuid · required

Alert ID

title

string · required

What's wrong

Example: Website is down

description

string | null · required

More about it, as the source described it

status

AlertStatus · enum · required

Whether the problem is ongoing


`firing` The problem is ongoing; it escalates until acknowledged.
`resolved` The problem is over.

Enum values:

firing

resolved

severity

Severity · enum · required

How urgent it is


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

source_type

AlertSourceType · enum · required

What raised it


`uptime` A monitor went down.
`certificate` A monitor's certificate is invalid or expires soon.
`performance` A monitor got slow.
`dns` The answer of a DNS monitor changed (when it alerts on changes).
`host_metric` A host's metric condition held, or it stopped sending data.
`domain` A domain expires soon, expired or its registration changed.
`external` An alert source (external tool) fired it.
`status_page` Visitor issue reports over the threshold or a traffic spike (`metadata.type`: `issue_reports`, `traffic_spike`).

Enum values:

uptime

certificate

performance

dns

host_metric

domain

external

status_page

required

fired_at

string · date-time · required

When it fired

acknowledged_at

string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by

string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe

resolved_at

string | null · date-time · required

When it resolved; null while firing

resolved_by

string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe

object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

AlertLink[] · required

Links the source sent along

POST/alerts/{alert}/acknowledge

curl https://api.spectate.net/v1/alerts/:alert/acknowledge \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "Website is down",
  "description": "description",
  "status": "firing",
  "severity": "critical",
  "source_type": "uptime",
  "resource": {
    "type": "monitor",
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Website"
  },
  "fired_at": "2024-08-25T15:00:00Z",
  "acknowledged_at": "2024-08-25T15:00:00Z",
  "acknowledged_by": "Jane Doe",
  "resolved_at": "2024-08-25T15:00:00Z",
  "resolved_by": "Jane Doe",
  "labels": {
    "key": "string"
  },
  "links": [
    {
      "label": "View issue in Sentry",
      "url": "https://www.example.com/path/to/resource"
    }
  ]
}

json

application/json

Resolve an alert

POST

https://api.spectate.net/v1

/alerts/{alert}/resolve

Ends the alert by hand, as if its problem were over: its escalation stops, the channels and on-call members it notified hear that it resolved, Slack and Telegram show it as resolved by the API token, and status pages automated from an uptime alert show the monitor as recovered. Use it for false alarms, or for alerts whose source can't tell they're over.

If the problem is still there, the source fires a new alert at its next check (a monitor that is still down, a host metric still over its limit). Resolving a resolved alert changes nothing.

Resolve an alert › path Parameters

alert

string · uuid · required

Alert ID.

Resolve an alert › Responses

The resolved alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.

Alert

id

string · uuid · required

Alert ID

title

string · required

What's wrong

Example: Website is down

description

string | null · required

More about it, as the source described it

status

AlertStatus · enum · required

Whether the problem is ongoing


`firing` The problem is ongoing; it escalates until acknowledged.
`resolved` The problem is over.

Enum values:

firing

resolved

severity

Severity · enum · required

How urgent it is


`critical` Customers are affected right now.
`high` Serious, needs attention soon.
`medium` Should be looked at.
`low` Informational.

Enum values:

critical

high

medium

low

source_type

AlertSourceType · enum · required

What raised it


`uptime` A monitor went down.
`certificate` A monitor's certificate is invalid or expires soon.
`performance` A monitor got slow.
`dns` The answer of a DNS monitor changed (when it alerts on changes).
`host_metric` A host's metric condition held, or it stopped sending data.
`domain` A domain expires soon, expired or its registration changed.
`external` An alert source (external tool) fired it.
`status_page` Visitor issue reports over the threshold or a traffic spike (`metadata.type`: `issue_reports`, `traffic_spike`).

Enum values:

uptime

certificate

performance

dns

host_metric

domain

external

status_page

required

fired_at

string · date-time · required

When it fired

acknowledged_at

string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by

string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe

resolved_at

string | null · date-time · required

When it resolved; null while firing

resolved_by

string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe

object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

AlertLink[] · required

Links the source sent along

POST/alerts/{alert}/resolve

curl https://api.spectate.net/v1/alerts/:alert/resolve \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "title": "Website is down",
  "description": "description",
  "status": "firing",
  "severity": "critical",
  "source_type": "uptime",
  "resource": {
    "type": "monitor",
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Website"
  },
  "fired_at": "2024-08-25T15:00:00Z",
  "acknowledged_at": "2024-08-25T15:00:00Z",
  "acknowledged_by": "Jane Doe",
  "resolved_at": "2024-08-25T15:00:00Z",
  "resolved_by": "Jane Doe",
  "labels": {
    "key": "string"
  },
  "links": [
    {
      "label": "View issue in Sentry",
      "url": "https://www.example.com/path/to/resource"
    }
  ]
}

json

application/json

Alert sources On-call