Grafana OnCall HTTP API reference on Grafana Labs

Alerts HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

List Alerts

curl "{{API_URL}}/api/v1/alerts/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "AA74DN7T4JQB6",
            "alert_group_id": "I68T24C13IFW1",
            "created_at": "2020-05-11T20:07:43Z",
            "payload": {
                "state": "alerting",
                "title": "[Alerting] Test notification",
                "ruleId": 0,
                "message": "Someone is testing the alert notification within Grafana.",
                "ruleUrl": "{{API_URL}}/",
                "ruleName": "Test notification",
                "evalMatches": [
                    {
                        "tags": null,
                        "value": 100,
                        "metric": "High value"
                    },
                    {
                        "tags": null,
                        "value": 200,
                        "metric": "Higher Value"
                    }
                ]
            }
        },
        {
            "id": "AR9SSYFKE2PV7",
            "alert_group_id": "I68T24C13IFW1",
            "created_at": "2020-05-11T20:07:54Z",
            "payload": {
                "state": "alerting",
                "title": "[Alerting] Test notification",
                "ruleId": 0,
                "message": "Someone is testing the alert notification within Grafana.",
                "ruleUrl": "{{API_URL}}/",
                "ruleName": "Test notification",
                "evalMatches": [
                    {
                        "tags": null,
                        "value": 100,
                        "metric": "High value"
                    },
                    {
                        "tags": null,
                        "value": 200,
                        "metric": "Higher Value"
                    }
                ]
            }
        },
        {
            "id": "AWJQSGEYYUFGH",
            "alert_group_id": "I68T24C13IFW1",
            "created_at": "2020-05-11T20:07:58Z",
            "payload": {
                "state": "alerting",
                "title": "[Alerting] Test notification",
                "ruleId": 0,
                "message": "Someone is testing the alert notification within Grafana.",
                "ruleUrl": "{{API_URL}}/",
                "ruleName": "Test notification",
                "evalMatches": [
                    {
                        "tags": null,
                        "value": 100,
                        "metric": "High value"
                    },
                    {
                        "tags": null,
                        "value": 200,
                        "metric": "Higher Value"
                    }
                ]
            }
        }
    ]
}

The following available filter parameters should be provided as GET arguments:

alert_group_id
search—string-based inclusion search by alert payload

HTTP request

GET {{API_URL}}/api/v1/alerts/

Escalation Chains HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Create an escalation chain

curl "{{API_URL}}/api/v1/escalation_chains/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "example-chain"
  }'

The above command returns JSON structured in the following way:

{
    "id": "FWDL7M6N6I9HE",
    "name": "example-chain",
    "team_id": null
}

Parameter	Required	Description
name	yes	Name of the escalation chain
team_id	no	ID of the team

HTTP request

POST {{API_URL}}/api/v1/escalation_chains/

Get an escalation chain

curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "id": "F5JU6KJET33FE",
    "name": "default",
    "team_id": null
}

HTTP request

GET {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/

List escalation chains

curl "{{API_URL}}/api/v1/escalation_chains/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "F5JU6KJET33FE",
            "name": "default",
            "team_id": null
        }
    ]
}

HTTP request

GET {{API_URL}}/api/v1/escalation_chains/

Delete an escalation chain

curl "{{API_URL}}/api/v1/escalation_chains/F5JU6KJET33FE/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/escalation_chains/<ESCALATION_CHAIN_ID>/

Escalation Policies HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Create an escalation policy

curl "{{API_URL}}/api/v1/escalation_policies/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "escalation_chain_id": "F5JU6KJET33FE",
      "type": "wait",
      "duration": 60
  }'

The above command returns JSON structured in the following way:

{
    "id": "E3GA6SJETWWJS",
    "escalation_chain_id": "F5JU6KJET33FE",
    "position": 0,
    "type": "wait",
    "duration": 60
}

