Cases API

Open in ChatGPTOpen in ClaudeAPI reference

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, make sure you have the following:

• To use this API you need to create a personal or team API key. Cases do not ship with a permission preset; add the individual CASES:* permissions you need.

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

  A CASES:* permission governs the operation. It does not, on its own, grant access to every Case: see Access also depends on the source alert.

• Select the api.:443 endpoint that corresponds to your Coralogix domain using the domain selector at the top of the page.

• Administrator permissions to manage your services.

Access also depends on the source alert

A CASES:* permission lets you call the endpoint. Whether a particular Case comes back also depends on what raised it.

Most Cases are opened by an alert, and Coralogix applies that alert's own read permission to the Case. Holding CASES:READ is not enough on its own:

The Case was raised by	You also need
A log alert	ALERTS:LOGSREADCONFIG
A metric alert	ALERTS:METRICSREADCONFIG
A trace alert	ALERTS:SPANSREADCONFIG
A Flow alert	ALERTS:READCONFIG
An SLO alert	ALERTS:SLOMGMTREADCONFIG

When a Case was raised by more than one alert, you need read permission for every one of them. A Case opened by both a log alert and a metric alert needs ALERTS:LOGSREADCONFIG and ALERTS:METRICSREADCONFIG, not either one.

A Case you cannot read is left out of the response rather than returned as a permission error, so a shorter list can mean missing alert read permission rather than fewer Cases.

A Case from a source that is not an alert, such as Prometheus Alert Manager, carries no such requirement, and CASES:READ is sufficient.

The practical effect is that two keys holding the same CASES:* permissions can see different Cases, because they hold different alert read permissions. A key without ALERTS:METRICSREADCONFIG can list and read Cases all day and never see one raised by a metric alert.

Each Case reports what raised it in case.indicators.alerts[].alertType, so a Case you can read tells you which alert permission it needed. A Case you cannot read does not, which is worth knowing when a call that looks correct returns nothing.

The same rule governs the Cases UI, where it is covered in Working with Cases. For every Coralogix permission and the roles that include it, see Permissions list.

Authentication

Coralogix API uses API keys to authenticate requests. You can view and manage your API keys 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.: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

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:

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

Sample request

Retrieve a single Case by ID using GetCase.

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

Sample response

{
    "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
• Case Events service
• Cases Notification service

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
Cases user guide	Working with Cases
Case permissions	Permissions list