Channels

Download schema

Where alerts are delivered: email, Slack, Discord, Microsoft Teams, Telegram, webhooks, Pushover, SMS and voice calls. Escalation paths send to channels. A channel that keeps failing is turned off automatically; a successful test turns it back on.

List channels

GET

https://api.spectate.net/v1

/channels

Returns the team's channels, by name.

List channels › query Parameters

filter[type]

ChannelType · enum

Only channels of this type.

Enum values:

slack

discord

microsoft_teams

webhook

pushover

sms

filter[enabled]

boolean

Only enabled (true) or disabled (false) channels.

page

integer

Page number, from 1.

Default: 1

per_page

integer

Channels per page, 1 to 100.

Default: 25

List channels › Responses

Paginated set of Channel

current_page

integer · min: 1 · required

Channel[] · 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/channels

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

Example Responses

{
  "current_page": 1,
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "On-call email",
      "type": "email",
      "enabled": true,
      "auto_disabled": true,
      "disabled_at": "2024-08-25T15:00:00Z",
      "disabled_reason": "disabled_reason",
      "consecutive_failures": 0,
      "failing_since": "2024-08-25T15:00:00Z",
      "last_failure_at": "2024-08-25T15:00:00Z",
      "last_failure_reason": "last_failure_reason",
      "last_delivered_at": "2024-08-25T15:00:00Z",
      "email": {
        "address": "oncall@example.com"
      },
      "slack": {
        "installation_id": "00000000-0000-0000-0000-000000000000",
        "channel": "C0123456789",
        "channel_name": "#alerts"
      },
      "telegram": {
        "chat_id": "-1001234567890",
        "chat_title": "Ops alerts"
      },
      "webhook": {
        "host": "hooks.example.com",
        "header_names": [
          "string"
        ]
      },
      "pushover": {
        "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
        "priority": 1
      },
      "sms": {
        "phone_number": "+31612345678"
      },
      "voice": {
        "phone_number": "+31612345678"
      },
      "created_at": "2024-08-25T15:00:00Z"
    }
  ],
  "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

Create a channel

POST

https://api.spectate.net/v1

/channels

Send type and the settings object of that type, for example type: "email" with email: {address}. Webhook URLs must be public addresses. Slack channels post through a Slack workspace connected under Integrations in the dashboard, Telegram channels are connected there too. Create channels before the escalation paths that use them.

Create a channel › Request Body

A new notification channel: a name, a type, and the settings object of that type (`email` for `email`, `slack` for `slack`…). Send only that one object. Telegram channels are connected from the dashboard.

CreateChannel

name

string · maxLength: 255 · required

Name shown in escalation paths

Example: On-call email

type

ChannelType · enum · required

Where the channel delivers; telegram can't be created through the API

Enum values:

slack

discord

microsoft_teams

webhook

pushover

sms

enabled

boolean

Whether it delivers from the start. Default true

ChannelEmail

Settings of an email channel

ChannelSlackInput

Settings of a slack channel

ChannelWebhookUrlInput

Settings of a discord channel

ChannelWebhookUrlInput

Settings of a microsoft_teams channel

ChannelWebhookInput

Settings of a webhook channel

ChannelPushoverInput

Settings of a pushover channel

ChannelPhone

Settings of an sms channel

ChannelPhone

Settings of a voice channel

Create a channel › Responses

The new channel.

A notification channel: where escalation paths send alerts. The settings of its type are in the object of that name (`email`, `slack`…); the others are `null`. Secrets (webhook URLs, tokens, header values) are never returned.

Channel

id

string · uuid · required

Channel ID

name

string · required

Name shown in escalation paths

Example: On-call email

type

ChannelType · enum · required

Where the channel delivers

Enum values:

slack

discord

microsoft_teams

webhook

pushover

sms

enabled

boolean · required

Whether the channel delivers. false when a member turned it off or Spectate did after repeated failures (auto_disabled)

auto_disabled

boolean · required

Whether Spectate turned the channel off because deliveries kept failing. Fix the cause, then enable it or send a test with enable

disabled_at

string | null · date-time · required

When the channel was turned off automatically

disabled_reason

string | null · required

Why it was turned off automatically

consecutive_failures

integer · required

Failed deliveries since the last successful one

failing_since

string | null · date-time · required

Since when deliveries fail

last_failure_at

string | null · date-time · required