Parameter	Required	Description
`escalation_chain_id`	Yes	Each escalation policy is assigned to a specific escalation chain.
`position`	Optional	Escalation policies execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down in the list.
`type`	Yes	One of: `wait`, `notify_persons`, `notify_person_next_each_time`, `notify_on_call_from_schedule`, `notify_user_group`, `trigger_action`, `resolve`, `notify_whole_channel`, `notify_if_time_from_to`.
`duration`	Optional	The duration, in seconds, when type `wait` is chosen.
`important`	Optional	Default is `false`. Will assign “important” to personal notification rules if `true`. This can be used to distinguish alerts on which you want to be notified immediately by phone. Applicable for types `notify_persons`, `notify_on_call_from_schedule`, and `notify_user_group`.
`action_to_trigger`	If type = `trigger_action`	ID of an action, or webhook.
`group_to_notify`	If type = `notify_user_group`	ID of a `User Group`.
`persons_to_notify`	If type = `notify_persons`	List of user IDs.
`persons_to_notify_next_each_time`	If type = `notify_person_next_each_time`	List of user IDs.
`notify_on_call _from_schedule`	If type = `notify_on_call_from_schedule`	ID of a Schedule.
`notify_if_time_from`	If type = `notify_if_time_from_to`	UTC time represents the beginning of the time period, for example `09:00:00Z`.
`notify_if_time_to`	If type = `notify_if_time_from_to`	UTC time represents the end of the time period, for example `18:00:00Z`.

HTTP request

POST {{API_URL}}/api/v1/escalation_policies/

Get an escalation policy

curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \

The above command returns JSON structured in the following way:

{
    "id": "E3GA6SJETWWJS",
    "escalation_chain_id": "F5JU6KJET33FE",
    "position": 0,
    "type": "wait",
    "duration": 60
}

HTTP request

GET {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/

List escalation policies

curl "{{API_URL}}/api/v1/escalation_policies/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "E3GA6SJETWWJS",
            "escalation_chain_id": "F5JU6KJET33FE",
            "position": 0,
            "type": "wait",
            "duration": 60
        },
        {
            "id": "E5JJTU52M5YM4",
            "escalation_chain_id": "F5JU6KJET33FE",
            "position": 1,
            "type": "notify_person_next_each_time",
            "persons_to_notify_next_each_time": [
                "U4DNY931HHJS5"
            ]
        }
    ]
}

The following available filter parameter should be provided as a GET argument:

escalation_chain_id

HTTP request

GET {{API_URL}}/api/v1/escalation_policies/

Delete an escalation policy

curl "{{API_URL}}/api/v1/escalation_policies/E3GA6SJETWWJS/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/escalation_policies/<ESCALATION_POLICY_ID>/

Alert groups HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

List alert groups

curl "{{API_URL}}/api/v1/alert_groups/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "I68T24C13IFW1",
            "integration_id": "CFRPV98RPR1U8",
            "route_id": "RIYGUJXCPFHXY",
            "alerts_count": 3,
            "state": "resolved",
            "created_at": "2020-05-19T12:37:01.430444Z",
            "resolved_at": "2020-05-19T13:37:01.429805Z",
            "acknowledged_at": null,
            "title": "Memory above 90% threshold"
        }
    ]
}

These available filter parameters should be provided as GET arguments:

route_id
integration_id

HTTP request

GET {{API_URL}}/api/v1/alert_groups/

Delete alert groups

curl "{{API_URL}}/api/v1/alert_groups/I68T24C13IFW1/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "mode": "wipe"
  }'

Parameter	Required	Description
`mode`	No	Default setting is `wipe`. `wipe` will remove the payload of all Grafana OnCall group alerts. This is useful if you sent sensitive data to OnCall. All metadata will remain. `DELETE` will trigger the removal of alert groups, alerts, and all related metadata. It will also remove alert group notifications in Slack and other destinations.

NOTE: DELETE can take a few moments to delete alert groups because Grafana OnCall interacts with 3rd party APIs such as Slack. Please check objects using GET to be sure the data is removed.

HTTP request

DELETE {{API_URL}}/api/v1/alert_groups/<ALERT_GROUP_ID>

Integrations HTTP API

Tue, 18 Mar 2025 12:53:54 +0100

Create an integration

curl "{{API_URL}}/api/v1/integrations/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --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/",
    "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
        }
    }
}

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

