> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meshai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Notifications API

> Manage notification channels for alerts and policy events

## List Channels

```
GET /notifications/channels
```

Sensitive fields in `config` (PagerDuty routing keys, Slack webhook URLs, webhook secrets) are masked in the response.

```bash theme={null}
curl https://api.meshai.dev/api/v1/notifications/channels \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "01HR3A2QK9XZC4M7QYNVTB5R8E",
        "name": "on-call-pagerduty",
        "channel_type": "pagerduty",
        "config": { "routing_key": "R012ABCD...789A" },
        "enabled": true,
        "events": ["policy.violated", "agent.blocked"],
        "created_at": "2026-03-17T10:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

## Create a Channel

```
POST /notifications/channels
```

`channel_type` must be `pagerduty`, `slack`, `webhook`, or `email`. Any webhook URL in `config` is validated at creation time to guard against SSRF.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/notifications/channels \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "on-call-pagerduty",
    "channel_type": "pagerduty",
    "config": { "routing_key": "R012ABCD1234EFGH56789A" },
    "enabled": true,
    "events": ["policy.violated", "agent.blocked"]
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "01HR3A2QK9XZC4M7QYNVTB5R8E",
      "name": "on-call-pagerduty",
      "channel_type": "pagerduty"
    }
  }
  ```
</ResponseExample>

## Update a Channel

```
PATCH /notifications/channels/{channel_id}
```

`channel_type` cannot be changed after creation. Any of `name`, `config`, `enabled`, `events` may be updated.

```bash theme={null}
curl -X PATCH https://api.meshai.dev/api/v1/notifications/channels/01HR3A2QK9XZC4M7QYNVTB5R8E \
  -H "Authorization: Bearer msh_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

## Delete a Channel

```
DELETE /notifications/channels/{channel_id}
```

```bash theme={null}
curl -X DELETE https://api.meshai.dev/api/v1/notifications/channels/01HR3A2QK9XZC4M7QYNVTB5R8E \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

Returns `204 No Content` on success.

## Send a Test Notification

```
POST /notifications/channels/{channel_id}/test
```

Sends a test payload through the channel to verify its configuration.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/notifications/channels/01HR3A2QK9XZC4M7QYNVTB5R8E/test \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Test notification sent"
    }
  }
  ```
</ResponseExample>

If delivery fails, the endpoint still returns `200 OK` with `success: false` and a `message` explaining the failure, rather than an HTTP error.