## Overview

This document outlines the Cases API. It exposes three services that together cover the full Case lifecycle:

- **`CasesService`** manages Cases throughout their lifecycle. Use it to get, list, update, assign, acknowledge, resolve, and close Cases, to set or clear a priority override, and to bulk-apply each of these operations. It also exposes filter values, grouping keys, and Case deep links.
- **`CaseEventsService`** manages the events on a Case's Activity timeline. Use it to list events, retrieve a single event, and create, update, or delete comment events. External systems can also sync threads into the timeline through this service.
- **`CasesNotificationService`** tracks notification-adjacent data. Use it to list the notification delivery records for one or more Cases, including routing, target, and outcome information.

### Prerequisites

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

- To use this API you need to [create](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/index.md) a personal or team API key. Cases do not ship with a permission preset; add the individual `CASE:*` permissions you need.

  | Permission         | Description                                  | Used by                                                                                                               |
  | ------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
  | `CASE:READ`        | View the list of Cases and individual Cases. | Every read method across all three services.                                                                          |
  | `CASE:UPDATE`      | Update Case fields and priority overrides.   | `UpdateCase`, `SetPriorityOverride`, `ClearPriorityOverride`, `BulkSetPriorityOverride`, `BulkClearPriorityOverride`. |
  | `CASE:ASSIGN`      | Assign a Case to yourself or to other users. | `AssignCase`, `UnassignCase`, `BulkAssign`, `BulkUnassign`.                                                           |
  | `CASE:ACKNOWLEDGE` | Acknowledge a Case.                          | `AcknowledgeCase`, `UnacknowledgeCase`, `BulkAcknowledge`.                                                            |
  | `CASE:CLOSE`       | Resolve or close a Case.                     | `ResolveCase`, `CloseCase`, `BulkResolve`, `BulkClose`.                                                               |
  | `CASE:COMMENT`     | Comment on a Case.                           | `CreateComment`, `UpdateComment`, `DeleteComment`, `SyncExternalCaseEvents`.                                          |

- Select the api.\[[DOMAIN_VALUE]\]:443 endpoint that corresponds to your Coralogix [domain](https://coralogix.com/docs/user-guides/account-management/account-settings/coralogix-domain/index.md) using the domain selector at the top of the page.

- Administrator permissions to manage your services.

## Authentication

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

### Example

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

Then, structure your header by using the api.\[[DOMAIN_VALUE]\]:443 endpoint for your Coralogix domain. To dynamically display the correct endpoint, use the domain selector at the top of the page.

`d @ api.[[DOMAIN_VALUE]]:443`

The Cases API exposes three fully qualified service names:

- `com.coralogixapis.cases.v1.CasesService`
- `com.coralogixapis.cases.v1.CaseEventsService`
- `com.coralogixapis.cases.v1.CasesNotificationService`

The complete request header should look like this:

```bash
grpcurl -H "Authorization: Bearer <cx_api_key>" -d @ api.[[DOMAIN_VALUE]]:443 com.coralogixapis.cases.v1.CasesService/
```

### Sample request

Retrieve a single Case by ID using `GetCase`.

```json
grpcurl -H "Authorization: Bearer <cx_api_key>" -d @ api.[[DOMAIN_VALUE]]:443 com.coralogixapis.cases.v1.CasesService/GetCase <<EOF
{
    "id": "case-697506"
}
EOF
```

### Sample response

```json
{
    "case": {
        "id": "case-697506",
        "name": "Spike in errors for specific country",
        "status": "CASE_STATUS_ACTIVE",
        "priority": "CASE_PRIORITY_P1",
        "category": "CASE_CATEGORY_AVAILABILITY",
        "assignee": null,
        "created_at": {
            "seconds": "1748208900",
            "nanos": 0
        },
        "last_updated_at": {
            "seconds": "1748210220",
            "nanos": 0
        }
    }
}
```

## API endpoints

⚠️ This is only a list of endpoints. For a detailed schema, consult the individual service references:

- [Cases service](https://docs.coralogix.com/api-reference/v5/cases-service/overview)
- [Case Events service](https://docs.coralogix.com/api-reference/v5/case-events-service/overview)
- [Cases Notification service](https://docs.coralogix.com/api-reference/v5/cases-notification-service/overview)

### CasesService

`CasesService` is the primary service for managing Cases. It covers lifecycle operations (assign, acknowledge, resolve, close), priority overrides, bulk operations, and metadata lookups.

| Method Name                 | Description                                                |
| --------------------------- | ---------------------------------------------------------- |
| `GetCase`                   | Retrieve detailed information about a single Case by ID.   |
| `ListCases`                 | List Cases using filters, pagination, and custom ordering. |
| `UpdateCase`                | Apply a partial update (patch) to a Case.                  |
| `SetPriorityOverride`       | Override a Case's computed priority with a specific value. |
| `ClearPriorityOverride`     | Remove a previously set priority override.                 |
| `AssignCase`                | Assign a Case to a user.                                   |
| `UnassignCase`              | Remove a Case's assignment.                                |
| `AcknowledgeCase`           | Acknowledge a Case.                                        |
| `UnacknowledgeCase`         | Move an acknowledged Case back to Active.                  |
| `ResolveCase`               | Resolve a Case.                                            |
| `CloseCase`                 | Close a Case.                                              |
| `BulkAssign`                | Assign multiple Cases to a user.                           |
| `BulkUnassign`              | Remove assignment from multiple Cases.                     |
| `BulkAcknowledge`           | Acknowledge multiple Cases.                                |
| `BulkResolve`               | Resolve multiple Cases.                                    |
| `BulkClose`                 | Close multiple Cases.                                      |
| `BulkSetPriorityOverride`   | Override priority for multiple Cases.                      |
| `BulkClearPriorityOverride` | Remove priority override from multiple Cases.              |
| `GetFilterValues`           | Get the available filter values for the Case list.         |
| `GetGroupingKeys`           | Get the available grouping keys for the Case list.         |
| `GetCaseDeepLinks`          | Get deep links for a Case.                                 |

### CaseEventsService

`CaseEventsService` provides access to the events that appear on a Case's Activity timeline, including system-generated events and user comments. It also lets external systems sync threads back into Coralogix.

| Method Name              | Description                                                   |
| ------------------------ | ------------------------------------------------------------- |
| `ListEvents`             | List events for a Case.                                       |
| `GetEvent`               | Retrieve a single event by ID.                                |
| `CreateComment`          | Create a new comment event on a Case.                         |
| `UpdateComment`          | Modify the content of an existing comment event.              |
| `DeleteComment`          | Delete a comment event.                                       |
| `SyncExternalCaseEvents` | Sync events from an external system into the Case's timeline. |

### CasesNotificationService

`CasesNotificationService` tracks notification-adjacent data for Cases. Use it to retrieve the notifications routed for one or more Cases and the delivery outcome on each connector.

| Method Name                  | Description                                                                                                       |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `ListNotificationDeliveries` | Retrieve notification delivery records for one or more Cases, including routing, target, and outcome information. |

## Additional resources

|                     |                                                                                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Coralogix Endpoints | [Coralogix Endpoints](https://coralogix.com/docs/integrations/coralogix-endpoints/index.md)                         |
| Cases user guide    | [Working with Cases](https://coralogix.com/docs/user-guides/cases/working-with-cases/index.md)                      |
| Case permissions    | [Permissions list](https://coralogix.com/docs/user-guides/aaa/access-control/permissions/permissions-list/index.md) |

## Support

**Need help?**

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us **via our in-app chat** or by sending us an email to [support@coralogix.com](mailto:support@coralogix.com).