HTTP request

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

Get integration

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

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/",
    "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
        }
    }
}

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

curl "{{API_URL}}/api/v1/integrations/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

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/",
            "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
                }
            }
        }
    ]
}

HTTP request

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

Update integration

curl "{{API_URL}}/api/v1/integrations/CFRPV98RPR1U8/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --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/",
    "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
        }
    }
}

HTTP request

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

Delete integration

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: meowmeowmeow"

HTTP request

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

OnCall shifts HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Create an OnCall shift

curl "{{API_URL}}/api/v1/on_call_shifts/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "Demo single event",
      "type": "single_event",
      "team_id": null,
      "time_zone": null,
      "level": 0,
      "start": "2020-09-10T08:00:00",
      "duration": 10800,
      "users": [
          "U4DNY931HHJS5"
      ]
  }'

The above command returns JSON structured in the following way:

{
    "id": "OH3V5FYQEYJ6M",
    "name": "Demo single event",
    "type": "single_event",
    "team_id": null,
    "time_zone": null,
    "level": 0,
    "start": "2020-09-10T08:00:00",
    "duration": 10800,
    "users": [
        "U4DNY931HHJS5"
    ]
}

Parameter	Unique	Required	Description
`name`	Yes	Yes	On-call shift name.
`type`	No	Yes	One of: `single_event`, `recurrent_event`, `rolling_users`.
`team_id`	No	ID of the team.
`time_zone`	No	Optional	On-call shift time zone. Default is local schedule time zone. This field will override the schedule time zone if changed. For more information see time zones.
`level`	No	Optional	Priority level. The higher the value, the higher the priority. If two events overlap in one schedule, Grafana OnCall will choose the event with higher level. For example: Alex is on-call from 8AM till 11AM with level 1, Bob is on-call from 9AM till 11AM with level 2. At 10AM Grafana OnCall will notify Bob. At 8AM OnCall will notify Alex.
`start`	No	Yes	Start time of the on-call shift. This parameter takes a date format as `yyyy-MM-dd'T'HH:mm:ss` (for example “2020-09-05T08:00:00”).
`duration`	No	Yes	Duration of the event.
`frequency`	No	If type = `recurrent_event` or `rolling_users`	One of: `daily`, `weekly`, `monthly`.
`interval`	No	Optional	This parameter takes a positive integer that represents the intervals that the recurrence rule repeats.
`week_start`	No	Optional	Start day of the week in iCal format. One of: `SU` (Sunday), `MO` (Monday), `TU` (Tuesday), `WE` (Wednesday), `TH` (Thursday), `FR` (Friday), `SA` (Saturday). Default: `SU`.
`by_day`	No	Optional	List of days in iCal format. Valid values are: `SU`, `MO`, `TU`, `WE`, `TH`, `FR`, `SA`.
`by_month`	No	Optional	List of months. Valid values are `1` to `12`.
`by_monthday`	No	Optional	List of days of the month. Valid values are `1` to `31` or `-31` to `-1`.
`users`	No	Optional	List of on-call users.
`rolling_users`	No	Optional	List of lists with on-call users (for `rolling_users` event type). Grafana OnCall will iterate over lists of users for every time frame specified in `frequency`. For example: there are two lists of users in `rolling_users` : [[Alex, Bob], [Alice]] and `frequency` = `daily` . This means that the first day Alex and Bob will be notified. The next day: Alice. The day after: Alex and Bob again and so on.
`start_rotation_from_user_index`	No	Optional	Index of the list of users in `rolling_users`, from which on-call rotation starts. By default, the start index is `0`

Please see RFC 5545 for more information about recurrence rules.

HTTP request

POST {{API_URL}}/api/v1/on_call_shifts/

Get OnCall shifts

curl "{{API_URL}}/api/v1/on_call_shifts/SBM7DV7BKFUYU/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \

The above command returns JSON structured in the following way:

{
    "id": "OH3V5FYQEYJ6M",
    "name": "Demo single event",
    "type": "single_event",
    "team_id": null,
    "time_zone": null,
    "level": 0,
    "start": "2020-09-10T08:00:00",
    "duration": 10800,
    "users": [
        "U4DNY931HHJS5"
    ]
}

