Alerts and IRM

IRM

Reference

OnCall API

Integrations API

Grafana Cloud

Integrations HTTP API

Create an integration

Required permission: grafana-irm-app.integrations:write

curl "{{API_URL}}/api/v1/integrations/" \
  --request POST \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "Content-Type: application/json" \
  --header "X-Grafana-URL: https://your-stack.grafana.net" \
  --data '{
      "type":"grafana"
  }'

The above command returns JSON structured in the following way:

{
  "id": "CFRPV98RPR1U8",
  "name": "Grafana :blush:",
  "team_id": null,
  "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
  "inbound_email": null,
  "maintenance_mode": null,
  "maintenance_started_at": null,
  "maintenance_end_at": null,
  "type": "grafana",
  "default_route": {
    "id": "RVBE4RKQSCGJ2",
    "escalation_chain_id": "F5JU6KJET33FE",
    "slack": {
      "channel_id": "CH23212D"
    }
  },
  "templates": {
    "grouping_key": null,
    "resolve_signal": null,
    "acknowledge_signal": null,
    "source_link": null,
    "slack": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "web": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "sms": {
      "title": null
    },
    "phone_call": {
      "title": null
    },
    "telegram": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "mobile_app": {
      "title": null,
      "message": null
    },
    "email": {
      "title": null,
      "message": null
    },
    "msteams": {
      "title": null,
      "message": null,
      "image_url": null
    }
  }
}

Integrations are sources of alerts and alert groups for Grafana OnCall. For example, to learn how to integrate Grafana OnCall with Alertmanager refer to Alertmanager.

HTTP request

POST {{API_URL}}/api/v1/integrations/

Parameter	Required	Description
`name`	No	The name of the integration.
`type`	Yes	The type of integration (e.g., `grafana`, `webhook`, `alertmanager`).
`team_id`	No	The ID of the team this integration belongs to.
`labels`	No	A list of static labels to attach to the integration. Each label must have a unique `key`. See Labels for format.
`dynamic_labels`	No	A list of dynamic labels with templated values. Each label must have a unique `key`. See Dynamic labels for format.
`templates`	No	Templates for customizing alert appearance in various channels.
`default_route`	No	Default routing configuration for alerts.

Get integration

Required permission: grafana-irm-app.integrations:read

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
  --request GET \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "Content-Type: application/json" \
  --header "X-Grafana-URL: https://your-stack.grafana.net"

The above command returns JSON structured in the following way:

{
  "id": "CFRPV98RPR1U8",
  "name": "Grafana :blush:",
  "team_id": null,
  "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
  "inbound_email": null,
  "maintenance_mode": null,
  "maintenance_started_at": null,
  "maintenance_end_at": null,
  "type": "grafana",
  "default_route": {
    "id": "RVBE4RKQSCGJ2",
    "escalation_chain_id": "F5JU6KJET33FE",
    "slack": {
      "channel_id": "CH23212D"
    }
  },
  "templates": {
    "grouping_key": null,
    "resolve_signal": null,
    "acknowledge_signal": null,
    "source_link": null,
    "slack": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "web": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "sms": {
      "title": null
    },
    "phone_call": {
      "title": null
    },
    "telegram": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "mobile_app": {
      "title": null,
      "message": null
    },
    "email": {
      "title": null,
      "message": null
    },
    "msteams": {
      "title": null,
      "message": null,
      "image_url": null
    }
  }
}

This endpoint retrieves an integration. Integrations are sources of alerts and alert groups for Grafana OnCall.

HTTP request

GET {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/

List integrations

Required permission: grafana-irm-app.integrations:read

curl "{{API_URL}}/api/v1/integrations/" \
  --request GET \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "Content-Type: application/json" \
  --header "X-Grafana-URL: https://your-stack.grafana.net"

The above command returns JSON structured in the following way:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "CFRPV98RPR1U8",
      "name": "Grafana :blush:",
      "team_id": null,
      "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
      "inbound_email": null,
      "maintenance_mode": null,
      "maintenance_started_at": null,
      "maintenance_end_at": null,
      "type": "grafana",
      "default_route": {
        "id": "RVBE4RKQSCGJ2",
        "escalation_chain_id": "F5JU6KJET33FE",
        "slack": {
          "channel_id": "CH23212D"
        }
      },
      "templates": {
        "grouping_key": null,
        "resolve_signal": null,
        "acknowledge_signal": null,
        "source_link": null,
        "slack": {
          "title": null,
          "message": null,
          "image_url": null
        },
        "web": {
          "title": null,
          "message": null,
          "image_url": null
        },
        "sms": {
          "title": null
        },
        "phone_call": {
          "title": null
        },
        "telegram": {
          "title": null,
          "message": null,
          "image_url": null
        },
        "mobile_app": {
          "title": null,
          "message": null
        },
        "email": {
          "title": null,
          "message": null
        },
        "msteams": {
          "title": null,
          "message": null,
          "image_url": null
        }
      }
    }
  ],
  "current_page_number": 1,
  "page_size": 50,
  "total_pages": 1
}

Note: The response is paginated. You may need to make multiple requests to get all records.

HTTP request

GET {{API_URL}}/api/v1/integrations/

Update integration

