Cases

A case is a container for investigating and responding to signals, carrying status, severity, assignment, and a body of typed blocks. A case's id is prefixed CAS_.

A case belongs to a Space and is the record of one investigation. It tracks workflow state (status, phase, severity, type, and assignment), a set of extracted entities, and time-to-respond metrics. Its body is an ordered list of blocks, each a typed unit such as a note, a captured query, an analysis, or a response action. A case is often opened from a signal, in which case the signal lands as a log block and the case name is drawn from the signal's message. Creating a case fires the CaseCreated webhook event.

Blocks

The body of a case is an ordered array of blocks. Each block has a shared header and a type-specific payload. getById returns them under blocks, discriminated by resourceKind.

Every block carries these header fields.

Field	Type	Description
id	string	Block ID.
resourceKind	enum	The block type. One of the six values below.
createdAt	timestamp	When the block was added.
createdByUserId	string	The user who added the block. Null when added by a non-user actor.
comments	array<object>	Threaded comments on the block, each with id, text, createdAt, and createdByUserId. Empty when there are none.

The six block types.

resourceKind	Description
CaseNoteBlock	A free-text note. Carries text.
CaseLogBlock	A captured row set, such as the signal that opened the case. Carries columns and rows.
CaseQueryBlock	A saved Hamelin query relevant to the investigation. Carries query.
CaseRelatedBlock	A link to another resource. Carries relatedResourceId.
CaseAnalysisBlock	An automated analysis run. Carries status, resultSummary, resultDetails, interestLevel, and its own extracted entities. See below.
CaseResponseActionBlock	A remediation task. Carries name, description, status, assignedToUserId, and completionNotes. See below.

A CaseAnalysisBlock runs through these states in status.

Value	Description
PENDING	Queued, not yet started.
IN_PROGRESS	Running.
COMPLETED	Finished. resultSummary, resultDetails, and interestLevel are populated.
FAILED	Errored. errorMessage explains the failure.

Its interestLevel grades the finding as NOT_INTERESTING, INTERESTING, or MALICIOUS. Null until the analysis completes.

A CaseResponseActionBlock runs through these states in status.

Value	Description
PENDING	Not yet acted on.
COMPLETED	Done. completionNotes records the outcome.
DISMISSED	Closed without action.

Entities

An entity is an observable extracted from a case or an analysis block. Each has a type, a raw value, and a normalizedValue. The type is one of seven values.

Value	Description
ip_address	An IP address.
hostname	A host name.
email	An email address.
domain	A domain name.
username	A user name.
file_hash	A file hash.
url	A URL.

Timeline

The timeline is the case's audit log, returned by getById under auditLogs. Each entry records one change.

Field	Type	Description
id	integer	Audit-log entry ID.
version	integer	The case version this entry produced.
timestamp	timestamp	When the change occurred.
userId	string	The user who made the change. Null when the actor was not a user.
chatId	string	The chat that made the change, prefixed CHT_. Null when not a chat.
changes	object	The fields that changed, as a partial case.

Severities

Severity is org-configurable. Each severity has an id and a name, managed at the organization level. The default set, ordered most to least severe, is Critical, High, Medium, Low, Informational. A case's severityId references one of these.

Phases

Phase is org-configurable. Each phase has an id and a name, managed at the organization level. The default set, in workflow order, is Identification, Containment, Eradication, Recovery. A case's phaseId references one of these.

Types

Type is org-configurable. Each type has an id, a name, and an icon, managed at the organization level. The default set is Phishing, Malware, Unauthorized Access, Data Breach, Policy Violation, Other. A case's typeId references one of these.

Inputs

Severity, phase, and type reference per-organization workflow settings rather than fixed enums. Each is an integer id pointing at a configured severity, phase, or type. See those sections for the defaults.

Field	Type	Required	Description
name	string	Required	Case title.
status	enum	Required	Workflow state: Open, On-Hold, or Closed.
severityId	integer	Optional	References a configured severity. Null when unset.
phaseId	integer	Required	References a configured phase.
typeId	integer	Optional	References a configured type. Null when unset.
assignedToUserId	string	Optional	The user the case is assigned to. Null when unassigned.
summary	string	Optional	Free-text case summary.
closureCode	enum	Optional	Disposition set when the case is closed. One of True Positive - Suspicious Activity, Benign Positive - Suspicious But Expected, False Positive - Incorrect Detection Logic, False Positive - Inaccurate Data, Other, Testing. Null while open.
suggestedClosureCodeDismissed	boolean	Optional	Whether the suggested closure code was dismissed.
spaceId	string	Required	The Space the case belongs to.

Outputs

Field	Type	Description
entities	array<object>	Extracted entities associated with the case.
suggestedClosureCode	enum	A closure code proposed by analysis, from the same value set as closureCode. Null when none is suggested.
createdByDetectionId	string	The detection whose signal opened the case, prefixed DET_. Null when the case was opened by hand.
timeToDetectMs	integer	Milliseconds from the triggering signal's timestamp to case creation. Null when not measured.
timeToInvestigateMs	integer	Milliseconds spent in investigation. Null when not measured.
timeToContainMs	integer	Milliseconds to containment. Null when not measured.
timeToEradicateMs	integer	Milliseconds to eradication. Null when not measured.
timeToResolveMs	integer	Milliseconds to resolution. Null when not measured.
initialAnalysisCompletedAt	timestamp	When the initial automated analysis finished. Null before it completes.
closedAt	timestamp	When the case was closed. Null while open.
closedByUserId	string	The user who closed the case. Null when closed by a non-user actor or still open.
closedByChatId	string	The chat that closed the case, prefixed CHT_. Null when not closed by a chat.
analysisSkippedReason	enum	Why automated analysis was skipped. Only value is QuotaExceeded. Null when analysis ran.
analysisPending	boolean	Whether automated analysis is queued or running for the case. Present on the list endpoint only.

Plus the common resource fields.

Related

• Signals vs alerts, what a case investigates.
• Signal schema reference, the fields of the signal that opens a case.
• Detections, the content that produces signals and can open cases.
• Webhooks, whose CaseCreated and CaseClosed events fire outbound requests when a case changes.