When a delivery last failed

last_failure_reason

string | null · required

Why the last delivery failed

last_delivered_at

string | null · date-time · required

When a delivery last succeeded

required

created_at

string · date-time · required

When the channel was created

POST/channels

curl https://api.spectate.net/v1/channels \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "On-call email",
  "type": "email",
  "enabled": true,
  "email": {
    "address": "oncall@example.com"
  },
  "slack": {
    "installation_id": "00000000-0000-0000-0000-000000000000",
    "channel": "C0123456789",
    "channel_name": "#alerts"
  },
  "discord": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "microsoft_teams": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "webhook": {
    "url": "https://hooks.example.com/spectate",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer s3cr3t"
      }
    ]
  },
  "pushover": {
    "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "api_token": "azGDORePK8gMaC0QOYAMyEEuzJnyUi",
    "priority": 1
  },
  "sms": {
    "phone_number": "+31612345678"
  },
  "voice": {
    "phone_number": "+31612345678"
  }
}'

Example Request Body

{
  "name": "On-call email",
  "type": "email",
  "enabled": true,
  "email": {
    "address": "oncall@example.com"
  },
  "slack": {
    "installation_id": "00000000-0000-0000-0000-000000000000",
    "channel": "C0123456789",
    "channel_name": "#alerts"
  },
  "discord": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "microsoft_teams": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "webhook": {
    "url": "https://hooks.example.com/spectate",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer s3cr3t"
      }
    ]
  },
  "pushover": {
    "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "api_token": "azGDORePK8gMaC0QOYAMyEEuzJnyUi",
    "priority": 1
  },
  "sms": {
    "phone_number": "+31612345678"
  },
  "voice": {
    "phone_number": "+31612345678"
  }
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "On-call email",
  "type": "email",
  "enabled": true,
  "auto_disabled": true,
  "disabled_at": "2024-08-25T15:00:00Z",
  "disabled_reason": "disabled_reason",
  "consecutive_failures": 0,
  "failing_since": "2024-08-25T15:00:00Z",
  "last_failure_at": "2024-08-25T15:00:00Z",
  "last_failure_reason": "last_failure_reason",
  "last_delivered_at": "2024-08-25T15:00:00Z",
  "email": {
    "address": "oncall@example.com"
  },
  "slack": {
    "installation_id": "00000000-0000-0000-0000-000000000000",
    "channel": "C0123456789",
    "channel_name": "#alerts"
  },
  "telegram": {
    "chat_id": "-1001234567890",
    "chat_title": "Ops alerts"
  },
  "webhook": {
    "host": "hooks.example.com",
    "header_names": [
      "string"
    ]
  },
  "pushover": {
    "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "priority": 1
  },
  "sms": {
    "phone_number": "+31612345678"
  },
  "voice": {
    "phone_number": "+31612345678"
  },
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Get a channel

GET

https://api.spectate.net/v1

/channels/{channel}

Returns the channel with its delivery health. Secrets in its settings are never returned.

Get a channel › path Parameters

channel

string · uuid · required

Channel ID.

Get a channel › Responses

The channel.

Channel

id

string · uuid · required

Channel ID

name

string · required

Name shown in escalation paths

Example: On-call email

type

ChannelType · enum · required

Where the channel delivers

Enum values:

slack

discord

microsoft_teams

webhook

pushover

sms

enabled

boolean · required

Whether the channel delivers. false when a member turned it off or Spectate did after repeated failures (auto_disabled)

auto_disabled

boolean · required

Whether Spectate turned the channel off because deliveries kept failing. Fix the cause, then enable it or send a test with enable

disabled_at

string | null · date-time · required

When the channel was turned off automatically

disabled_reason

string | null · required

Why it was turned off automatically

consecutive_failures

integer · required

Failed deliveries since the last successful one

failing_since

string | null · date-time · required

Since when deliveries fail

last_failure_at

string | null · date-time · required

When a delivery last failed

last_failure_reason

string | null · required

Why the last delivery failed

last_delivered_at

string | null · date-time · required

When a delivery last succeeded

required

created_at

string · date-time · required

When the channel was created