HTTP request

GET {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/

List OnCall shifts

curl "{{API_URL}}/api/v1/on_call_shifts/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "OH3V5FYQEYJ6M",
            "name": "Demo single event",
            "type": "single_event",
            "team_id": null,
            "time_zone": null,
            "level": 0,
            "start": "2020-09-10T08:00:00",
            "duration": 10800,
            "users": [
                "U4DNY931HHJS5"
            ]
        },
        {
            "id": "O9WTH7CKM3KZW",
            "name": "Demo recurrent event",
            "type": "recurrent_event",
            "team_id": null,
            "time_zone": null,
            "level": 0,
            "start": "2020-09-10T16:00:00",
            "duration": 10800,
            "frequency": "weekly",
            "interval": 2,
            "week_start": "SU",
            "by_day": [
                "MO",
                "WE",
                "FR"
            ],
            "by_month": null,
            "by_monthday": null,
            "users": [
                "U4DNY931HHJS5"
            ]
        }
    ]
}

The following available filter parameters should be provided as GET arguments:

name (Exact match)
schedule_id (Exact match)

HTTP request

GET {{API_URL}}/api/v1/on_call_shifts/

Update OnCall shift

curl "{{API_URL}}/api/v1/on_call_shifts/S3Z477AHDXTMF/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Demo single event",
    "type": "single_event",
    "level": 0,
    "start": "2020-09-10T08:00:00",
    "duration": 10800,
    "users": [
        "U4DNY931HHJS5"
    ]
  }'

The above command returns JSON structured in the following way:

{
    "id": "OH3V5FYQEYJ6M",
    "name": "Demo single event",
    "type": "single_event",
    "team_id": null,
    "time_zone": null,
    "level": 0,
    "start": "2020-09-10T08:00:00",
    "duration": 10800,
    "users": [
        "U4DNY931HHJS5"
    ]
}

HTTP request

PUT {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/

Delete OnCall shift

curl "{{API_URL}}/api/v1/on_call_shifts/S3Z477AHDXTMF/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/on_call_shifts/<ON_CALL_SHIFT_ID>/

Outgoing webhooks HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Outgoing webhooks (actions)

Used in escalation policies with type trigger_action.

List actions

curl "{{API_URL}}/api/v1/actions/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "KGEFG74LU1D8L",
            "name": "Publish alert group notification to JIRA"
        }
    ]
}

HTTP request

GET {{API_URL}}/api/v1/actions/

Personal Notification Rules HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Post a personal notification rule

curl "{{API_URL}}/api/v1/personal_notification_rules/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "user_id": "U4DNY931HHJS5",
      "type": "notify_by_sms"
  }'

The above command returns JSON structured in the following way:

{
    "id": "NT79GA9I7E4DJ",
    "user_id": "U4DNY931HHJS5",
    "position": 0,
    "important": false,
    "type": "notify_by_sms"
}

Parameter	Required	Description
`user_id`	Yes	User ID
`position`	Optional	Personal notification rules execute one after another starting from `position=0`. `Position=-1` will put the escalation policy to the end of the list. A new escalation policy created with a position of an existing escalation policy will move the old one (and all following) down on the list.
`type`	Yes	One of: `wait`, `notify_by_slack`, `notify_by_sms`, `notify_by_phone_call`, `notify_by_telegram`, `notify_by_email`.
`duration`	Optional	A time in secs when type `wait` is chosen for `type`.
`important`	Optional	Boolean value indicates if a rule is “important”. Default is `false`.

HTTP request

POST {{API_URL}}/api/v1/personal_notification_rules/

Get personal notification rule

curl "{{API_URL}}/api/v1/personal_notification_rules/ND9EHN5LN1DUU/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "id": "ND9EHN5LN1DUU",
    "user_id": "U4DNY931HHJS5",
    "position": 1,
    "duration": 300,
    "important": false,
    "type": "wait"
}

HTTP request

GET {{API_URL}}/api/v1/personal_notification_rules/<PERSONAL_NOTIFICATION_RULE_ID>/

