Incydr API release notes

Overview

This article lists release notes for Incydr APIs.

The deprecations listed below remain in a functional, yet deprecated state for one year from the announcement date. If you have API scripts that use the deprecated items, update the scripts before the deprecation period ends. After one year has passed, there is no guarantee that deprecated APIs will remain functional. If you need help, please contact our Technical Support Engineers.

Incydr Developer Portal
See the Developer Portal for more API documentation and resources. The portal provides:

• A single access point for documentation of methods for Incydr, including the REST API, Incydr SDK, and command-line interface (CLI)
• A single request URL for API calls to each cloud instance
• API reference documentation 

Use the Developer Portal for your API needs as much as possible. APIs in the portal are the preferred way to integrate with Incydr. If you use APIs that do not appear on the Developer Portal, contact our Technical Support Engineers for guidance on the best way to integrate with Incydr.

November 2024

Deprecations

November 27, 2024

• The v2/actor-risk-profiles APIs are deprecated and being replaced by v1/actors APIs.

April 2024

Enhancements and updates

New sessions API supports grouped events in a single alert

April 3, 2024

The v1/alerts APIs are being replaced by v1/sessions APIs. The v1/sessions APIs use the newer alerts framework to group related activity into a single alert. This matches how alerts are displayed in the Code42 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.

• In the Code42 developer portal API Reference, the Alerts category was renamed Alerts and Sessions.
• The v1/alerts APIs use the legacy alert framework, which does not group related events into a single alert. 
• The new v1/sessions APIs use the newer alerting framework, which consolidates related events into a single alert. Sessions may include file events, alerts, Instructor lessons, and more. A single session can contain one or more alerts.
• While the v1/alerts APIs returned most metadata directly in the response, the v1/sessions APIs may require additional lookups to return all the same data. 
  • For example, the v1/alerts/query-alerts response contained both actor and actorId. The new v1/sessions equivalent only includes the actorId in the response, which can then be used to look up the actor value.

Deprecations

April 3, 2024

• The v1/alerts APIs are deprecated and being replaced by v1/sessions APIs.

March 2024

Enhancements and updates

March 13, 2024

• Added a new version (v2) of the Watchlists and Risk Profiles APIs and deprecated the previous version (v1). The new versions use actor_id in place of the previous user_id. For complete documentation of the new v2 APIs, see the Code42 Developer Portal:  
  • /v2/actor-risk-profiles
  • /v2/watchlists

Deprecations

March 13, 2024

• The previous version (v1) of the following Watchlists and Risk Profiles APIs are deprecated and replaced by a new version (v2).  
  • /v1/user-risk-profiles
  • /v1/watchlists

September 2023

Enhancements and updates

September 29, 2023

• Added new Actor APIs in the Code42 Developer Portal. In the path examples below, replace <actorId> with the actor’s ID, replace <name> with the actor’s username, and replace <childActorId> with the actor ID for a child in an actor’s family:
  • Get actor by actorId: GET /v1/actors/actor/id/<actorId>
  • Get family from any member's actorId: GET /v1/actors/actor/id/<actorId>/family
  • Get actor by actorId, preferring their parent: GET /v1/actors/actor/id/<actorId>/parent
  • Get family from any member's name: GET /v1/actors/actor/name/<name>/family
  • Get actor by name, preferring their parent: GET /v1/actors/actor/name/<name>/parent
  • Make one actor adopt another: POST /v1/actors/adoption

Deprecations

September 29, 2023

• Deprecated APIs for managing cloud aliases in user profiles.

Deprecated APIs	New APIs
/v1/user-risk-profiles/{user_id}/add-cloud-aliases	NA
/v1/user-risk-profiles/{user_id}/delete-cloud-aliases	NA

June 2023

Enhancements and updates

June 07, 2023

• The FileCategoryByBytes and FileCategoryByExtension fields on the v2/file-events and v1/file-events API were consolidated into a single FileCategory field. FileCategoryByBytes and FileCategoryByExtension are no longer being populated with data. If you use either of these fields in your scripts or integrations, use FileCategory instead.

April 2023

Deprecations

April 19, 2023

• Deprecated Computer and Devices APIs, and replaced them with new Agents APIs. Following are the deprecated Computer and Devices APIs, with the corresponding new APIs to use in scripting. 