Required permission: grafana-irm-app.integrations:write

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
  --request PUT \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "Content-Type: application/json" \
  --header "X-Grafana-URL: https://your-stack.grafana.net" \
  --data '{
    "templates": {
      "grouping_key": null,
      "resolve_signal": null,
      "slack": {
        "title": null,
        "message": null,
        "image_url": null
      }
    }
  }'

The above command returns JSON structured in the following way:

{
  "id": "CFRPV98RPR1U8",
  "name": "Grafana :blush:",
  "team_id": null,
  "link": "{{API_URL}}/integrations/v1/grafana/mReAoNwDm0eMwKo1mTeTwYo/",
  "inbound_email": null,
  "maintenance_mode": null,
  "maintenance_started_at": null,
  "maintenance_end_at": null,
  "type": "grafana",
  "default_route": {
    "id": "RVBE4RKQSCGJ2",
    "escalation_chain_id": "F5JU6KJET33FE",
    "slack": {
      "channel_id": "CH23212D"
    }
  },
  "templates": {
    "grouping_key": null,
    "resolve_signal": null,
    "slack": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "web": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "email": {
      "title": null,
      "message": null
    },
    "sms": {
      "title": null
    },
    "phone_call": {
      "title": null
    },
    "telegram": {
      "title": null,
      "message": null,
      "image_url": null
    },
    "mobile_app": {
      "title": null,
      "message": null
    }
  }
}

HTTP request

PUT {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/

Parameter	Required	Description
`name`	No	The name of the integration.
`team_id`	No	The ID of the team this integration belongs to.
`labels`	No	A list of static labels to attach to the integration. Each label must have a unique `key`. See Labels for format.
`dynamic_labels`	No	A list of dynamic labels with templated values. Each label must have a unique `key`. See Dynamic labels for format.
`templates`	No	Templates for customizing alert appearance in various channels.
`default_route`	No	Default routing configuration for alerts.

Start maintenance

Required permission: grafana-irm-app.maintenance:write

Starts a maintenance window on an integration. While the window is active, the integration handles incoming alerts according to the selected mode. The window stops automatically after duration seconds, or when you call Stop maintenance.

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/maintenance_start" \
  --request POST \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "Content-Type: application/json" \
  --header "X-Grafana-URL: https://your-stack.grafana.net" \
  --data '{
      "mode": "group_alerts",
      "duration": 3600
  }'

The above command returns the updated integration object, including the populated maintenance_mode, maintenance_started_at, and maintenance_end_at fields.

HTTP request

POST {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/maintenance_start

Parameter	Required	Description
`mode`	Yes	How alerts are handled during the maintenance window. Refer to the following list of supported values.
`duration`	Yes	Length of the maintenance window in seconds. Must be a positive integer.

Supported mode values:

silence_escalations: Alerts are created but escalations are paused.
group_alerts: All alerts are collected into a single maintenance alert group without escalation.
disable_alerts: Incoming alerts are ignored until the maintenance window ends.

Response codes

200 OK: Maintenance started; returns the updated integration object.
400 Bad Request: Invalid mode or duration, or the integration is already in maintenance.

Stop maintenance

Required permission: grafana-irm-app.maintenance:write

Ends an active maintenance window on an integration before its scheduled end time.

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/maintenance_stop" \
  --request POST \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "Content-Type: application/json" \
  --header "X-Grafana-URL: https://your-stack.grafana.net"

The above command returns the updated integration object with maintenance_mode, maintenance_started_at, and maintenance_end_at reset to null.

HTTP request

POST {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/maintenance_stop

This endpoint takes no request body.

Delete integration

Required permission: grafana-irm-app.integrations:write

Deleted integrations will stop recording new alerts from monitoring. Integration removal won’t trigger removal of related alert groups or alerts.

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
  --request DELETE \
  --header "Authorization: Bearer meowmeowmeow" \
  --header "X-Grafana-URL: https://your-stack.grafana.net"

HTTP request

DELETE {{API_URL}}/api/v1/integrations/<INTEGRATION_ID>/

Labels

Labels are key-value pairs that can be attached to integrations for categorization and filtering. Each label must have a unique key within the integration.

{
  "labels": [
    {
      "key": { "name": "team" },
      "value": { "name": "SRE" }
    },
    {
      "key": { "name": "environment" },
      "value": { "name": "production" }
    }
  ]
}

Constraints:

Each label key must be unique within the labels array
Key names must be 1-63 characters, contain only alphanumeric characters and underscores, and cannot start or end with a number or underscore
Value names must be 1-63 characters, contain only alphanumeric characters, hyphens, underscores, and periods, and cannot start or end with a number

Dynamic labels

Dynamic labels are similar to static labels but their values are evaluated at runtime using Jinja2 templates. This allows label values to be extracted from the alert payload. Each dynamic label must have a unique key within the integration.

{
  "dynamic_labels": [
    {
      "key": { "name": "severity" },
      "value": { "name": "{{ payload.get('severity', 'unknown') }}" }
    },
    {
      "key": { "name": "service" },
      "value": { "name": "{{ payload.commonLabels.get('service_name', '') }}" }
    }
  ]
}

Constraints:

Each label key must be unique within the dynamic_labels array
Key names must be 1-63 characters, contain only alphanumeric characters and underscores, and cannot start or end with a number or underscore
Value names can contain Jinja2 template expressions that are evaluated when an alert is received