List personal notification rules

curl "{{API_URL}}/api/v1/personal_notification_rules/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following ways:

{
    "count": 4,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "NT79GA9I7E4DJ",
            "user_id": "U4DNY931HHJS5",
            "position": 0,
            "important": false,
            "type": "notify_by_sms"
        },
        {
            "id": "ND9EHN5LN1DUU",
            "user_id": "U4DNY931HHJS5",
            "position": 1,
            "duration": 300,
            "important": false,
            "type": "wait"
        },
        {
            "id": "NEF49YQ1HNPDD",
            "user_id": "U4DNY931HHJS5",
            "position": 2,
            "important": false,
            "type": "notify_by_phone_call"
        },
        {
            "id": "NWAL6WFJNWDD8",
            "user_id": "U4DNY931HHJS5",
            "position": 0,
            "important": true,
            "type": "notify_by_phone_call"
        }
    ]
}

The following available filter parameters should be provided as GET arguments:

user_id
important

HTTP Request

GET {{API_URL}}/api/v1/personal_notification_rules/

Delete a personal notification rule

curl "{{API_URL}}/api/v1/personal_notification_rules/NWAL6WFJNWDD8/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/personal_notification_rules/<PERSONAL_NOTIFICATION_RULE_ID>/

Routes HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Create a route

curl "{{API_URL}}/api/v1/routes/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "integration_id": "CFRPV98RPR1U8",
      "escalation_chain_id": "F5JU6KJET33FE",
      "routing_regex": "us-(east|west)",
      "position": 0,
      "slack": {
        "channel_id": "CH23212D"
      }
  }'

The above command returns JSON structured in the following way:

{
    "id": "RIYGUJXCPFHXY",
    "integration_id": "CFRPV98RPR1U8",
    "escalation_chain_id": "F5JU6KJET33FE",
    "routing_regex": "us-(east|west)",
    "position": 0,
    "is_the_last_route": false,
    "slack": {
        "channel_id": "CH23212D"
    }
}

Routes allow you to direct different alerts to different messenger channels and escalation chains. Useful for:

Important/non-important alerts
Alerts for different engineering groups
Snoozing spam & debugging alerts

Parameter	Unique	Required	Description
`integration_id`	No	Yes	Each route is assigned to a specific integration.
`escalation_chain_id`	No	Yes	Each route is assigned a specific escalation chain.
`routing_regex`	Yes	Yes	Python Regex query (use https://regex101.com/ for debugging). OnCall chooses the route for an alert in case there is a match inside the whole alert payload.
`position`	Yes	Optional	Route matching is performed one after another starting from position=`0`. Position=`-1` will put the route to the end of the list before `is_the_last_route`. A new route created with a position of an existing route will move the old route (and all following routes) down in the list.
`slack`	Yes	Optional	Dictionary with Slack-specific settings for a route.

HTTP request

POST {{API_URL}}/api/v1/routes/

Get a route

curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \

The above command returns JSON structured in the following way:

{
    "id": "RIYGUJXCPFHXY",
    "integration_id": "CFRPV98RPR1U8",
    "escalation_chain_id": "F5JU6KJET33FE",
    "routing_regex": "us-(east|west)",
    "position": 0,
    "is_the_last_route": false,
    "slack": {
        "channel_id": "CH23212D"
    }
}

HTTP request

GET {{API_URL}}/api/v1/routes/<ROUTE_ID>/

List routes

curl "{{API_URL}}/api/v1/routes/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "RIYGUJXCPFHXY",
            "integration_id": "CFRPV98RPR1U8",
            "escalation_chain_id": "F5JU6KJET33FE",
            "routing_regex": "us-(east|west)",
            "position": 0,
            "is_the_last_route": false,
            "slack": {
                "channel_id": "CH23212D"
            }
        },
        {
            "id": "RVBE4RKQSCGJ2",
            "integration_id": "CFRPV98RPR1U8",
            "escalation_chain_id": "F5JU6KJET33FE",
            "routing_regex": ".*",
            "position": 1,
            "is_the_last_route": true,
            "slack": {
                "channel_id": "CH23212D"
            }
        }
    ]
}

