# Incident management API

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Fdata-management%2Fincident-management-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fdeveloper-portal%2Fapis%2Fdata-management%2Fincident-management-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[API reference](https://coralogix.com/docs/docs/api-reference/v5/incidents-service)

Cases is replacing Incidents

[Cases](https://coralogix.com/docs/docs/user-guides/cases/overview/.md) is an upgrade to Incidents, and Incidents will be gradually replaced. New accounts work with Cases by default. To understand how the two differ, see [Cases vs Incidents](https://coralogix.com/docs/docs/user-guides/cases/cases-incidents/.md). For programmatic access, use the [Cases API](https://coralogix.com/docs/docs/developer-portal/apis/data-management/cases-api/.md).

## Overview[​](#overview "Direct link to Overview")

This document outlines the Incident Management API. It includes various methods for managing incidents, such as retrieving incident details, listing incidents, aggregating incidents, assigning and unassigning incidents and acknowledging or resolving incidents. The `IncidentsService` is designed to handle all operations related to incident management within Coralogix.

### Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before you begin, please make sure you have the following:

* To use this API you need to [create](https://coralogix.com/docs/docs/user-guides/account-management/api-keys/api-keys/.md) a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

  | Preset    | Action                                                                                                               | Description                                                                                                                                                                              |
  | --------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | Incidents | `INCIDENTS:ACKNOWLEDGE`<br />`INCIDENTS:ASSIGN`<br />`INCIDENTS:CLOSE`<br />`INCIDENTS:READ`<br />`INCIDENTS:SNOOZE` | Acknowledge Events in Triggered Alerts<br />Assign an Event in Triggered Alerts<br />Manually Resolve Events in Triggered Alerts<br />View Events in Triggered Alerts<br />Snooze Events |

* Choose the <!-- -->api.:443<!-- --> endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/docs/user-guides/account-management/account-settings/coralogix-domain/.md) using the domain selector at the top of the page.

* Administrator permissions to manage your services.

## Authentication[​](#authentication "Direct link to Authentication")

Coralogix API uses API keys to authenticate requests. You can view and manage your [API keys](https://coralogix.com/docs/docs/user-guides/account-management/api-keys/api-keys/.md) from the Data Flow tab in Coralogix. You need to use an API key in the Authorization request header to successfully connect.

### Example[​](#example "Direct link to Example")

`grpcurl -H "Authorization: Bearer <cx_api_key>"`

Then, structure your header by using the <!-- -->api.:443<!-- --> endpoint for your Coralogix domain. To dynamically display the correct endpoint, use the domain selector at the top of the page.

`d @ api.eu2.coralogix.com:443`

For the Incidents Service API, the service name will be `IncidentsService`.

`com.coralogixapis.incidents.v1.IncidentsService/`

The complete request header should look like this:

```
grpcurl -H "Authorization: Bearer <cx_api_key>" -d @ api.eu2.coralogix.com:443 com.coralogixapis.incidents.v1.IncidentsService/
```

### Sample request[​](#sample-request "Direct link to Sample request")

Lists all available incidents based on specified filters and order. In this case, incidents are shown per `assignee`. The list is ordered in an unspecified direction and sorted by time created.

```
grpcurl -H "Authorization: Bearer <cx_api_key>" -d @ api.eu2.coralogix.com:443 com.coralogixapis.incidents.v1.IncidentsService/ListIncidents <<EOF 

{

    "filter": {

        "assignee": [

            "assignee@coralogix.com"

            ]

        },

    "order_bys": [

        {

            "direction": "ORDER_BY_DIRECTION_UNSPECIFIED",

            "incident_field": "INCIDENTS_FIELDS_CREATED_TIME"

        }

    ]

}

EOF
```

### Sample response[​](#sample-response "Direct link to Sample response")

```
{

    "incidents": [

        {

            "assignments": [

                {

                    "assigned_to": {

                        "user_id": {

                            "value": "assignee@coralogix.com"

                        }

                    },

                    "assigned_by": {

                        "user_id": {

                            "value": "assignee@coralogix.com"

                        }

                    }

                }

            ],

            "events": [],

            "contextualLabels": [

                {

                    "key": "alert_id",

                    "value": "e2e1e00f-552f-4dfc-9d24-ab9d21d4979c"

                },

                {

                    "key": "alert_name",

                    "value": "inalert"

                },

                {

                    "key": "alert_type",

                    "value": "Standard"

                },

                {

                    "key": "alert_severity",

                    "value": "Info"

                },

                {

                    "key": "alert_group_by_fields",

                    "value": "coralogix.metadata.applicationName , coralogix.metadata.subsystemName"

                },

                {

                    "key": "alert_notification_group_id",

                    "value": "ab8dee0e-063b-43c2-89a3-bdbb068ff851"

                },

                {

                    "key": "alert_notification_group_grouping_fields",

                    "value": "coralogix.metadata.applicationName , coralogix.metadata.subsystemName"

                },

                {

                    "key": "alert_notification_group_integrations_ids",

                    "value": ""

                }

            ],

            "displayLabels": [

                {

                    "key": "coralogix.metadata.subsystemName",

                    "value": "coralogix-operator"

                },

                {

                    "key": "coralogix.metadata.applicationName",

                    "value": "staging"

                }

            ],

            "id": {

                "value": "cdfaf78b-27ee-401f-8d13-ebd2daa08232"

            },

            "name": null,

            "state": "INCIDENT_STATE_TRIGGERED",

            "status": "INCIDENT_STATUS_TRIGGERED",

            "description": null,

            "severity": "INCIDENT_SEVERITY_INFO",

            "created_at": {

                "seconds": "1703677320",

                "nanos": 0

            },

            "closed_at": null,

            "last_state_update_time": {

                "seconds": "1706088981",

                "nanos": 286000000

            },

            "last_state_update_key": {

                "value": "8cde7807-dedc-418b-b542-62d78fead629"

            },

            "is_muted": {

                "value": false

            }

        }

    ]

}
```

## API endpoints[​](#api-endpoints "Direct link to API endpoints")

⚠️ This is only a list of endpoints. For a detailed schema, please consult the whole [Incidents API reference](https://coralogix.com/docs/docs/api-reference/v5/incidents-service/overview).

### IncidentsService[​](#incidentsservice "Direct link to IncidentsService")

The IncidentsService is designed to provide a set of functionalities and operations to facilitate the effective management, monitoring, and resolution of incidents. Here are some key methods within the IncidentsService:

| Method Name              | Description                                                                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| ListIncidents            | Lists incidents based on filters. This method is used to retrieve a collection of incidents that match certain criteria.                            |
| ListIncidentAggregations | Lists incident aggregations. This method is used to retrieve aggregated information about incidents, grouped by specific parameters.                |
| GetIncident              | Retrieves detailed information about a specific incident. This method is used to get comprehensive details regarding a single incident.             |
| GetIncidentEvents        | Retrieves events associated with a particular incident. This method is used to obtain a chronological sequence of events related to an incident.    |
| BatchGetIncident         | Retrieves details for multiple incidents. This method is designed to efficiently retrieve information for a batch of incidents in a single request. |
| AssignIncidents          | Assigns incidents to specific users or teams. This method is used for managing the assignment of incidents to responsible parties.                  |
| UnassignIncidents        | Unassigns incidents from users or teams. This method is used to remove assignment associations for incidents.                                       |
| AcknowledgeIncidents     | Acknowledges incidents.                                                                                                                             |
| PaginationRequest        | Retrieves pagination information for incidents.                                                                                                     |
| CloseIncidents           | Closes incidents.                                                                                                                                   |
| ResolveIncidents         | Resolves incidents.                                                                                                                                 |

## Additional resources[​](#additional-resources "Direct link to Additional resources")

|                     |                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------- |
| Coralogix Endpoints | [Coralogix Endpoints](https://coralogix.com/docs/docs/integrations/coralogix-endpoints/.md) |