Grafana OnCallGrafana OnCall API referenceRoutes HTTP API

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 like this:

{
    "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 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
ParameterUniqueRequiredDescription
integration_idNoYesEach route is assigned to a specific integration.
escalation_chain_idNoYesEach route is assigned a specific escalation chain.
routing_regexYesYesPython 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.
positionYesOptionalRoute 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.
slackYesOptionalDictionary 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 like this:

{
    "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 like this:

{
    "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 like this:

{
    "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>/