Migrate to Chronicle API

Supported in:

This document outlines the steps and considerations to help you update programmatic API references to the SOAR API endpoints as part of Chronicle API.

The Chronicle API surface introduces several improvements designed to streamline your development process. It also addresses limitations and complexities present in the older API.

The legacy SOAR API and API keys remain available until March 31, 2027, after which they stop functioning.

Out-of-the-box response integrations

If you're using an outdated integration version that is calling the legacy SOAR APIs, update the integration package before March 31, 2027:

  • Content Hub integrations: Open Content Hub in Google Security Operations and update any outdated commercial integrations to their latest versions. For more information, see Content Hub overview.
  • Splunk add-on: If you use the Chronicle SOAR Add-on for Splunk, upgrade TA-Siemplify in Splunk to the latest version. After upgrading, reconfigure the add-on to use your regional Chronicle API endpoint and Google Cloud service account credentials.

Prerequisites

Before migrating SOAR API calls to the Chronicle API, complete Stage 1 of the migration (Google.com appears next to the system version in SOAR Settings > License Management). You can test and migrate programmatic Chronicle API calls before or after enabling Google Cloud Identity and Access Management (IAM) for SOAR permission groups.

Key changes and enhancements

The following table highlights the major differences between the old and new API surfaces:

Feature area Old API New API Details
Authentication API token OAuth 2.0 The new authentication method provides enhanced security and standardizes the process.
Data models Flat structures Resource-oriented design This new design improves data consistency and simplifies object manipulation.
Endpoint naming Inconsistent RESTful and standardized Consistent naming makes the API more intuitive and easier to integrate.

Deprecation schedule

The legacy siemplify-soar.com API surface and AppKey authentication remain available until March 31, 2027, after which they stop functioning.

Until March 31, 2027, legacy SOAR APIs continue to work in parallel with the Chronicle API—even after you enable Google Cloud IAM—so you can gradually migrate and validate each component at your own pace without disrupting active workflows.

Because the legacy SOAR API is less efficient than the Chronicle API, we recommend migrating to the Chronicle API substitutes as soon as possible, and before March 31, 2027 to avoid service interruptions.

Migration steps

This section outlines the steps to successfully migrate your applications to Chronicle API:

Review the documentation

Familiarize yourself with the comprehensive documentation for the new API, including the Chronicle API reference guide.

Map endpoints to the new API surface

Identify the corresponding new endpoints for each of the old API calls your application makes. Similarly, map the old data models to the new ones, accounting for any structural changes or new fields. For details, see API endpoint mapping table.

Optional: Create a staging integration

If you're editing a custom integration or a custom action, Google recommends that you push the changes to a staging integration first. This process lets you test without impacting your production automation flows. If you're migrating a custom-built application that uses the SOAR API, you can skip to the next step. For details about integration staging, see Test integrations in staging mode.

Update the service endpoint and URLs

A service endpoint is the base URL that specifies the network address of an API service. A single service can have multiple service endpoints. Chronicle is a regional service and only supports regional endpoints.

All new endpoints use a consistent prefix, making the final endpoint address predictable. The following example shows the new endpoint URL structure:

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

This structure makes the final address to the endpoint as follows:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Where:

  • service_endpoint: A regional service address
  • api_version: The API version to query. Use v1 when available, or fall back to v1beta or v1alpha if v1 isn't available yet (check the SOAR API mapping table for the version supported by each endpoint).
  • project_id: Your project ID (same project as you defined for your IAM permissions)
  • location: The location of your project (region); same as the regional endpoints
  • instance_id: Your Google Security Operations SIEM customer ID.

