Add documentation for /api/v2/team/sync (#2611)

Co-authored-by: ci.datadog-api-spec <[email protected]>

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

.generated-info

@@ -1,4 +1,4 @@
 {
-  "spec_repo_commit": "b434599",
-  "generated": "2025-08-13 22:16:45.303"
+  "spec_repo_commit": "c38287b",
+  "generated": "2025-08-15 18:55:02.903"
 }

.generator/schemas/v2/openapi.yaml

@@ -42824,6 +42824,68 @@ components:
         urgency:
           $ref: '#/components/schemas/Urgency'
       type: object
+    TeamSyncAttributes:
+      description: Team sync attributes.
+      properties:
+        source:
+          $ref: '#/components/schemas/TeamSyncAttributesSource'
+        type:
+          $ref: '#/components/schemas/TeamSyncAttributesType'
+      required:
+      - source
+      - type
+      type: object
+    TeamSyncAttributesSource:
+      description: The external source platform for team synchronization. Only "github"
+        is supported.
+      enum:
+      - github
+      example: github
+      type: string
+      x-enum-varnames:
+      - GITHUB
+    TeamSyncAttributesType:
+      description: The type of synchronization operation. Only "link" is supported,
+        which links existing teams by matching names.
+      enum:
+      - link
+      example: link
+      type: string
+      x-enum-varnames:
+      - LINK
+    TeamSyncBulkType:
+      description: Team sync bulk type.
+      enum:
+      - team_sync_bulk
+      example: team_sync_bulk
+      type: string
+      x-enum-varnames:
+      - TEAM_SYNC_BULK
+    TeamSyncData:
+      description: Team sync data.
+      properties:
+        attributes:
+          $ref: '#/components/schemas/TeamSyncAttributes'
+        type:
+          $ref: '#/components/schemas/TeamSyncBulkType'
+      required:
+      - attributes
+      - type
+      type: object
+    TeamSyncRequest:
+      description: Team sync request.
+      example:
+        data:
+          attributes:
+            source: github
+            type: link
+          type: team_sync_bulk
+      properties:
+        data:
+          $ref: '#/components/schemas/TeamSyncData'
+      required:
+      - data
+      type: object
     TeamTarget:
       description: Represents a team target for an escalation policy step, including
         the team's ID and resource type.
@@ -65913,6 +65975,71 @@ paths:
         permissions:
         - teams_read
         - teams_manage
+  /api/v2/team/sync:
+    post:
+      description: 'This endpoint attempts to link your existing Datadog teams with
+        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.
+
+
+        [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
+
+        to teams in GitHub. This will not create new Teams in Datadog.'
+      operationId: SyncTeams
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TeamSyncRequest'
+        required: true
+      responses:
+        '200':
+          description: OK
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '429':
+          $ref: '#/components/responses/TooManyRequestsResponse'
+        '500':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/APIErrorResponse'
+          description: Internal Server Error - Unexpected error during linking.
+      security:
+      - apiKeyAuth: []
+        appKeyAuth: []
+      - AuthZ:
+        - teams_manage
+      summary: Link Teams with GitHub Teams
+      tags:
+      - Teams
+      x-codegen-request-body-name: body
+      x-permission:
+        operator: AND
+        permissions:
+        - teams_manage
+      x-unstable: '**Note**: This endpoint is in Preview. To request access, fill
+        out this [form](https://www.datadoghq.com/product-preview/github-integration-for-teams/).
+
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).'
   /api/v2/team/{super_team_id}/member_teams:
     get:
       description: Get all member teams.

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

@@ -0,0 +1 @@
+"2025-08-15T17:48:19.712Z"

cassettes/v2/Teams_3116892301/Sync-teams-returns-OK-response_3488879418/recording.har

@@ -0,0 +1,66 @@
+{
+  "log": {
+    "_recordingName": "Teams/Sync teams returns \"OK\" response",
+    "creator": {
+      "comment": "persister:fs",
+      "name": "Polly.JS",
+      "version": "6.0.5"
+    },
+    "entries": [
+      {
+        "_id": "394163072f49be157e109223981e6839",
+        "_order": 0,
+        "cache": {},
+        "request": {
+          "bodySize": 81,
+          "cookies": [],
+          "headers": [
+            {
+              "_fromType": "array",
+              "name": "accept",
+              "value": "*/*"
+            },
+            {
+              "_fromType": "array",
+              "name": "content-type",
+              "value": "application/json"
+            }
+          ],
+          "headersSize": 535,
+          "httpVersion": "HTTP/1.1",
+          "method": "POST",
+          "postData": {
+            "mimeType": "application/json",
+            "params": [],
+            "text": "{\"data\":{\"attributes\":{\"source\":\"github\",\"type\":\"link\"},\"type\":\"team_sync_bulk\"}}"
+          },
+          "queryString": [],
+          "url": "https://api.datadoghq.com/api/v2/team/sync"
+        },
+        "response": {
+          "bodySize": 0,
+          "content": {
+            "mimeType": "text/plain",
+            "size": 0
+          },
+          "cookies": [],
+          "headers": [
+            {
+              "name": "content-type",
+              "value": "text/plain"
+            }
+          ],
+          "headersSize": 653,
+          "httpVersion": "HTTP/1.1",
+          "redirectURL": "",
+          "status": 200,
+          "statusText": "OK"
+        },
+        "startedDateTime": "2025-08-15T17:48:19.717Z",
+        "time": 203
+      }
+    ],
+    "pages": [],
+    "version": "1.2"
+  }
+}

examples/v2/teams/SyncTeams.ts

@@ -0,0 +1,30 @@
+/**
+ * Link Teams with GitHub Teams returns "OK" response
+ */
+
+import { client, v2 } from "@datadog/datadog-api-client";
+
+const configuration = client.createConfiguration();
+configuration.unstableOperations["v2.syncTeams"] = true;
+const apiInstance = new v2.TeamsApi(configuration);
+
+const params: v2.TeamsApiSyncTeamsRequest = {
+  body: {
+    data: {
+      attributes: {
+        source: "github",
+        type: "link",
+      },
+      type: "team_sync_bulk",
+    },
+  },
+};
+
+apiInstance
+  .syncTeams(params)
+  .then((data: any) => {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  })
+  .catch((error: any) => console.error(error));

examples/v2/teams/SyncTeams_3215592344.ts

@@ -0,0 +1,30 @@
+/**
+ * Sync teams returns "OK" response
+ */
+
+import { client, v2 } from "@datadog/datadog-api-client";
+
+const configuration = client.createConfiguration();
+configuration.unstableOperations["v2.syncTeams"] = true;
+const apiInstance = new v2.TeamsApi(configuration);
+
+const params: v2.TeamsApiSyncTeamsRequest = {
+  body: {
+    data: {
+      attributes: {
+        source: "github",
+        type: "link",
+      },
+      type: "team_sync_bulk",
+    },
+  },
+};
+
+apiInstance
+  .syncTeams(params)
+  .then((data: any) => {
+    console.log(
+      "API called successfully. Returned data: " + JSON.stringify(data)
+    );
+  })
+  .catch((error: any) => console.error(error));

features/support/scenarios_model_mapping.ts

@@ -7555,6 +7555,13 @@ export const ScenariosModelMappings: {[key: string]: {[key: string]: any}} = {
             },
         "operationResponseType": "TeamResponse",
     },
+    "v2.SyncTeams": {
+        "body": {
+            "type": "TeamSyncRequest",
+            "format": "",
+            },
+        "operationResponseType": "void",
+    },
     "v2.ListMemberTeams": {
         "superTeamId": {
             "type": "string",