Deprecated APIs	Replaced by APIs in the Code42 Developer Portal
GET /v1/Devices/<GUID> or <id>	GET /v1/agents/{agentId}  (Get a single agent)
GET /v1/Devices	GET /v1/agents (Get a list of agents)
PUT /v1/Computer	PUT /v1/agents/{agentId} {             "name": "new name",             "externalReference": "ext_id:4242" } (Update an agent)
DELETE /v1/ComputerDeactivation	POST /v1/agents/activate { "agentIds" : ["123456789123456789", "987654321987654321", "123456789987654321", ...] } (Activate a set of agents)
PUT /v1/ComputerDeactivation	POST /v1/agents/deactivate { "agentIds" : ["123456789123456789", "987654321987654321", "123456789987654321", ...] } (Deactivate a set of agents)

October 2022

Enhancements and updates

October 26, 2022

• Added the following Legal Hold APIs to the Code42 Developer Portal. In the path examples, replace <matterId> with the legal hold matter's ID:   
  • Create a policy:  POST /v1/legal-hold/policies  
  • Remove a user from a matter:  POST /v1/legal-hold/matters/<matterId>/custodians/remove  

October 6, 2022

• Added support for API clients in the Code42 command-line interface (CLI). To use an API client with the CLI, create an API client and use its client ID and secret for authentication.   
• Added an Integration Guides section to the Code42 Developer Portal containing guides to integrate with Microsoft Sentinel using py42 or the Code42 command-line interface (CLI). For information on other integrations, see Code42 integrations resources.  
• Added a new version (v2) of Rules APIs and deprecated the previous version (v1). For complete documentation of the following v2 Rules APIs, see the Code42 Developer Portal:   
  • GET /v2/alert-rules/<ID>
  • GET /v2/alert-rules
  • POST /v2/alert-rules/<ID>/enable
  • POST /v2/alert-rules/enable
  • POST /v2/alert-rules/<ID>/disable
  • POST /v2/alert-rules/disable
  • DELETE /v2/alert-rules/<ID>/users
  • GET /v2/alert-rules/<ID>/users

Deprecations

v1 Rules APIs

October 6, 2022

• The previous version (v1) of the following Rules APIs in the Code42 Developer Portal are deprecated and replaced by a new version (v2).   