Regional addresses:

  • africa-south1: https://africa-south1-chronicle.googleapis.com

  • asia-northeast1: https://asia-northeast1-chronicle.googleapis.com

  • asia-south1: https://asia-south1-chronicle.googleapis.com

  • asia-southeast1: https://asia-southeast1-chronicle.googleapis.com

  • asia-southeast2: https://asia-southeast2-chronicle.googleapis.com

  • australia-southeast1: https://australia-southeast1-chronicle.googleapis.com

  • europe-west12: https://europe-west12-chronicle.googleapis.com

  • europe-west2: https://europe-west2-chronicle.googleapis.com

  • europe-west3: https://europe-west3-chronicle.googleapis.com

  • europe-west6: https://europe-west6-chronicle.googleapis.com

  • europe-west9: https://europe-west9-chronicle.googleapis.com

  • me-central1: https://me-central1-chronicle.googleapis.com

  • me-central2: https://me-central2-chronicle.googleapis.com

  • me-west1: https://me-west1-chronicle.googleapis.com

  • northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com

  • southamerica-east1: https://southamerica-east1-chronicle.googleapis.com

  • us: https://us-chronicle.googleapis.com

  • eu: https://eu-chronicle.googleapis.com

For example, to get a list of all cases on a project in the US:

GET
  https://us-chronicle.googleapis.com/v1/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

Update the authentication method

The Chronicle API uses Google Cloud IAM for authentication. Update your custom integrations or external applications to implement this authentication flow. Make sure the user or service account running the script has the required permissions for the target endpoints. For more information, see Authenticate to Chronicle API.

Map the service account or workload identity to SOAR parameters

If you are using a service account or workload identity federation to authenticate to the Chronicle API, you must authorize it within the platform to ensure it can successfully communicate with Google SecOps. This mapping is required to provide the service account or workload identity with the necessary access to SOC Roles and Environments.

To grant a service account access or workload identity federation access to Google SecOps, you must map the identity to the platform's access control parameters. This mapping is a mandatory step to provide the identity with the necessary access to SOC Roles, and Environments required to perform automated tasks or API operations.

  1. Go to Settings > Access Management > Group Mapping.
  2. Click add Add.
  3. Complete the fields in the Add Mapping dialog to map the identity to the platform's access control parameters.

    1. In the IdP / User group field, enter one of the following:
      • The full email address of your service account, if identity was set up using Cloud Identity.
      • The Workload Identity principal string, if identity was set up using Workforce Identity Federation.
    2. Configure the following access control fields:

      Field Description
      Permission groups Select the permission groups to define which modules and submodules the identity can access.
      SOC roles Select the SOC roles to define the identity's role (such as Tier 1).
      Environments Select the environments or environment groups the identity can access (such as All Environments).
      Group members Enter the required user emails if applicable. Press Enter after adding each email.
      Restricted actions Select the restricted actions to limit specific operations within modules.
  4. Click Add.

For more detailed information on mapping users and service accounts, see Map users in the platform using third-party identity or Map users in the platform using Cloud Identity.

Update API logic

Analyze the new data models and endpoint structures provided in the API reference. Not all methods have changed significantly, and some existing code can be reused. The primary objective is to review the new reference documentation and, for each specific use case, identify and implement necessary changes to field names and data structures within your application's logic.

Migrate custom API calls to the Chronicle API

Not all custom Python code in Google SecOps requires code changes:

  • Built-in SDK methods require no code changes: Custom Python code in custom integrations, playbook actions, connectors, and jobs that uses standard built-in SDK methods—such as siemplify.add_comment(), siemplify.get_case_comments(), or siemplify.update_alerts_additional_data()—requires no code modifications. Google SecOps automatically routes built-in Siemplify SDK methods through the unified API surface.
  • Only manual HTTP requests require updates: You only need to update custom Python scripts that manually construct HTTP requests to legacy SOAR APIs using SDK properties—for example, building a URL with siemplify.API_ROOT and authenticating with siemplify.api_key using requests or siemplify.session. To identify affected custom components, run resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" in Logs Explorer (inspecting labels.integration_name, labels.action_name, labels.connector_name, labels.job_name, and labels.playbook_name), or check the CustomCode list in the legacy API usage summary report.

Test your integration

Test your updated application in a staging integration before deploying to production:

  1. Create a test plan: Define test cases that cover all migrated functionalities.
  2. Execute tests: Run automated and manual tests to confirm accuracy and validity.
  3. Monitor performance: Assess the performance of your application with the new API.

Quotas and rate limits

The Chronicle API enforces Google Cloud project-level quotas to maintain service availability and prevent runaway traffic:

  • Default quotas: The Chronicle API enforces requests-per-minute (RPM) limits at the Google Cloud project level—typically 6,000 RPM per project, with regional API sub-limits.
  • Rate-limiting errors (HTTP 429): If an integration or external script exceeds your project quota, the Chronicle API returns HTTP 429 (RESOURCE_EXHAUSTED or TooManyRequestsException).

