This article is a platform for notifications on potentially breaking changes and end-of-life (EoL) announcements for the Cato GraphQL API schema and contains information that might require you to update the API client.
The API terms used in this article are explained in What is the Cato API.
For any customers using the Cato API, we recommend that you click Follow to automatically receive email notifications for updates to this article about breaking changes to the API. You can also see more information about new and updated APIs in the Cato API Changelog.
For more information about the APIs, see the Cato Networks GraphQL API Reference.
Currently, Cato's API gateway may return ID fields as either a String or a Long (integer). As part of an upcoming infrastructure update, all ID fields will consistently be returned as Strings.
-
What's changing: API responses that previously returned ID fields as a numeric Long values (for example,
1000000002) will now always return them as Strings (for example,"1000000002"). - Who is affected: API clients that handle ID fields strictly as Long/integer types may break when this change is rolled out.
- What you should do before June 21, 2026: Update your API client code to accept both Long and String types for ID fields. This will ensure a smooth transition and prevent disruptions when the change takes effect.
On Aug 10, 2025, the email field in the addAdmin and updateAdmin APIs became optional (nullable). This change supports upcoming infrastructure to support granular API access control that includes scripts and automations using service principals.
- Current and future human CMA admins must always include an
emailvalue - Queries that return only human admins are unaffected.
- Some clients may need to handle null values in response payloads, such as addAdminPayload
This is not typically a breaking change, but it may impact clients that assume email is always present. Review your integration to avoid issues.
The eventsFeed API uses a marker to enable iteratively pulling the events feed. The Marker field shows an identifier that indicates the start of a new iteration to fetch events. The API reads events from the queue based on the unique Marker field, and provides the next marker location in the response. If there are no new events in the queue, then the Marker field is empty
An alternative events consumption model is to use the direct no-code integration, see Integrating Cato Events with AWS S3 and Integrating Cato Events with Azure Storage Account.
What did we change?
- Previously, when the marker was not specified, the API returned the oldest available marker. This required consuming the entire event queue before reaching the most recent events.
- Starting from April 27, 2025, if no marker is specified, the API returns the most recent marker. This allows the API to pull the most recent events directly.
Is it a breaking change?
- There is no impact for most use cases of the eventsFeed API. There is no change when the Marker field is used for a query, and the events feed consumption logic is the same.
-
If you have a dedicated logic to consume the queue to reach the recent events, this logic is no longer required.
- Now, if no input marker is specified, the API provides the most recent marker. Calling the API with this marker fetches the most recent events
- The API response contains a marker that points to the most recent (top of the queue) location
- The corresponding scripts and automated processes should be updated
We changed the functionality of the limit field so that limit=0 is no longer supported because this isn’t considered a best practice. To ensure continued smooth operation, you need to update any scripts or queries that rely on this parameter. Instead, you can set a limit between 1-2000, which the API fully supports.
If you need to retrieve all stories, we recommend using a pagination approach.
The following fields and types in the LastMileBWInput API are currently marked as Deprecated and reached end-of-life (EoL) on June 30, 2025.
Please use the recommended fields and types instead.
| Deprecated Type | Recommended Type |
|---|---|
| downstream | downstreamMbpsPrecision |
| upstream | upstreamMbpsPrecision |
The following fields and types in the InterfaceInfo API are currently marked as Deprecated and reached end-of-life (EoL) on June 30, 2025.
Please use the recommended fields and types instead.
| Deprecated Type | Recommended Type |
|---|---|
| downstreamBandwidth | downstreamBandwidthMbpsPrecision |
| upstreamBandwidth | upstreamBandwidthMbpsPrecision |
The following fields and types in the SocketInterfaceBandwidthInput API are currently marked as Deprecated and reached end-of-life (EoL) on June 30, 2025.
Please use the recommended fields and types instead.
| Deprecated Type | Recommended Type |
|---|---|
| downstreamBandwidth | downstreamBandwidthMbpsPrecision |
| upstreamBandwidth | upstreamBandwidthMbpsPrecision |
- The
auditFeedquery API accepts a list of filters using theAuditFieldFilterInputtype. Each filter includes afieldNamedefined by the typeFieldNameInput, which currently includes two input fields:AuditFieldNameandEventFieldName. - However, only
AuditFieldNameis a valid and supported input field. To improve schema clarity and avoid confusion, theEventFieldNamefield was removed from the schema on June 8, 2025. - Update all scripts and queries that use
auditFeedfilters to only use theAuditFieldNameinput field.
The following fields and types in the EventFieldName API are currently marked as Deprecated and reached end-of-life (EoL) on May 1, 2025.
Please use the recommended fields and types instead.
| Deprecated Type | Recommended Type |
|---|---|
| application | application_id/application_name |
| custom_categories | custom_category_id/custom_category_name |
| custom_category | custom_category_id/custom_category_name |
| dest_site | dest_site_id/dest_site_name |
| device_posture_profiles | device_posture_profile |
| internalId | event_id |
| rule | rule_name |
| src_site | src_site_id/src_site_name |
The following fields and types in the EventFieldName API were marked as Deprecated and are end-of-life (EoL) as of March 1, 2025.
Please use the recommended fields and types instead.
| Deprecated Type | Recommended Type |
|---|---|
| parent_pid | src_process_parent_pid |
| pid | src_pid |
| process_path | src_process_path |
The following field in the StoryDrillDownFilter Beta API was marked as Deprecated and is end-of-life (EoL) as of Feb 23, 2025.
Please use the recommended fields and types instead.
| Deprecated Type | Recommended Type |
|---|---|
| value | values |
Following the announcement of EoL for some SubType values used in the event consumption APIs related to the Cato Clients, the rollout is paused for accounts that use the Ireland CMA location (cc.catonetworks.com) for the following fields:
| Deprecated Type | Recommended Type |
|---|---|
| Reconnected | Connected or Disconnected |
| Changed PoP |
Connected or Disconnected (The PoP name is returned in the lastPopName field.) |
- For more information, see CMA - Technical Guidelines
The following fields and types related to the Cato Client were marked as Deprecated and are end-of-life (EoL) as of January 2, 2025.
Please use the recommended fields and types instead.
| Deprecated Type | Recommended Type | Notes |
|---|---|---|
| VPN Never-Off-Bypass | Always-On Bypass | The VPN Never-Off-Bypass SubType value is being replaced with the value Always-On Bypass |
| Reconnected | Connected or Disconnected | To increase granularity, the Reconnected SubType value is being split into 2 new values, Connected and Disconnected |
| Changed PoP |
Connected or Disconnected (The PoP name is returned in the lastPopName field) |
To increase granularity, the Changed PoP SubType value is being split into 2 new values, Connected and Disconnected |
- For more information, see this article: Upcoming EoL for Some SubTypes of Cato Event Data
7 comments
Added upcoming change for XDR API, limit=0 will no longer be supported as of Feb, 9. 2025
Updated the EoL date from May 1, 2025 to March 1, 2025 for the following EventFieldName types: parent_pid, pid, and process path.
Added upcoming EoL for StoryDrillDownFilter value Field
Update to EoL for Some SubTypes of Cato Event Data
Added change for eventsFeed Query API Supports Fetching the Most Recent Events
Added Upcoming EoL for SecondarySocketSerial Field on March 18, 2026
Added details of a potentially breaking change ‘API ID Fields: Type Change from Long/Integer to String’ set to occur on 21st June 2026.
Please sign in to leave a comment.