Add partial hierarchy selection to team sync endpoints (#3591)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -65885,6 +65885,8 @@ components:
       properties:
         frequency:
           $ref: "#/components/schemas/TeamSyncAttributesFrequency"
+        selection_state:
+          $ref: "#/components/schemas/TeamSyncAttributesSelectionState"
         source:
           $ref: "#/components/schemas/TeamSyncAttributesSource"
         sync_membership:
@@ -65907,6 +65909,14 @@ components:
         - ONCE
         - CONTINUOUSLY
         - PAUSED
+    TeamSyncAttributesSelectionState:
+      description: |-
+        Specifies which teams or organizations to sync. When
+        provided, synchronization is limited to the specified
+        items and their subtrees.
+      items:
+        $ref: "#/components/schemas/TeamSyncSelectionStateItem"
+      type: array
     TeamSyncAttributesSource:
       description: The external source platform for team synchronization. Only "github" is supported.
       enum:
@@ -65916,6 +65926,7 @@ components:
       x-enum-varnames:
         - GITHUB
     TeamSyncAttributesSyncMembership:
+      default: false
       description: Whether to sync members from the external team to the Datadog team. Defaults to `false` when not provided.
       example: true
       type: boolean
@@ -65975,6 +65986,72 @@ components:
             $ref: "#/components/schemas/TeamSyncData"
           type: array
       type: object
+    TeamSyncSelectionStateExternalId:
+      description: The external identifier for a team or organization in the source platform.
+      properties:
+        type:
+          $ref: "#/components/schemas/TeamSyncSelectionStateExternalIdType"
+        value:
+          $ref: "#/components/schemas/TeamSyncSelectionStateExternalIdValue"
+      required:
+        - type
+        - value
+      type: object
+    TeamSyncSelectionStateExternalIdType:
+      description: |-
+        The type of external identifier for the selection state item.
+        For GitHub synchronization, the allowed values are `team` and
+        `organization`.
+      enum:
+        - team
+        - organization
+      example: team
+      type: string
+      x-enum-varnames:
+        - TEAM
+        - ORGANIZATION
+    TeamSyncSelectionStateExternalIdValue:
+      description: |-
+        The external identifier value from the source
+        platform. For GitHub, this is the string
+        representation of a GitHub organization ID or team
+        ID.
+      example: "1"
+      type: string
+    TeamSyncSelectionStateItem:
+      description: Identifies a team or organization hierarchy to include in synchronization.
+      properties:
+        external_id:
+          $ref: "#/components/schemas/TeamSyncSelectionStateExternalId"
+        operation:
+          $ref: "#/components/schemas/TeamSyncSelectionStateOperation"
+        scope:
+          $ref: "#/components/schemas/TeamSyncSelectionStateScope"
+      required:
+        - external_id
+      type: object
+    TeamSyncSelectionStateOperation:
+      description: |-
+        The operation to perform on the selected hierarchy.
+        When set to `include`, synchronization covers the
+        referenced teams or organizations.
+      enum:
+        - include
+      example: include
+      type: string
+      x-enum-varnames:
+        - INCLUDE
+    TeamSyncSelectionStateScope:
+      description: |-
+        The scope of the selection. When set to `subtree`,
+        synchronization includes the referenced team or
+        organization and everything nested under it.
+      enum:
+        - subtree
+      example: subtree
+      type: string
+      x-enum-varnames:
+        - SUBTREE
     TeamTarget:
       description: "Represents a team target for an escalation policy step, including the team's ID and resource type."
       properties:
@@ -105434,12 +105511,6 @@ paths:
           description: OK
         "403":
           $ref: "#/components/responses/ForbiddenResponse"
-        "404":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/APIErrorResponse"
-          description: Team sync configurations not found
         "429":
           $ref: "#/components/responses/TooManyRequestsResponse"
       security:
@@ -105456,13 +105527,17 @@ paths:
           - teams_read
     post:
       description: |-
-        This endpoint attempts to link your existing Datadog teams with GitHub teams by matching their names.
+        This endpoint configures synchronization between your existing Datadog teams and GitHub teams by matching their names.
         It evaluates all current Datadog teams and compares them against teams in the GitHub organization
         connected to your Datadog account, based on Datadog Team handle and GitHub Team slug
         (lowercased and kebab-cased).
 
         This operation is read-only on the GitHub side, no teams will be modified or created.
 
+        Optionally, provide `selection_state` to limit synchronization
+        to specific teams or organizations and their subtrees, instead
+        of syncing all teams.
+
         [A GitHub organization must be connected to your Datadog account](https://docs.datadoghq.com/integrations/github/),
         and the GitHub App integrated with Datadog must have the `Members Read` permission. Matching is performed by comparing the Datadog team handle to the GitHub team slug
         using a normalized exact match; case is ignored and spaces are removed. No modifications are made
@@ -105477,6 +105552,8 @@ paths:
       responses:
         "200":
           description: OK
+        "204":
+          description: No Content
         "403":
           $ref: "#/components/responses/ForbiddenResponse"
         "429":

cassettes/v2/Teams_3116892301/Get-team-sync-configurations-returns-OK-response_2349360064/frozen.json

@@ -0,0 +1 @@
+"2026-03-04T16:01:00.945Z"

cassettes/v2/Teams_3116892301/Get-team-sync-configurations-returns-OK-response_2349360064/recording.har

@@ -0,0 +1,64 @@
+{
+  "log": {
+    "_recordingName": "Teams/Get team sync configurations returns \"OK\" response",
+    "creator": {
+      "comment": "persister:fs",
+      "name": "Polly.JS",
+      "version": "6.0.5"
+    },
+    "entries": [
+      {
+        "_id": "9340a9d9b12be8261e72ba1bbc945a32",
+        "_order": 0,
+        "cache": {},
+        "request": {
+          "bodySize": 0,
+          "cookies": [],
+          "headers": [
+            {
+              "_fromType": "array",
+              "name": "accept",
+              "value": "application/json"
+            }
+          ],
+          "headersSize": 521,
+          "httpVersion": "HTTP/1.1",
+          "method": "GET",
+          "queryString": [
+            {
+              "name": "filter",
+              "value": {
+                "source": "github"
+              }
+            }
+          ],
+          "url": "https://api.datadoghq.com/api/v2/team/sync?filter%5Bsource%5D=github"
+        },
+        "response": {
+          "bodySize": 282,
+          "content": {
+            "mimeType": "application/vnd.api+json",
+            "size": 282,
+            "text": "{\"data\":[{\"id\":\"3d33cc55-aea4-4801-bb75-139d347298c9\",\"type\":\"team_sync_bulk\",\"attributes\":{\"frequency\":\"once\",\"selection_state\":[{\"external_id\":{\"type\":\"organization\",\"value\":\"1\"},\"operation\":\"include\",\"scope\":\"subtree\"}],\"source\":\"github\",\"sync_membership\":false,\"type\":\"link\"}}]}"
+          },
+          "cookies": [],
+          "headers": [
+            {
+              "name": "content-type",
+              "value": "application/vnd.api+json"
+            }
+          ],
+          "headersSize": 659,
+          "httpVersion": "HTTP/1.1",
+          "redirectURL": "",
+          "status": 200,
+          "statusText": "OK"
+        },
+        "startedDateTime": "2026-03-04T16:01:00.949Z",
+        "time": 322
+      }
+    ],
+    "pages": [],
+    "version": "1.2"
+  }
+}

cassettes/v2/Teams_3116892301/Link-Teams-with-GitHub-Teams-returns-No-Content-response_3413215892/frozen.json

@@ -0,0 +1 @@
+"2026-03-04T16:01:34.366Z"

…rns-OK-response_3488879418/recording.har …ontent-response_3413215892/recording.harcassettes/v2/Teams_3116892301/Sync-teams-returns-OK-response_3488879418/recording.har renamed to cassettes/v2/Teams_3116892301/Link-Teams-with-GitHub-Teams-returns-No-Content-response_3413215892/recording.har cassettes/v2/Teams_3116892301/Sync-teams-returns-OK-response_3488879418/recording.har renamed to cassettes/v2/Teams_3116892301/Link-Teams-with-GitHub-Teams-returns-No-Content-response_3413215892/recording.har

@@ -1,18 +1,18 @@
 {
   "log": {
-    "_recordingName": "Teams/Sync teams returns \"OK\" response",
+    "_recordingName": "Teams/Link Teams with GitHub Teams returns \"No Content\" response",
     "creator": {
       "comment": "persister:fs",
       "name": "Polly.JS",
       "version": "6.0.5"
     },
     "entries": [
       {
-        "_id": "394163072f49be157e109223981e6839",
+        "_id": "56fda770a3895f0797c8e26a49e8311d",
         "_order": 0,
         "cache": {},
         "request": {
-          "bodySize": 81,
+          "bodySize": 153,
           "cookies": [],
           "headers": [
             {
@@ -26,13 +26,13 @@
               "value": "application/json"
             }
           ],
-          "headersSize": 535,
+          "headersSize": 534,
           "httpVersion": "HTTP/1.1",
           "method": "POST",
           "postData": {
             "mimeType": "application/json",
             "params": [],
-            "text": "{\"data\":{\"attributes\":{\"source\":\"github\",\"type\":\"link\"},\"type\":\"team_sync_bulk\"}}"
+            "text": "{\"data\":{\"attributes\":{\"selection_state\":[{\"external_id\":{\"type\":\"organization\",\"value\":\"1\"}}],\"source\":\"github\",\"type\":\"link\"},\"type\":\"team_sync_bulk\"}}"
           },
           "queryString": [],
           "url": "https://api.datadoghq.com/api/v2/team/sync"
@@ -44,20 +44,15 @@
             "size": 0
           },
           "cookies": [],
-          "headers": [
-            {
-              "name": "content-type",
-              "value": "text/plain"
-            }
-          ],
-          "headersSize": 653,
+          "headers": [],
+          "headersSize": 594,
           "httpVersion": "HTTP/1.1",
           "redirectURL": "",
-          "status": 200,
-          "statusText": "OK"
+          "status": 204,
+          "statusText": "No Content"
         },
-        "startedDateTime": "2025-08-15T17:48:19.717Z",
-        "time": 203
+        "startedDateTime": "2026-03-04T16:01:34.369Z",
+        "time": 563
       }
     ],
     "pages": [],

cassettes/v2/Teams_3116892301/Sync-teams-returns-OK-response_3488879418/frozen.json

@@ -431,20 +431,13 @@ Feature: Teams
     Then the response status is 200 OK
     And the response "data" has length 1
 
-  @generated @skip @team:DataDog/aaa-omg
+  @team:DataDog/aaa-omg
   Scenario: Get team sync configurations returns "OK" response
     Given new "GetTeamSync" request
-    And request contains "filter[source]" parameter from "REPLACE.ME"
+    And request contains "filter[source]" parameter with value "github"
     When the request is sent
     Then the response status is 200 OK
 
-  @generated @skip @team:DataDog/aaa-omg
-  Scenario: Get team sync configurations returns "Team sync configurations not found" response
-    Given new "GetTeamSync" request
-    And request contains "filter[source]" parameter from "REPLACE.ME"
-    When the request is sent
-    Then the response status is 404 Team sync configurations not found
-
   @generated @skip @team:DataDog/aaa-omg
   Scenario: Get user memberships returns "API error response." response
     Given new "GetUserMemberships" request
@@ -461,6 +454,13 @@ Feature: Teams
     Then the response status is 200 Represents a user's association to a team
     And the response "data" has length 0
 
+  @team:DataDog/aaa-omg
+  Scenario: Link Teams with GitHub Teams returns "No Content" response
+    Given new "SyncTeams" request
+    And body with value {"data": {"attributes": {"source": "github", "type": "link", "selection_state": [{"external_id": {"type": "organization", "value": "1"}}]}, "type": "team_sync_bulk"}}
+    When the request is sent
+    Then the response status is 204 No Content
+
   @generated @skip @team:DataDog/aaa-omg
   Scenario: Link Teams with GitHub Teams returns "OK" response
     Given new "SyncTeams" request
@@ -582,13 +582,6 @@ Feature: Teams
     When the request is sent
     Then the response status is 204 No Content
 
-  @replay-only @team:DataDog/aaa-omg
-  Scenario: Sync teams returns "OK" response
-    Given new "SyncTeams" request
-    And body with value {"data": {"attributes": {"source": "github", "type": "link"}, "type": "team_sync_bulk"}}
-    When the request is sent
-    Then the response status is 200 OK
-
   @team:DataDog/aaa-omg
   Scenario: Update a team link returns "API error response." response
     Given new "UpdateTeamLink" request

features/v2/teams.feature

@@ -3160,11 +3160,7 @@ export class TeamsApiResponseProcessor {
       ) as TeamSyncResponse;
       return body;
     }
-    if (
-      response.httpStatusCode === 403 ||
-      response.httpStatusCode === 404 ||
-      response.httpStatusCode === 429
-    ) {
+    if (response.httpStatusCode === 403 || response.httpStatusCode === 429) {
       const bodyText = parse(await response.body.text(), contentType);
       let body: APIErrorResponse;
       try {
@@ -3592,7 +3588,7 @@ export class TeamsApiResponseProcessor {
    */
   public async syncTeams(response: ResponseContext): Promise<void> {
     const contentType = normalizeMediaType(response.headers["content-type"]);
-    if (response.httpStatusCode === 200) {
+    if (response.httpStatusCode === 200 || response.httpStatusCode === 204) {
       return;
     }
     if (
@@ -5264,13 +5260,17 @@ export class TeamsApi {
   }
 
   /**
-   * This endpoint attempts to link your existing Datadog teams with GitHub teams by matching their names.
+   * This endpoint configures synchronization between your existing Datadog teams and GitHub teams by matching their names.
    * It evaluates all current Datadog teams and compares them against teams in the GitHub organization
    * connected to your Datadog account, based on Datadog Team handle and GitHub Team slug
    * (lowercased and kebab-cased).
    *
    * This operation is read-only on the GitHub side, no teams will be modified or created.
    *
+   * Optionally, provide `selection_state` to limit synchronization
+   * to specific teams or organizations and their subtrees, instead
+   * of syncing all teams.
+   *
    * [A GitHub organization must be connected to your Datadog account](https://docs.datadoghq.com/integrations/github/),
    * and the GitHub App integrated with Datadog must have the `Members Read` permission. Matching is performed by comparing the Datadog team handle to the GitHub team slug
    * using a normalized exact match; case is ignored and spaces are removed. No modifications are made

services/teams/src/v2/TeamsApi.ts

@@ -146,6 +146,11 @@ export { TeamSyncBulkType } from "./models/TeamSyncBulkType";
 export { TeamSyncData } from "./models/TeamSyncData";
 export { TeamSyncRequest } from "./models/TeamSyncRequest";
 export { TeamSyncResponse } from "./models/TeamSyncResponse";
+export { TeamSyncSelectionStateExternalId } from "./models/TeamSyncSelectionStateExternalId";
+export { TeamSyncSelectionStateExternalIdType } from "./models/TeamSyncSelectionStateExternalIdType";
+export { TeamSyncSelectionStateItem } from "./models/TeamSyncSelectionStateItem";
+export { TeamSyncSelectionStateOperation } from "./models/TeamSyncSelectionStateOperation";
+export { TeamSyncSelectionStateScope } from "./models/TeamSyncSelectionStateScope";
 export { TeamType } from "./models/TeamType";
 export { TeamUpdate } from "./models/TeamUpdate";
 export { TeamUpdateAttributes } from "./models/TeamUpdateAttributes";