--- title: "Integrations HTTP API | Grafana Cloud documentation" description: "Integrations HTTP API Create an integration Required permission: grafana-irm-app.integrations:write shell Copy 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:" --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Integrations HTTP API ## Create an integration **Required permission**: `grafana-irm-app.integrations:write` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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](/404/). **HTTP request** `POST {{API_URL}}/api/v1/integrations/` Expand table | 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](#labels) for format. | | `dynamic_labels` | No | A list of dynamic labels with templated values. Each label must have a unique `key`. See [Dynamic labels](#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` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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//` ## List integrations **Required permission**: `grafana-irm-app.integrations:read` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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](/docs/grafana-cloud/alerting-and-irm/irm/reference/oncall-api/#pagination). 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` shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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//` Expand table | 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](#labels) for format. | | `dynamic_labels` | No | A list of dynamic labels with templated values. Each label must have a unique `key`. See [Dynamic labels](#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. shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell 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//` ## 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. JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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. JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json { "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