GET/channels/{channel}

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

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "On-call email",
  "type": "email",
  "enabled": true,
  "auto_disabled": true,
  "disabled_at": "2024-08-25T15:00:00Z",
  "disabled_reason": "disabled_reason",
  "consecutive_failures": 0,
  "failing_since": "2024-08-25T15:00:00Z",
  "last_failure_at": "2024-08-25T15:00:00Z",
  "last_failure_reason": "last_failure_reason",
  "last_delivered_at": "2024-08-25T15:00:00Z",
  "email": {
    "address": "oncall@example.com"
  },
  "slack": {
    "installation_id": "00000000-0000-0000-0000-000000000000",
    "channel": "C0123456789",
    "channel_name": "#alerts"
  },
  "telegram": {
    "chat_id": "-1001234567890",
    "chat_title": "Ops alerts"
  },
  "webhook": {
    "host": "hooks.example.com",
    "header_names": [
      "string"
    ]
  },
  "pushover": {
    "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "priority": 1
  },
  "sms": {
    "phone_number": "+31612345678"
  },
  "voice": {
    "phone_number": "+31612345678"
  },
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Update a channel

PATCH

https://api.spectate.net/v1

/channels/{channel}

Changes only the fields you send. The settings object of the channel's type replaces the current settings, including secrets: send them again. Other types' objects are refused (422); create a new channel to change the type. Enabling clears an automatic disable.

Update a channel › path Parameters

channel

string · uuid · required

Channel ID.

Update a channel › Request Body

Changes to a channel; fields you leave out keep their value. A channel's type can't change. Its settings object, when you send it, replaces the current settings, secrets included.

UpdateChannel

name

string · maxLength: 255

Name shown in escalation paths

Example: On-call email

enabled

boolean

Turn delivery on or off. Turning it on clears an automatic disable and its failure count

ChannelEmail

New settings of an email channel

ChannelSlackInput

New settings of a slack channel

ChannelWebhookUrlInput

New settings of a discord channel

ChannelWebhookUrlInput

New settings of a microsoft_teams channel

ChannelWebhookInput

New settings of a webhook channel

ChannelPushoverInput

New settings of a pushover channel

ChannelPhone

New settings of an sms channel

ChannelPhone

New settings of a voice channel

Update a channel › Responses

The updated channel.

Channel

id

string · uuid · required

Channel ID

name

string · required

Name shown in escalation paths

Example: On-call email

type

ChannelType · enum · required

Where the channel delivers

Enum values:

slack

discord

microsoft_teams

webhook

pushover

sms

enabled

boolean · required

Whether the channel delivers. false when a member turned it off or Spectate did after repeated failures (auto_disabled)

auto_disabled

boolean · required

Whether Spectate turned the channel off because deliveries kept failing. Fix the cause, then enable it or send a test with enable

disabled_at

string | null · date-time · required

When the channel was turned off automatically

disabled_reason

string | null · required

Why it was turned off automatically

consecutive_failures

integer · required

Failed deliveries since the last successful one

failing_since

string | null · date-time · required

Since when deliveries fail

last_failure_at

string | null · date-time · required

When a delivery last failed

last_failure_reason

string | null · required

Why the last delivery failed

last_delivered_at

string | null · date-time · required

When a delivery last succeeded

required

created_at

string · date-time · required

When the channel was created

PATCH/channels/{channel}

curl https://api.spectate.net/v1/channels/:channel \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "On-call email",
  "enabled": true,
  "email": {
    "address": "oncall@example.com"
  },
  "slack": {
    "installation_id": "00000000-0000-0000-0000-000000000000",
    "channel": "C0123456789",
    "channel_name": "#alerts"
  },
  "discord": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "microsoft_teams": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "webhook": {
    "url": "https://hooks.example.com/spectate",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer s3cr3t"
      }
    ]
  },
  "pushover": {
    "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "api_token": "azGDORePK8gMaC0QOYAMyEEuzJnyUi",
    "priority": 1
  },
  "sms": {
    "phone_number": "+31612345678"
  },
  "voice": {
    "phone_number": "+31612345678"
  }
}'

Example Request Body

{
  "name": "On-call email",
  "enabled": true,
  "email": {
    "address": "oncall@example.com"
  },
  "slack": {
    "installation_id": "00000000-0000-0000-0000-000000000000",
    "channel": "C0123456789",
    "channel_name": "#alerts"
  },
  "discord": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "microsoft_teams": {
    "webhook_url": "https://discord.com/api/webhooks/123/abc"
  },
  "webhook": {
    "url": "https://hooks.example.com/spectate",
    "headers": [
      {
        "key": "Authorization",
        "value": "Bearer s3cr3t"
      }
    ]
  },
  "pushover": {
    "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "api_token": "azGDORePK8gMaC0QOYAMyEEuzJnyUi",
    "priority": 1
  },
  "sms": {
    "phone_number": "+31612345678"
  },
  "voice": {
    "phone_number": "+31612345678"
  }
}