To view your current Chronicle API quota usage or request a higher limit, follow these steps:

  1. In the Google Cloud console, go to IAM & Admin > Quotas & System Limits:

    Go to Quotas & System Limits

  2. Click Filter, select Service, and enter chronicle.googleapis.com to inspect current usage and limits. For more information, see View quotas in the Google Cloud console.

  3. If your production ingestion, automation, or ticketing integration requires higher limits, select the checkbox next to the relevant quota and click Edit (or Edit Quotas) to request an increase. For detailed steps, see Request a quota adjustment. You can also submit a quota increase request through Cloud Customer Care or your Google SecOps representative.

Audit remaining legacy API usage

You can identify remaining legacy SOAR API calls using Logging, in-product system notifications, or the legacy API usage summary endpoint.

Query Logging

Legacy API deprecation warnings (labels.auth_deprecation="true") are emitted as WARNING-severity SOAR operational logs under resource.labels.namespace_name="chronicle-soar" (see Collect SOAR platform logs), rather than in Cloud Audit Logs. Only customer-actionable warnings (labels.actionable_by="Customer") are exported to your Google Cloud project; internal Google UI and system calls are filtered out automatically.

Run the following queries in Logs Explorer:

  • Remote Agent attribution (labels.is_remote="true"): Indicates legacy calls from code running on a Remote Agent. First, upgrade the Remote Agent to version 2.6.2 or later and migrate it to service account authentication (see Migrate remote agent authentication infrastructure). Once the Remote Agent is upgraded and configured with a Google Cloud service account, the agent's own control-plane polling uses OAuth 2.0; full component label attribution for Remote Agent SDK calls is being released in stages across production. If entries continue after migrating the agent, check for outdated integrations or custom code running on that agent.

  • 30-day zero-log completion check (all customer-actionable legacy calls):

    resource.labels.namespace_name="chronicle-soar"
    labels.auth_deprecation="true"
    

    Your API migration is complete when this query returns zero logs over 30 consecutive days.

  • External scripts and third-party tools calling legacy APIs directly (AppKey):

    resource.labels.namespace_name="chronicle-soar"
    labels.auth_deprecation="true"
    labels.is_system="false"
    

    Emitted fields include labels.app_key (the legacy API key identifier), labels.via_xlb ("true" for external ingress), and the called HTTP route in textPayload (Deprecated direct AppKey authentication detected (Route: ROUTE).).

  • Outdated Content Hub integrations: To check whether installed commercial integrations still call legacy SOAR APIs, run the following query to list matching deprecation entries (see Out-of-the-box response integrations):

    resource.labels.namespace_name="chronicle-soar"
    labels.auth_deprecation="true"
    labels.is_system="true"
    labels.is_custom="false"
    
    Logs Explorer query results listing deprecation entries for an outdated commercial integration.
    Figure 1. Logs Explorer query results listing deprecation entries for an outdated commercial integration.

    Expand a matching log entry to view labels.integration_name, labels.integration_version, labels.latest_integration_version, and the triggering component (labels.action_name, labels.connector_name, labels.job_name, or labels.playbook_name):

    Expanded deprecation log entry in Logs Explorer showing installed and latest commercial integration versions.
    Figure 2. Expanded deprecation log entry showing the installed and latest commercial integration versions.

    You can also check the OutdatedIntegrations list in the legacy API usage summary report.

  • Custom Python code making manual HTTP calls: Run resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" (see Migrate custom API calls to the Chronicle API).

Check in-product system notifications

As this capability becomes available in Google SecOps instances, System Notifications displays a summary of customer-actionable legacy API calls from the past 24 hours across outdated Content Hub integrations, custom IDE components, and external API keys, similar to the following example:

Non-1P API usage summary (last 24h): 2294 legacy API call(s) require action.
Content Hub - Update 1 outdated integration(s): GoogleChronicle (v94->v98).
IDE - Refactor 15 custom component(s): Action 'CustomAction' (LegacyAuthCases),
Connector 'CustomConnector' (LegacyAuthCases), Job 'CustomJob'
(LegacyAuthCases) (+12 more).
Settings > API Keys - Migrate 1 external key(s) to 1P auth:
'example_external_automation_key'.

