Configure alert routing

POST /alerts/config

Accepts a generic AlertingConfig JSON, renders it into a valid Alertmanager YAML configuration, and pushes it to Mimir. SMTP settings are injected server-side. A built-in history webhook (ALERTING_HISTORY_WEBHOOK_URL) is always included and cannot be disabled. Priority order: per-system overrides > per-severity overrides > global settings. Address fallback: if an override's address list is empty, global addresses are used.

Query parameters

organization_id string

Target organization ID. Required for Owner, Distributor, and Reseller roles. Customer role uses their own organization automatically.

application/json

Body Required

mail_enabled boolean

Globally enable or disable email notifications

Default value is false.
webhook_enabled boolean

Globally enable or disable custom webhook notifications

Default value is false.
telegram_enabled boolean

Globally enable or disable Telegram notifications

Default value is false.
mail_addresses array[string(email)]

Global default email recipients
webhook_receivers array[object]

Global default webhook receivers
Hide webhook_receivers attributes Show webhook_receivers attributes object
- name string Required
  
  Descriptive name for this webhook receiver
- url string(uri) Required
  
  Webhook URL
telegram_receivers array[object]

Global Telegram bot receivers
Hide telegram_receivers attributes Show telegram_receivers attributes object
- bot_token string Required
  
  Telegram bot token obtained from @BotFather
- chat_id integer(int64) Required
  
  Numeric Telegram chat ID (user, group, or channel)
severities array[object]

Per-severity overrides. Empty list = use global settings for all severities.
Hide severities attributes Show severities attributes object
- severity string Required
  
  Values are critical, warning, or info.
- mail_enabled boolean | null
  
  Override global mail_enabled for this severity
- webhook_enabled boolean | null
  
  Override global webhook_enabled for this severity
- telegram_enabled boolean | null
  
  Override global telegram_enabled for this severity
- mail_addresses array[string(email)]
  
  Email addresses for this severity. Inherits global addresses if empty.
- webhook_receivers array[object]
  
  Webhook receivers for this severity. Inherits global receivers if empty.
  Hide webhook_receivers attributes Show webhook_receivers attributes object
  
  name string Required
  
  Descriptive name for this webhook receiver
  
  url string(uri) Required
  
  Webhook URL
- telegram_receivers array[object]
  
  Telegram receivers for this severity. Inherits global receivers if empty.
  Hide telegram_receivers attributes Show telegram_receivers attributes object
  
  bot_token string Required
  
  Telegram bot token obtained from @BotFather
  
  chat_id integer(int64) Required
  
  Numeric Telegram chat ID (user, group, or channel)
systems array[object]

Per-system_key overrides (highest priority). Empty list = no per-system overrides.
Hide systems attributes Show systems attributes object
- system_key string Required
  
  The system_key label value to match
- mail_enabled boolean | null
  
  Override global mail_enabled for this system
- webhook_enabled boolean | null
  
  Override global webhook_enabled for this system
- telegram_enabled boolean | null
  
  Override global telegram_enabled for this system
- mail_addresses array[string(email)]
  
  Email addresses for this system. Inherits global addresses if empty.
- webhook_receivers array[object]
  
  Webhook receivers for this system. Inherits global receivers if empty.
  Hide webhook_receivers attributes Show webhook_receivers attributes object
  
  name string Required
  
  Descriptive name for this webhook receiver
  
  url string(uri) Required
  
  Webhook URL
- telegram_receivers array[object]
  
  Telegram receivers for this system. Inherits global receivers if empty.
  Hide telegram_receivers attributes Show telegram_receivers attributes object
  
  bot_token string Required
  
  Telegram bot token obtained from @BotFather
  
  chat_id integer(int64) Required
  
  Numeric Telegram chat ID (user, group, or channel)
email_template_lang string

Language for email and Telegram notification templates. "en" (English, default) or "it" (Italian).

Values are en or it. Default value is en.

Responses

200 application/json

Alerting configuration updated
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
400 application/json

Bad request - validation error
Hide response attributes Show response attributes object
- code integer
  
  HTTP error code
- message string
  
  Error message
- data object
  
  Hide data attributes Show data attributes object
  
  type string
  
  Type of error
  
  Values are validation_error or external_api_error.
  
  errors array[object]
  
  Hide errors attributes Show errors attributes object
  
  key string
  
  Field name that failed validation
  
  message string
  
  Error code or message
  
  value string
  
  Value that failed validation
  
  details
  
  Additional error details
401 application/json

Unauthorized - invalid or missing token
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
403 application/json

Forbidden - insufficient permissions
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null
500 application/json

Internal server error
Hide response attributes Show response attributes object
- code integer
- message string
- data object | null

POST /alerts/config

curl \
 --request POST 'https://api.your-domain.com/api/alerts/config' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"mail_enabled":true,"webhook_enabled":true,"telegram_enabled":true,"mail_addresses":["global@example.com"],"webhook_receivers":[{"name":"slack","url":"https://hooks.slack.com/services/T00/B00/XXX"}],"telegram_receivers":[{"bot_token":"123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11","chat_id":-1001234567890}],"email_template_lang":"en","severities":[{"severity":"critical","mail_enabled":true,"webhook_enabled":true,"mail_addresses":["oncall@example.com"]},{"severity":"warning","mail_enabled":false,"webhook_enabled":false}],"systems":[{"system_key":"ns8-prod-01","mail_enabled":false,"webhook_enabled":true}]}'

Request examples

{
  "mail_enabled": true,
  "webhook_enabled": true,
  "telegram_enabled": true,
  "mail_addresses": [
    "global@example.com"
  ],
  "webhook_receivers": [
    {
      "name": "slack",
      "url": "https://hooks.slack.com/services/T00/B00/XXX"
    }
  ],
  "telegram_receivers": [
    {
      "bot_token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
      "chat_id": -1001234567890
    }
  ],
  "email_template_lang": "en",
  "severities": [
    {
      "severity": "critical",
      "mail_enabled": true,
      "webhook_enabled": true,
      "mail_addresses": [
        "oncall@example.com"
      ]
    },
    {
      "severity": "warning",
      "mail_enabled": false,
      "webhook_enabled": false
    }
  ],
  "systems": [
    {
      "system_key": "ns8-prod-01",
      "mail_enabled": false,
      "webhook_enabled": true
    }
  ]
}

Response examples (200)

{
  "code": 200,
  "message": "string",
  "data": {}
}

Response examples (400)

{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}

Response examples (401)

{
  "code": 401,
  "message": "invalid token",
  "data": {}
}

Response examples (403)

{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}

Response examples (500)

{
  "code": 500,
  "message": "internal server error",
  "data": {}
}