Integrations HTTP API

Create an integration

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

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

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