Deprecated APIs	New APIs
POST /v1/alert-rules/update-is-enabled  (v1 - Enable or disable a list of rules)	POST /v2/alert-rules/enable  (v2 - Enables a set of rules) POST /v2/alert-rules/disable  (v2 - Disables a set of rules) POST /v2/alert-rules/<ID>/enable  (2 - Enables an individual rule by id) POST /v2/alert-rules/<ID>/disable  (v2 - Disables an individual rule by id)
POST /v1/alert-rules/add-users (v1 - Add users to a rule's watch list)	NA
POST /v1/alert-rules/remove-users  (v1 - Remove users from a rule's watch list)	NA
POST /v1/alert-rules/remove-user-aliases (v1 - Remove user aliases from a rule's watch list)	NA
POST /v1/alert-rules/remove-all-users (v1 - Remove all users from a rule's watch list)	DELETE /v2/alert-rules/<ID>/users (v2 - Removes all users from a rule's username filter)
POST /v1/alert-rules/query-users (v1 - Get users assigned to a given rule)	GET /v2/alert-rules/<ID>/users  (v2 - Gets the username filter of a rule) GET /v2/alert-rules/<ID>  (v2 - Gets the details of a single rule)
POST /v1/alert-rules/query-cloud-share-permissions-rule (v1 - Get details about a set of Cloud Share Permissions rules)	GET /v2/alert-rules  (v2 - Gets all rules in the service)
POST /v1/alert-rules/query-endpoint-exfiltration-rule (v1 - Get details about a set of Endpoint Exfiltration rules)	GET /v2/alert-rules  (v2 - Gets all rules in the service)
POST /v1/alert-rules/query-file-type-mismatch-rule (v1 - Get details about a set of File Type Mismatch rules)	GET /v2/alert-rules  (v2 - Gets all rules in the service)
POST /v1/alert-rules/query-file-name-rule (v1 - Get details about a set of File Name rules)	GET /v2/alert-rules  (v2 - Gets all rules in the service)

Alerts API to query rules

October 6, 2022

• The POST /v1/alerts/rules/query-rule-metadata API (Query list of all rules in the alerting application) is deprecated and is replaced by the GET /v2/alert-rules API (v2 - Gets all rules in the service).   

September 2022

Enhancements and updates

September 9, 2022

• Added support for API clients in py42. To use an API client with py42, create an API client and use its client ID and secret to initiate the SDKClient.    

September 7, 2022

• The following Users APIs are added to the Code42 Developer Portal. In the path examples, replace <userId> with the user's unique ID:   
  • Get the roles associated with a user:  GET /v1/users/<userId>/roles 
  • Update the roles associated with a user:  PUT /v1/users/<userId>/roles 
  • Activate a user:  POST /v1/users/<userId>/activate  
  • Deactivate a user:  POST /v1/users/<userId>/deactivate  
  • Move a user to a specified organization:  POST /v1/users/<userId>/move 

Deprecations

Deprecated Legal Hold APIs that do not support pagination

September 22, 2022

• Deprecated Legal Hold APIs that do not support pagination, and replaced them with APIs that support pagination and include totalSize in the response. Following are the deprecated Legal Hold APIs, with the corresponding new APIs to use in scripting.   

Deprecated APIs	Replaced by APIs in the Code42 Developer Portal
GET /api/v31/legal-hold-policy/list	GET /v1/legal-hold/policies  (Get a list of policies)
GET /api/v31/legal-hold-matter/list	GET /v1/legal-hold/matters  (Get a list of matters)
GET /api/v31/legal-hold-membership/list	GET /v1/legal-hold/matters/<matterId>/custodians (Get a list of matter custodians)

End of support

September 23, 2022

• Removed  the /api/AuthToken/ API for use in cloud storage. Because this API is called only in limited cloud storage scenarios, you are affected only if you use py42 version 1.25.1 or earlier to automate file restores. Upgrade your py42 instance to version 1.26 or higher.  

August 2022

Enhancements and updates

August 1, 2022

• Added the following case API to the Code42 Developer Portal. In the path example, replace <caseNumber> with the case's unique ID:   

  • Export some or all components of a case:  GET /v1/cases/<caseNumber>/export/full 

End of support

August 31, 2022

• Removed support for the v3_user_token   scheme originally deprecated in January 2022.  The v3_user_token  scheme is replaced by the Bearer scheme, which is the standard scheme for bearer tokens.  

Use this header to pass the token:
Authorization: Bearer <token>

July 2022

Enhancements and updates

July 21, 2022

• Added the following organization APIs to the Code42 Developer Portal. In the path examples, replace <orgGuid> with the organization's globally unique ID:   
  • Get a list of organizations:  GET /v1/orgs 
  • Create an organization:  POST /v1/orgs 
  • Get a specific organization:   GET /v1/orgs/<orgGuid> 
  • Update a specific organization:  PUT /v1/orgs/<orgGuid> 
  • Activate a specific organization:  POST /v1/orgs/<orgGuid>/activate 
  • Deactivate a specific organization:  POST /v1/orgs/<orgGuid>/deactivate 

July 18, 2022

• Added the following APIs in the Code42 Developer Portal to support building integrations with watchlists:   
  • Departments
    • Get a list of departments:  GET /v1/departments 
  • Directory Groups
    • Get a list of directory groups:  GET /v1/directory-groups 

June 2022

Enhancements and updates

June 21, 2022

• The v2/file-events API added new fields (see v2 - Search for file events in the Code42 Developer Portal):
  • event.inserted: Indicates the date and time the event was received for indexing by Code42. This may differ slightly from the existing @timestamp field, which indicates the date and time the event was initially observed.
  • destination.domains: The domain section of the URLs reported in destination.tabs.url. 
  • source.domains: The domain section of the URLs reported in source.tabs.url. (Note: Although similar in name, this field has no relation to source.domain, which reports the FQDN or IP address of the user’s device.)

May 2022

Enhancements and updates

May 20, 2022

• Added a new version (v2) of File Events APIs and deprecated the previous version (v1). The data model for the APIs is improved with new groupings of data model elements in the response. For complete documentation of the following v2 File Event APIs, see the Code42 Developer Portal:  
  • /v2/file-events
  • /v2/file-events/export
  • /v2/file-events/grouping

May 19, 2022

• Added support for watchlists in the Code42 command line interface.   

May 18, 2022

• Removed the email_promo parameter from the User endpoint, as it was no longer in use.  

May 12, 2022

• Added support for watchlists in py42.   

Deprecations

May 20, 2022

• The previous version (v1) of the following File Events APIs in the Code42 Developer Portal are deprecated and replaced by a new version (v2).  
  • /v1/file-events
  • /v1/file-events/export
  • /v1/file-events/grouping 

May 18, 2022

Deprecated User APIs

Following are the deprecated User APIs, with the corresponding new APIs to use in scripting. For additional User APIs, see User APIs in the Code42 Developer Portal. 

Deprecated API	Replaced by APIs in the Code42 Developer Portal
PUT /api/UserBlock/<user_id>	NA
DELETE /api/UserBlock/<user_id>	NA
PUT /api/UserDeactivation/<user_id>	POST /v1/users/<userId>/deactivate  (Deactivate a user)
DELETE /api/UserDeactivation/<user_id>	POST /v1/users/<userId>/activate  (Activate a user)
POST /api/UserRole	PUT /v1/users/<userId>/roles  (Update the roles associated with a user)
DELETE /api/UserRole?userId=<user_id>&roleId=<role_id>	NA
GET /api/UserRole/<userId>	GET /v1/users/<userId>/roles  (Get the roles associated with a user)
POST /api/UserMoveProcess	POST /v1/users/<userId>/move  (Move a user to a specified organization)

Note: In the path examples, replace <userId> with the user's unique ID. 

Deprecated Org APIs

Following are the deprecated Org APIs, with the corresponding new APIs to use in scripting. For additional Org APIs, see organization APIs in the Code42 Developer Portal.  

Note: In the path examples, replace <orgGuid> with the organization's unique ID. 

Deprecated APIs	Replaced by APIs in the Code42 Developer Portal
GET /api/v1/Org	GET /v1/orgs  (Get a list of organizations)
POST /api/v1/Org	POST /v1/orgs  (Create an organization)
PUT /api/v1/Org	PUT /v1/orgs/<orgGuid>  (Update a specific organization)
PUT /api/v1/OrgBlock	NA
DELETE /api/v1/OrgBlock	NA
PUT /api/v1/OrgDeactivation	POST /v1/orgs/<orgGuid>/activate  (Activate a specific organization)
DELETE /api/v1/OrgDeactivation	POST /v1/orgs/<orgGuid>/deactivate  (Deactivate a specific organization)

February 2022

Enhancements and updates

February 28, 2022

• Added Watchlists APIs in the Code42 Developer Portal to support building integrations with watchlists. 

February 17, 2022

• Removed the lastLoginDate parameter from the User resource.

Deprecations

February 28, 2022

• Deprecated Detection Lists APIs in the Code42 Developer Portal. Detection List APIs are replaced by Watchlists APIs.

January 2022

Enhancements and updates

January 26, 2022

• The www-authenticate header is removed from the Code42 API. As a result, making an API call with basic authentication is no longer supported in a web browser (for example to download a CSV file). To make API calls, use programming, or tools like Postman or cURL. Also as a result of this change, basic authentication of Code42 APIs is no longer supported in PowerShell unless you set a request header for authentication.  

Deprecations

Basic authentication

January 26, 2022

Basic authentication is deprecated for APIs in the Code42 Developer Portal and is replaced by API clients. Basic authentication will continue to be supported for APIs not in the Code42 Developer Portal. This change is being made to align with security best practices for least privilege integrations. 

Following are examples of basic authentication API calls that are now deprecated:

• Basic authentication:

curl -u "<username>:<password>" <RequestURL>/<Resource>

• Basic authentication to obtain an authentication token:

curl -X GET -u "<username>:<password>" <RequestURL>/v1/auth

This also includes using basic authentication to obtain an authentication token when a second factor (TOTP) token is required. For example:

curl -X -H "totp-auth: <totp_token" GET -u "<username>:<password>" <RequestURL>/v1/auth 

In the path examples, replace <RequestURL> with the URL path for your Code42 cloud. For more information, see Code42 API authentication methods.

Inconsistent API URL paths

January 26, 2022

Code42 is deprecating inconsistent Code42 API URL paths and is replacing them with unified URL paths across all APIs. This change only affects Code42 customers who use the older Code42 API paths in scripting. This change does not affect you if you use invocations from the Code42 Developer Portal. 

Following are the deprecated paths, with the corresponding new paths to use in scripting.

Deprecated URL paths	New URL paths
<RequestURL>/<resource>	<RequestURL>/api/v1/<Resource>
<RequestURL>/api/<resource>	<RequestURL>/api/v1/<Resource>
<RequestURL>/<webapp>/api/<resource>	<RequestURL>/api/v1/<Resource>
<RequestURL>/<webapp>/api/v1/<resource>	<RequestURL>/api/v1/<Resource>
<RequestURL>/<webapp>/api/v2/<resource>	<RequestURL>/api/v2/<Resource>
<RequestURL>/c42api/v3/<resource>	<RequestURL>/api/v3/<resource>

Note the following:

• In the path examples, replace <RequestURL> with the URL path for your Code42 cloud. For example:
  • United States
    • US1: https://console.us.code42.com
    • US2: https://console.us2.code42.com
    • US3: https://console.gov.code42.com (Code42 federal environment only)
  • Ireland
    • EU1: https://console.ie.code42.com
• Those instances where the initial character of v1 and v2 resources were lowercase, they must now begin with an uppercase character. The capitalization of resources in v3 and higher APIs is unchanged.
• In the examples, <webapp> is one of the following: account, app, business, client-management, console, consumer, enterprise, enterprise-store, legal-hold, login, partner, reporting, search, security, or subscriptions.

v3_user_token scheme

January 26, 2022

The v3_user_token scheme is deprecated and is replaced by the Bearer scheme, which is the standard scheme for bearer tokens. 

Following is the deprecated header used to pass a user token to an API:
Authorization: v3_user_token <token>

Going forward, use this header instead to pass the token:
Authorization: Bearer <token>

Auth/jwt API endpoint

January 26, 2022

The /c42api/v3/auth/jwt  endpoint is now deprecated as a method for obtaining an OAuth token and is replaced by API clients. 

APIs that do not support API clients

January 26, 2022

The following APIs are deprecated because they do not support API clients. 

If you perform all your API integrations using APIs in the Code42 Developer Portal, the following API deprecations do not affect you since APIs in the Code42 Developer Portal support API clients. 

Deprecated Legal Hold APIs

Following are the deprecated Legal Hold APIs, with the corresponding new APIs to use in scripting.   

Deprecated APIs	Replaced by APIs in the Code42 Developer Portal
GET /api/v4/legal-hold-policy	GET /v1/legal-hold/policies  (Get a list of policies)
POST /api/LegalHoldResource	POST /v1/legal-hold/matters  (Create a matter)
GET /api/LegalHoldResource	GET /v1/legal-hold/matters  (Get a list of matters)
GET /api/LegalHoldResource	NA
GET /api/LegalHoldSummary/<legalHoldUid>	GET /v1/legal-hold/matters/<matterId> (Get a matter)
GET /api/LegalholdSummary?activeState=<ACTIVE|INACTIVE|ALL>	GET /v1/legal-hold/matters  (Get a list of matters)
GET /api/LegalHoldEventResource?legalHoldUid=<legalHoldUid>	NA
GET /api/LegalHoldEventResource	NA
POST /api/LegalHoldMembershipResource	POST /v1/legal-hold/matters/<matterId>/custodians (Add a user to a matter)
GET /api/LegalHoldMembershipResource?userUid=<userUid>	GET /v1/legal-hold/custodians/<userId> (Get a list of matters for a user)
GET /api/LegalHoldMembershipResource?legalHoldUid=<legalHoldUid>	GET /v1/legal-hold/matters/<matterId>/custodians (Get a list of matter custodians)
GET /api/LegalHoldMembershipResource/<legalHoldMembershipUid>	NA
POST /api/LegalHoldMembershipDeactivation	NA

 

Previous release notes

Prior to January 2022, API release notes were incorporated into our general release notes. See Previous version release notes.

Related topics

• Code42 Developer Portal
• Incydr release notes
• Code42 API resources
• API clients
• Code42 API authentication methods