The following available filter parameters should be provided as GET arguments:

integration_id
routing_regex (Exact match)

HTTP request

GET {{API_URL}}/api/v1/routes/

Update route

curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "routing_regex": "us-(east|west)",
      "position": 0,
      "slack": {
        "channel_id": "CH23212D"
      }
  }'

The above command returns JSON structured in the following way:

{
    "id": "RIYGUJXCPFHXY",
    "integration_id": "CFRPV98RPR1U8",
    "escalation_chain_id": "F5JU6KJET33FE",
    "routing_regex": "us-(east|west)",
    "position": 0,
    "is_the_last_route": false,
    "slack": {
        "channel_id": "CH23212D"
    }
}

HTTP request

PUT {{API_URL}}/api/v1/routes/<ROUTE_ID>/

Delete a route

curl "{{API_URL}}/api/v1/routes/RIYGUJXCPFHXY/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/routes/<ROUTE_ID>/

Schedule HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Create a schedule

curl "{{API_URL}}/api/v1/schedules/" \
  --request POST \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "Demo schedule iCal",
      "ical_url_primary": "https://example.com/meow_calendar.ics",
      "slack": {
          "channel_id": "MEOW_SLACK_ID",
          "user_group_id": "MEOW_SLACK_ID"
      }
  }'

The above command returns JSON structured in the following way:

{
    "id": "SBM7DV7BKFUYU",
    "name": "Demo schedule iCal",
    "type": "ical",
    "team_id": null,
    "ical_url_primary": "https://example.com/meow_calendar.ics",
    "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
    "on_call_now": [
        "U4DNY931HHJS5"
    ],
    "slack": {
        "channel_id": "MEOW_SLACK_ID",
        "user_group_id": "MEOW_SLACK_ID"
    }
}

Parameter	Unique	Required	Description
`name`	Yes	Yes	Schedule name.
`type`	No	Yes	Schedule type. May be `ical` (used for iCalendar integration) or `calendar` (used for manually created on-call shifts).
`team_id`	No	No	ID of the team.
`time_zone`	No	Optional	Schedule time zone. Is used for manually added on-call shifts in Schedules with type `calendar`. Default time zone is `UTC`. For more information about time zones, see time zones.
`ical_url_primary`	No	If type = `ical`	URL of external iCal calendar for schedule with type `ical`.
`ical_url_overrides`	No	Optional	URL of external iCal calendar for schedule with any type. Events from this calendar override events from primary calendar or from on-call shifts.
`slack`	No	Optional	Dictionary with Slack-specific settings for a schedule. Includes `channel_id` and `user_group_id` fields, that take a channel ID and a user group ID from Slack.
`shifts`	No	Optional	List of shifts. Used for manually added on-call shifts in Schedules with type `calendar`.

HTTP request

POST {{API_URL}}/api/v1/schedules/

Get a schedule

curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \

The above command returns JSON structured in the following way:

{
    "id": "SBM7DV7BKFUYU",
    "name": "Demo schedule iCal",
    "type": "ical",
    "team_id": null,
    "ical_url_primary": "https://example.com/meow_calendar.ics",
    "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
    "on_call_now": [
        "U4DNY931HHJS5"
    ],
    "slack": {
        "channel_id": "MEOW_SLACK_ID",
        "user_group_id": "MEOW_SLACK_ID"
    }
}

HTTP request

GET {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/

List schedules

curl "{{API_URL}}/api/v1/schedules/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "SBM7DV7BKFUYU",
            "name": "Demo schedule iCal",
            "type": "ical",
            "team_id": null,
            "ical_url_primary": "https://example.com/meow_calendar.ics",
            "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
            "on_call_now": [
                "U4DNY931HHJS5"
            ],
            "slack": {
                "channel_id": "MEOW_SLACK_ID",
                "user_group_id": "MEOW_SLACK_ID"
          }
        },
        {
            "id": "S3Z477AHDXTMF",
            "name": "Demo schedule Calendar",
            "type": "calendar",
            "team_id": null,
            "time_zone": "America/New_York",
            "on_call_now": [
                "U4DNY931HHJS5"
            ],
            "shifts": [
              "OH3V5FYQEYJ6M",
              "O9WTH7CKM3KZW"
            ],
            "ical_url_overrides": null,
            "slack": {
                "channel_id": "MEOW_SLACK_ID",
                "user_group_id": "MEOW_SLACK_ID"
          }
        }
    ]
}

