# Channels API

The Uptizm API has 6 endpoints on this resource, one section each.

## List notification channels

`GET /notification-channels`

The team's notification channels, newest first, page-numbered.

- URL: `https://api.uptizm.com/v1/notification-channels`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `channels:read`
- Tag: Channels
- operationId: `v1.notification-channels.index`

### Response 200

Content type: `application/json`.

- `data` (array of NotificationChannelResource, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `channel_type` (string, one of `"slack"`, `"webhook"`, `"pagerduty"`, `"teams"`, required)
  - `is_enabled` (boolean, required)
  - `severity` (string, one of `"all"`, `"critical"`, required)
  - `credentials` (object or object or object or object, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)
- `links` (object, required)
  - `first` (string or null, required)
  - `last` (string or null, required)
  - `prev` (string or null, required)
  - `next` (string or null, required)
- `meta` (object, required)
  - `current_page` (integer, min 1, required)
  - `from` (integer or null, min 1, required)
  - `last_page` (integer, min 1, required)
  - `links` (array of object, required): Generated paginator links.
    - `url` (string or null, required)
    - `label` (string, required)
    - `active` (boolean, required)
  - `path` (string or null, required): Base path for paginator generated URLs.
  - `per_page` (integer, min 0, required): Number of items shown per page.
  - `to` (integer or null, min 1, required): Number of the last item in the slice.
  - `total` (integer, min 0, required): Total number of items being paginated.
  - `push_provisioned` (boolean, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Create a notification channel

`POST /notification-channels`

Creates a channel alerts are delivered through.

- URL: `https://api.uptizm.com/v1/notification-channels`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `channels:write`
- Tag: Channels
- operationId: `v1.notification-channels.store`

### Parameters

- `Idempotency-Key` (header, string): Any unique string per logical request.

### Request body

Content type: `application/json`.

- `name` (string, max length 200, required)
- `channel_type` (NotificationChannelType: string, one of `"slack"`, `"webhook"`, `"pagerduty"`, `"teams"`, required): The delivery driver a notification channel sends through.
- `credentials` (object, required)
  - `token` (string or null, max length 255)
  - `channel` (string or null, max length 200)
  - `url` (string or null, max length 2048)
  - `secret` (string or null, max length 255)
  - `routing_key` (string or null, max length 64)
- `is_enabled` (boolean)
- `severity` (NotificationChannelSeverity: string, one of `"all"`, `"critical"`): Which incidents a channel fires for: all of them or only critical ones.

### Response 201

Content type: `application/json`.

- `data` (NotificationChannelResource, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `channel_type` (string, one of `"slack"`, `"webhook"`, `"pagerduty"`, `"teams"`, required)
  - `is_enabled` (boolean, required)
  - `severity` (string, one of `"all"`, `"critical"`, required)
  - `credentials` (object or object or object or object, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Get a notification channel

`GET /notification-channels/{channel}`

One channel of the team.

- URL: `https://api.uptizm.com/v1/notification-channels/{channel}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `channels:read`
- Tag: Channels
- operationId: `v1.notification-channels.show`

### Parameters

- `channel` (path, string, required): The channel ID

### Response 200

Content type: `application/json`.

- `data` (NotificationChannelResource, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `channel_type` (string, one of `"slack"`, `"webhook"`, `"pagerduty"`, `"teams"`, required)
  - `is_enabled` (boolean, required)
  - `severity` (string, one of `"all"`, `"critical"`, required)
  - `credentials` (object or object or object or object, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Update a notification channel

`PUT /notification-channels/{channel}`

Updates the channel.

- URL: `https://api.uptizm.com/v1/notification-channels/{channel}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `channels:write`
- Tag: Channels
- operationId: `v1.notification-channels.update`

### Parameters

- `channel` (path, string, required): The channel ID

### Request body

Content type: `application/json`.

- `name` (string, max length 200)
- `channel_type` (NotificationChannelType: string, one of `"slack"`, `"webhook"`, `"pagerduty"`, `"teams"`): The delivery driver a notification channel sends through.
- `credentials` (object)
  - `token` (string or null, max length 255)
  - `channel` (string or null, max length 200)
  - `routing_key` (string or null, max length 64)
  - `url` (string or null, max length 2048)
  - `secret` (string or null, max length 255)
- `is_enabled` (boolean)
- `severity` (NotificationChannelSeverity: string, one of `"all"`, `"critical"`): Which incidents a channel fires for: all of them or only critical ones.

### Response 200

Content type: `application/json`.

- `data` (NotificationChannelResource, required)
  - `id` (string, required)
  - `team_id` (string, required)
  - `name` (string, required)
  - `channel_type` (string, one of `"slack"`, `"webhook"`, `"pagerduty"`, `"teams"`, required)
  - `is_enabled` (boolean, required)
  - `severity` (string, one of `"all"`, `"critical"`, required)
  - `credentials` (object or object or object or object, required)
  - `created_at` (string or null, required)
  - `updated_at` (string or null, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 422: Validation error
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Delete a notification channel

`DELETE /notification-channels/{channel}`

Deletes the channel.

- URL: `https://api.uptizm.com/v1/notification-channels/{channel}`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `channels:write`
- Tag: Channels
- operationId: `v1.notification-channels.destroy`

### Parameters

- `channel` (path, string, required): The channel ID

### Response 204

No body.

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md

## Send a test notification

`POST /notification-channels/{channel}/test`

Sends a test message through the channel and reports whether it was delivered.

- URL: `https://api.uptizm.com/v1/notification-channels/{channel}/test`
- Auth: `Authorization: Bearer upz_...`
- Required ability (`x-required-ability`): `channels:write`
- Tag: Channels
- operationId: `v1.notification-channels.test`

### Parameters

- `channel` (path, string, required): The channel ID
- `Idempotency-Key` (header, string): Any unique string per logical request.

### Response 200

Content type: `application/json`.

- `data` (object, required)
  - `delivered` (boolean, required)

### Errors

- 401: Unauthenticated
- 403: The key lacks the ability this endpoint requires (`required_ability` names it), or the action is not allowed for the team.
- 404: Not found
- 429: Rate limited. Each key may make 120 reads (GET) and 30 writes per minute; wait for `Retry-After` seconds.
- 502: Bad Gateway

Error bodies: https://uptizm.com/docs/errors.md. Rate limits: https://uptizm.com/docs/rate-limits.md. Idempotency: https://uptizm.com/docs/idempotency.md