Incydr API: Migrate from alerts to sessions

Updated

Overview

This article provides guidance on migrating from the /v1/alerts/ API endpoint to the /v1/sessions/ endpoint. Depending on your specific API implementation, migrating may involve updating API endpoints, field mappings, and/or data processing logic. 

The newer sessions API uses an improved alerting framework, which consolidates related events into a single alert. This provides improved data organization, natural-language summaries, and enhanced compatibility with SIEM and SOAR tools. It also matches how alerts are displayed in the Incydr console.

Deprecation and end-of-life notice
The /v1/alerts/ endpoint was deprecated on April 3, 2024, and will stop working on February 28, 2026. To avoid potential service interruptions, you must update scripts and integrations that use the /v1/alerts/ endpoint to use the /v1/sessions/ endpoint instead.

What are sessions?

Sessions use the newer alerts framework to group related activity into a single alert. This matches how alerts are displayed on the Review Alerts page in the Incydr console. 

Grouping events reduces the number of alerts to be triaged, and makes it easier to identify the activity that poses the greatest risk to your organization.

Sessions may include file events, alerts, Instructor lessons, and more. A single session can contain one or more alerts.

Key differences between alerts and sessions endpoints

While the /v1/alerts/ API returned most metadata directly in the response, the /v1/sessions/ API may require additional lookups to return all the same data. For complete schema details, see the Incydr Developer Portal.

Several of the main changes are detailed in the sections below.

File events

Deprecated alert method: /v1/alerts/query-details

  • Returned an object with an observations key containing file event details.
  • Required processing of json-string data fields.

New sessions method: /v1/sessions/{id}/events

  • Provides complete file event details in a structured format.
  • Eliminates the need to process json-string data fields.
  • Includes a totalCount field in the response for the number of file events.

Alert names

Deprecated alert method: The name field contained the name of the triggered alert rule.

New sessions method:

  • Multiple alert rules may be triggered within a single session.
  • To retrieve rule names:
    1. Iterate over the triggeredAlerts array to get ruleId values.
    2. Call /v2/alert-rules to retrieve rule names and descriptions.

Recommended display format:
Combine the total number of file events with the exfiltrationSummary field, which provides a natural-language description of the session's activity. For example: {totalCount} {exfiltrationSummary}

To calculate the total count of file events:

  • Call /v1/sessions/{id}/events and check the totalCount field, or
  • Sum the following fields from the session response: noRiskEvents, lowEvents, moderateEvents, highEvents, and criticalEvents.

Actor names

Deprecated alert method: The actor field contained the email address of the user associated with the file events.

New sessions method: Only the actorId is provided. To obtain the actor's name or email address:

  1. Call /v1/actors/actor/id/{actorId}.
  2. Retrieve the name field from the response.

Alert severity

Deprecated alert methods: 

  • severity: Assigned to the alert rule at creation (legacy, no longer relevant).
  • riskSeverity: Derived from PRISM scores (LOW, MODERATE, HIGH, CRITICAL).

New sessions methods: 

  • Session details contain an array of scores, each with a PRISM score and a severity value.
  • Severity values are integers:
    • 0: No risk
    • 1: Low
    • 2: Moderate
    • 3: High
    • 4: Critical

To determine the overall severity for a session, use the maximum severity value from all file events in the session. For example, a session with severities of 3, 2, 0, and 4 has an overall severity of Critical (4).

Alert status

Deprecated alert methods: /v1/alerts/update-all-state and /v1/alerts/update-state

New sessions methods: 

  • Single session: /v1/sessions/{id}/change-state
  • Multiple sessions: /v1/sessions/change-state

Available states:

  • OPEN: New or reopened Session.
  • IN_PROGRESS: Session under investigation.
  • CLOSED: General closure (not recommended).
  • CLOSED_TP: Closed as a true positive.
  • CLOSED_FP: Closed as a false positive.
  • OPEN_NEW_DATA: Automatically set when new data is added to an existing session.

Best practices for querying sessions within a given timeframe

Querying for all activity within a given timeframe requires a slightly different approach with the transition from alerts to sessions. Unlike alerts, which are point-in-time events, sessions are more dynamic and often contain a group of related events over a period of time. Sessions may also be updated or created after the events contained in the session occurred. 

If you need to query activity within a precise time window, or you use sequential queries to request all events (for example, a query every day to capture the past 24 hours of activity), set the start time earlier than the end time of your last query to account for sessions created after their events occurred. After retrieving sessions, filter them by the first observed or last modified dates to ensure you are capturing the updates you want, without ingesting duplicates. 

Alternatively, consider using the Event Data Export functionality in the Incydr console to automatically stream alert data to external tools.

Related topics

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.