json

Example Responses

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "On-call email",
  "type": "email",
  "enabled": true,
  "auto_disabled": true,
  "disabled_at": "2024-08-25T15:00:00Z",
  "disabled_reason": "disabled_reason",
  "consecutive_failures": 0,
  "failing_since": "2024-08-25T15:00:00Z",
  "last_failure_at": "2024-08-25T15:00:00Z",
  "last_failure_reason": "last_failure_reason",
  "last_delivered_at": "2024-08-25T15:00:00Z",
  "email": {
    "address": "oncall@example.com"
  },
  "slack": {
    "installation_id": "00000000-0000-0000-0000-000000000000",
    "channel": "C0123456789",
    "channel_name": "#alerts"
  },
  "telegram": {
    "chat_id": "-1001234567890",
    "chat_title": "Ops alerts"
  },
  "webhook": {
    "host": "hooks.example.com",
    "header_names": [
      "string"
    ]
  },
  "pushover": {
    "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
    "priority": 1
  },
  "sms": {
    "phone_number": "+31612345678"
  },
  "voice": {
    "phone_number": "+31612345678"
  },
  "created_at": "2024-08-25T15:00:00Z"
}

json

application/json

Delete a channel

DELETE

https://api.spectate.net/v1

/channels/{channel}

Escalation steps that sent to it stay, and are skipped until you point them at another channel. Notifications already sent aren't affected.

Delete a channel › path Parameters

channel

string · uuid · required

Channel ID.

Delete a channel › Responses

No content

No data returned

Send a test notification

POST

https://api.spectate.net/v1

/channels/{channel}/test

Delivers a test through the channel right away and returns when it was accepted. A successful test clears the failure count and, with enable, turns a disabled channel back on. A failed test (422 CHANNEL_TEST_FAILED) doesn't count towards turning it off. SMS and voice tests use the team's notification credits (422 NOTIFICATION_CREDITS_EXHAUSTED without them). Limited to 10 tests a minute per token.

Send a test notification › path Parameters

channel

string · uuid · required

Channel ID.

Send a test notification › Request Body

Options of a channel test.

TestChannel

enable

boolean

Enable the channel again when the test succeeds, also after Spectate turned it off. Default false

Send a test notification › Responses

The test was delivered.

A test notification that was delivered.

ChannelTestResult

message

string · required

What was sent

Example: Test notification sent

Channel · required

The channel after the test: its failure count is cleared, and with enable it's enabled again

POST/channels/{channel}/test

curl https://api.spectate.net/v1/channels/:channel/test \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "enable": true
}'

Example Request Body

{
  "enable": true
}

json

Example Responses

{
  "message": "Test notification sent",
  "channel": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "On-call email",
    "type": "email",
    "enabled": true,
    "auto_disabled": true,
    "disabled_at": "2024-08-25T15:00:00Z",
    "disabled_reason": "disabled_reason",
    "consecutive_failures": 0,
    "failing_since": "2024-08-25T15:00:00Z",
    "last_failure_at": "2024-08-25T15:00:00Z",
    "last_failure_reason": "last_failure_reason",
    "last_delivered_at": "2024-08-25T15:00:00Z",
    "email": {
      "address": "oncall@example.com"
    },
    "slack": {
      "installation_id": "00000000-0000-0000-0000-000000000000",
      "channel": "C0123456789",
      "channel_name": "#alerts"
    },
    "telegram": {
      "chat_id": "-1001234567890",
      "chat_title": "Ops alerts"
    },
    "webhook": {
      "host": "hooks.example.com",
      "header_names": [
        "string"
      ]
    },
    "pushover": {
      "user_key": "uQiRzpo4DXghDmr9QzzfQu27cmVRsG",
      "priority": 1
    },
    "sms": {
      "phone_number": "+31612345678"
    },
    "voice": {
      "phone_number": "+31612345678"
    },
    "created_at": "2024-08-25T15:00:00Z"
  }
}

json

application/json

Projects Escalation paths