Query the legacy API usage summary endpoint

You can also query GET /api/external/v1/logging/non-1p-api-usage directly to retrieve an aggregated JSON report of recent legacy API calls:

  1. In SOAR Settings > Advanced > API Keys, create or select a legacy API key assigned to a permission group that includes the Settings permission. For instructions, see Authenticate to legacy SOAR API.
  2. Send a GET request with the AppKey header (set hoursBack between 1 and 168; defaults to 24):

    curl -H "AppKey: API_KEY" \
      "https://INSTANCE.siemplify-soar.com/api/external/v1/logging/non-1p-api-usage?hoursBack=24"
    

The response groups customer-actionable deprecation warnings into the following sections:

  • OutdatedIntegrations: Lists commercial Content Hub integrations where InstalledVersion is older than LatestVersion, including IntegrationName, InstalledVersion, LatestVersion, ActionNeeded, InvocationCount, FirstUsedTimestamp, LastUsedTimestamp, and affected components (AffectedActions, AffectedConnectors, AffectedJobs, AffectedPlaybooks), similar to the following example:

    {
      "OutdatedIntegrations": [
        {
          "IntegrationName": "GoogleChronicle",
          "InstalledVersion": "94",
          "LatestVersion": "98",
          "ActionNeeded": "Upgrade integration to v98 in Content Hub",
          "AffectedActions": ["Ping"],
          "AffectedConnectors": ["Google Chronicle - Chronicle Alerts Connector"],
          "InvocationCount": 202,
          "FirstUsedTimestamp": "2026-10-14T19:16:31Z",
          "LastUsedTimestamp": "2026-10-14T19:44:54Z"
        }
      ]
    }
    
  • CustomCode: Lists custom SDK components (ComponentType: Action, Connector, Job, Playbook, or Custom Script) making manual legacy API calls, including ComponentName, IntegrationName, AffectedPlaybooks, RoutesUsed, InvocationCount, FirstUsedTimestamp, and LastUsedTimestamp.

  • DirectAppKeys: Lists direct external AppKey calls made outside the SDK, including AppKey, ActionNeeded, RoutesUsed, InvocationCount, FirstUsedTimestamp, and LastUsedTimestamp, similar to the following example:

    {
      "DirectAppKeys": [
        {
          "AppKey": "example_external_automation_key",
          "ActionNeeded": "Migrate external script or automation to use Google Cloud service account or OAuth authentication",
          "RoutesUsed": [
            "GET /api/external/v1/cases/GetCaseFullDetails/14",
            "GET /api/external/v1/dynamic-cases/GetCaseDetails/14",
            "GET /api/external/v1/ide/GetIdeItemCards",
            "GET /api/external/v1/jobs/GetInstalledJobs",
            "GET /api/external/v1/jobs/GetJobHistoryLogs/jobIdStr",
            "GET /api/external/v1/logging/non-1p-api-usage",
            "GET /api/external/v1/playbooks/GetWorkflowFullInfoWithEnvFilterByIdentifier/00000000-0000-0000-0000-000000000000",
            "POST /api/external/v1/ide/GetIdeItem",
            "POST /api/external/v1/ide/TestItem",
            "POST /api/external/v1/integrations/GetOptionalIntegrationInstances",
            "POST /api/external/v1/jobs/RunJob",
            "POST /api/external/v1/playbooks/AttacheWorkflowToCase",
            "POST /api/external/v1/playbooks/GetWorkflowMenuCardsWithEnvFilter",
            "POST /api/external/v1/playbooks/RerunPlaybook"
          ],
          "InvocationCount": 1084,
          "FirstUsedTimestamp": "2026-10-14T19:30:15.169684Z",
          "LastUsedTimestamp": "2026-10-14T20:24:13.552893800Z"
        }
      ]
    }
    
  • TopOffenders (TopAppKeys and TopRoutes): Summarizes the most frequently used legacy AppKey identities and HTTP routes (HTTP method and route) to help you prioritize migration work.

Need more help? Get answers from Community members and Google SecOps professionals.