---
title: "Create a channel"
method: POST
path: "/v1/channels"
tags: ["Channels"]
---

# Create a channel

`POST /v1/channels`

## Request

- Base URL: `https://api.merlonix.com`
- URL: `https://api.merlonix.com/v1/channels`
- Auth: HTTP bearer

Create an alert notification channel. Requires a `write`-scoped key. The `target` shape depends on `kind` (email address, https webhook URL, `<bot_token>:<chat_id>` for telegram, routing/integration key for pagerduty/opsgenie, or an E.164 phone for sms) and is validated per-kind (`422` on a mismatch). For webhook kinds a signing secret is server-minted and returned only as a `signing_secret_preview`.

## Request body

- ChannelCreate: Request body for creating a notification channel (TD-943).
  - `kind` 'email' | 'slack_webhook' | 'generic_webhook' | 'teams_webhook' | 'discord_webhook' | 'telegram' | 'google_chat' | 'pagerduty' | 'opsgenie' | 'sms', required
  - `name` string, required
  - `target` string, required: email address for kind=email; https webhook URL for slack/teams/discord/google_chat/generic; "<bot_token>:<chat_id>" for telegram; routing/integration key for pagerduty; GenieKey for opsgenie; E.164 phone (+15551234567) for sms. Validated per-kind.
  - `severity_filter` string[]: Severities that page this channel (default: all three).

## Response `201`

The created channel.

- Channel: An alert notification channel (mirrors AlertChannelPublicSchema).
  - `id` string, uuid, required
  - `tenant_id` string, uuid, required
  - `kind` 'email' | 'slack_webhook' | 'generic_webhook' | 'teams_webhook' | 'discord_webhook' | 'telegram' | 'google_chat' | 'pagerduty' | 'opsgenie' | 'sms', required
  - `name` string, required
  - `target` string, required: Destination; shape depends on kind (email / webhook URL / token:chat / routing key / E.164).
  - `signing_secret_preview` string, nullable, required: First 6 chars of the webhook signing secret; null for email + slack channels.
  - `is_active` boolean, required
  - `severity_filter` string[], required
  - `created_at` string, date-time, required
  - `last_delivery` object, nullable, required: TD-1220: most-recent alert delivery to this channel; null when none.
    - `status` string
    - `at` string, date-time
    - `error_message` string, nullable

## Other responses

- `400`: Error — canonical envelope with a trace_id.
- `401`: Error — canonical envelope with a trace_id.
- `403`: Error — canonical envelope with a trace_id.
- `422`: Error — canonical envelope with a trace_id.
- `429`: Error — canonical envelope with a trace_id.

---

[API](https://skmtc.dev/merlonix/apis/merlonix-public-api.md) · [All operations](https://skmtc.dev/merlonix/apis/merlonix-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/merlonix/apis/merlonix-public-api/revisions/2192584bdfcd?raw)