The following available filter parameter should be provided as a GET argument:

name (Exact match)

HTTP request

GET {{API_URL}}/api/v1/schedules/

Update a schedule

curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \
  --request PUT \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Demo schedule iCal",
    "ical_url": "https://example.com/meow_calendar.ics",
    "slack": {
        "channel_id": "MEOW_SLACK_ID"
    }
  }'

The above command returns JSON structured in the following way:

{
    "id": "SBM7DV7BKFUYU",
    "name": "Demo schedule iCal",
    "type": "ical",
    "team_id": null,
    "ical_url_primary": "https://example.com/meow_calendar.ics",
    "ical_url_overrides": "https://example.com/meow_calendar_overrides.ics",
    "on_call_now": [
        "U4DNY931HHJS5"
    ],
    "slack": {
        "channel_id": "MEOW_SLACK_ID",
        "user_group_id": "MEOW_SLACK_ID"
    }
}

HTTP request

PUT {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/

Delete a schedule

curl "{{API_URL}}/api/v1/schedules/SBM7DV7BKFUYU/" \
  --request DELETE \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

HTTP request

DELETE {{API_URL}}/api/v1/schedules/<SCHEDULE_ID>/

Slack Channels HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

List Slack Channels

curl "{{API_URL}}/api/v1/slack_channels/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "meow_channel",
            "slack_id": "MEOW_SLACK_ID"
        }
    ]
}

The following available filter parameter should be provided as a GET argument:

channel_name

HTTP Request

GET {{API_URL}}/api/v1/slack_channels/

OnCall User Groups HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

List user groups

curl "{{API_URL}}/api/v1/user_groups/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "GPFAPH7J7BKJB",
            "type": "slack_based",
            "slack": {
              "id": "MEOW_SLACK_ID",
              "name": "Meow Group",
              "handle": "meow_group"
            }
        }
    ]
}

Parameter	Unique	Description
`id`	Yes	User Group ID
`type`	No	Slack-defined user groups
`slack`	No	Metadata retrieved from Slack.

HTTP request

GET {{API_URL}}/api/v1/user_groups/

Grafana OnCall Users HTTP API

Wed, 19 Apr 2023 14:16:27 +0100

Get a user

This endpoint retrieves the user object.

```shell
curl "{{API_URL}}/api/v1/users/current/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "id": "U4DNY931HHJS5",
    "email": "public-api-demo-user-1@grafana.com",
    "slack": [
        {
            "user_id": "UALEXSLACKDJPK",
            "team_id": "TALEXSLACKDJPK"
        }
    ],
    "username": "alex",
    "role": "admin"
}

HTTP request

GET {{API_URL}}/api/v1/users/<USER_ID>/

Use {{API_URL}}/api/v1/users/current to retrieve the current user.

Parameter	Unique	Description
`id`	Yes/org	User ID
`email`	Yes/org	User e-mail
`slack`	Yes/org	List of user IDs from connected Slack. User linking key is e-mail.
`username`	Yes/org	User username
`role`	No	One of: `user`, `observer`, `admin`.

List Users

curl "{{API_URL}}/api/v1/users/" \
  --request GET \
  --header "Authorization: meowmeowmeow" \
  --header "Content-Type: application/json"

The above command returns JSON structured in the following way:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": "U4DNY931HHJS5",
            "email": "public-api-demo-user-1@grafana.com",
            "slack": [
                {
                    "user_id": "UALEXSLACKDJPK",
                    "team_id": "TALEXSLACKDJPK"
                }
            ],
            "username": "alex",
            "role": "admin"
        }
    ]
}

This endpoint retrieves all users.

The following available filter parameter should be provided as a GET argument:

username (Exact match)

HTTP request

GET {{API_URL}}/api/v1/users/