Added new optional field definition to include more detail in findings for '/api/v2/posture_management/findings' (#2863)

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

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

.apigentools-info

@@ -4,13 +4,13 @@
     "spec_versions": {
         "v1": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:21.660332",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:40.720994",
+            "spec_repo_commit": "faa72400"
         },
         "v2": {
             "apigentools_version": "1.6.6",
-            "regenerated": "2025-06-05 08:11:21.677480",
-            "spec_repo_commit": "0e7259ca"
+            "regenerated": "2025-06-05 09:49:40.742309",
+            "spec_repo_commit": "faa72400"
         }
     }
 }

.generator/schemas/v2/openapi.yaml

@@ -15279,10 +15279,16 @@ components:
     FindingAttributes:
       description: The JSON:API attributes of the finding.
       properties:
+        datadog_link:
+          $ref: '#/components/schemas/FindingDatadogLink'
+        description:
+          $ref: '#/components/schemas/FindingDescription'
         evaluation:
           $ref: '#/components/schemas/FindingEvaluation'
         evaluation_changed_at:
           $ref: '#/components/schemas/FindingEvaluationChangedAt'
+        external_id:
+          $ref: '#/components/schemas/FindingExternalId'
         mute:
           $ref: '#/components/schemas/FindingMute'
         resource:
@@ -15300,6 +15306,22 @@ components:
         vulnerability_type:
           $ref: '#/components/schemas/FindingVulnerabilityType'
       type: object
+    FindingDatadogLink:
+      description: The Datadog relative link for this finding.
+      example: /security/compliance?panels=cpfinding%7Cevent%7CruleId%3Adef-000-u5t%7CresourceId%3Ae8c9ab7c52ebd7bf2fdb4db641082d7d%7CtabId%3Aoverview
+      type: string
+    FindingDescription:
+      description: The description and remediation steps for this finding.
+      example: '## Remediation
+
+
+        1. In the console, go to **Storage Account**.
+
+        2. For each Storage Account, navigate to **Data Protection**.
+
+        3. Select **Set soft delete enabled** and enter the number of days to retain
+        soft deleted data.'
+      type: string
     FindingEvaluation:
       description: The evaluation of the finding.
       enum:
@@ -15317,6 +15339,10 @@ components:
       format: int64
       minimum: 1
       type: integer
+    FindingExternalId:
+      description: The cloud-based ID for the resource related to the finding.
+      example: arn:aws:s3:::my-example-bucket
+      type: string
     FindingID:
       description: The unique ID for this finding.
       example: ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==
@@ -53082,13 +53108,19 @@ paths:
         the equal sign: `filter[evaluation_changed_at]=>=1678809373257`.\n\nQuery
         parameters must be only among the documented ones and with values of correct
         types. Duplicated query parameters (e.g. `filter[status]=low&filter[status]=info`)
-        are not allowed.\n\n### Response\n\nThe response includes an array of finding
-        objects, pagination metadata, and a count of items that match the query.\n\nEach
-        finding object contains the following:\n\n- The finding ID that can be used
-        in a `GetFinding` request to retrieve the full finding details.\n- Core attributes,
-        including status, evaluation, high-level resource details, muted state, and
-        rule details.\n- `evaluation_changed_at` and `resource_discovery_date` time
-        stamps.\n- An array of associated tags.\n"
+        are not allowed.\n\n### Additional extension fields\n\nAdditional extension
+        fields are available for some findings.\n\nThe data is available when you
+        include the query parameter `?detailed_findings=true` in the request.\n\nThe
+        following fields are available for findings:\n- `external_id`: The resource
+        external ID related to the finding.\n- `description`: The description and
+        remediation steps for the finding.\n- `datadog_link`: The Datadog relative
+        link for the finding.\n\n### Response\n\nThe response includes an array of
+        finding objects, pagination metadata, and a count of items that match the
+        query.\n\nEach finding object contains the following:\n\n- The finding ID
+        that can be used in a `GetFinding` request to retrieve the full finding details.\n-
+        Core attributes, including status, evaluation, high-level resource details,
+        muted state, and rule details.\n- `evaluation_changed_at` and `resource_discovery_date`
+        time stamps.\n- An array of associated tags.\n"
       operationId: ListFindings
       parameters:
       - description: Limit the number of findings returned. Must be <= 1000.
@@ -53191,6 +53223,14 @@ paths:
           items:
             $ref: '#/components/schemas/FindingVulnerabilityType'
           type: array
+      - description: Return additional fields for some findings.
+        example:
+        - true
+        in: query
+        name: detailed_findings
+        required: false
+        schema:
+          type: boolean
       responses:
         '200':
           content:

examples/v2/security-monitoring/ListFindings_2932019633.java

@@ -0,0 +1,27 @@
+// List findings returns "OK" response with details
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.SecurityMonitoringApi;
+import com.datadog.api.client.v2.api.SecurityMonitoringApi.ListFindingsOptionalParameters;
+import com.datadog.api.client.v2.model.ListFindingsResponse;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.listFindings", true);
+    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);
+
+    try {
+      ListFindingsResponse result =
+          apiInstance.listFindings(new ListFindingsOptionalParameters().detailedFindings(true));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling SecurityMonitoringApi#listFindings");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/v2/api/SecurityMonitoringApi.java

@@ -5344,6 +5344,7 @@ public static class ListFindingsOptionalParameters {
     private FindingEvaluation filterEvaluation;
     private FindingStatus filterStatus;
     private List<FindingVulnerabilityType> filterVulnerabilityType;
+    private Boolean detailedFindings;
 
     /**
      * Set pageLimit.
@@ -5497,6 +5498,17 @@ public ListFindingsOptionalParameters filterVulnerabilityType(
       this.filterVulnerabilityType = filterVulnerabilityType;
       return this;
     }
+
+    /**
+     * Set detailedFindings.
+     *
+     * @param detailedFindings Return additional fields for some findings. (optional)
+     * @return ListFindingsOptionalParameters
+     */
+    public ListFindingsOptionalParameters detailedFindings(Boolean detailedFindings) {
+      this.detailedFindings = detailedFindings;
+      return this;
+    }
   }
 
   /**
@@ -5647,6 +5659,17 @@ public PaginationIterable<Finding> listFindingsWithPagination(
    * Duplicated query parameters (e.g. <code>filter[status]=low&amp;filter[status]=info</code>) are
    * not allowed.
    *
+   * <h3>Additional extension fields</h3>
+   *
+   * <p>Additional extension fields are available for some findings.
+   *
+   * <p>The data is available when you include the query parameter <code>?detailed_findings=true
+   * </code> in the request.
+   *
+   * <p>The following fields are available for findings: - <code>external_id</code>: The resource
+   * external ID related to the finding. - <code>description</code>: The description and remediation
+   * steps for the finding. - <code>datadog_link</code>: The Datadog relative link for the finding.
+   *
    * <h3>Response</h3>
    *
    * <p>The response includes an array of finding objects, pagination metadata, and a count of items
@@ -5700,6 +5723,7 @@ public ApiResponse<ListFindingsResponse> listFindingsWithHttpInfo(
     FindingEvaluation filterEvaluation = parameters.filterEvaluation;
     FindingStatus filterStatus = parameters.filterStatus;
     List<FindingVulnerabilityType> filterVulnerabilityType = parameters.filterVulnerabilityType;
+    Boolean detailedFindings = parameters.detailedFindings;
     // create path and map variables
     String localVarPath = "/api/v2/posture_management/findings";
 
@@ -5725,6 +5749,8 @@ public ApiResponse<ListFindingsResponse> listFindingsWithHttpInfo(
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[status]", filterStatus));
     localVarQueryParams.addAll(
         apiClient.parameterToPairs("multi", "filter[vulnerability_type]", filterVulnerabilityType));
+    localVarQueryParams.addAll(
+        apiClient.parameterToPairs("", "detailed_findings", detailedFindings));
 
     Invocation.Builder builder =
         apiClient.createBuilder(
@@ -5780,6 +5806,7 @@ public CompletableFuture<ApiResponse<ListFindingsResponse>> listFindingsWithHttp
     FindingEvaluation filterEvaluation = parameters.filterEvaluation;
     FindingStatus filterStatus = parameters.filterStatus;
     List<FindingVulnerabilityType> filterVulnerabilityType = parameters.filterVulnerabilityType;
+    Boolean detailedFindings = parameters.detailedFindings;
     // create path and map variables
     String localVarPath = "/api/v2/posture_management/findings";
 
@@ -5805,6 +5832,8 @@ public CompletableFuture<ApiResponse<ListFindingsResponse>> listFindingsWithHttp
     localVarQueryParams.addAll(apiClient.parameterToPairs("", "filter[status]", filterStatus));
     localVarQueryParams.addAll(
         apiClient.parameterToPairs("multi", "filter[vulnerability_type]", filterVulnerabilityType));
+    localVarQueryParams.addAll(
+        apiClient.parameterToPairs("", "detailed_findings", detailedFindings));
 
     Invocation.Builder builder;
     try {

src/main/java/com/datadog/api/client/v2/model/FindingAttributes.java

@@ -20,8 +20,11 @@
 
 /** The JSON:API attributes of the finding. */
 @JsonPropertyOrder({
+  FindingAttributes.JSON_PROPERTY_DATADOG_LINK,
+  FindingAttributes.JSON_PROPERTY_DESCRIPTION,
   FindingAttributes.JSON_PROPERTY_EVALUATION,
   FindingAttributes.JSON_PROPERTY_EVALUATION_CHANGED_AT,
+  FindingAttributes.JSON_PROPERTY_EXTERNAL_ID,
   FindingAttributes.JSON_PROPERTY_MUTE,
   FindingAttributes.JSON_PROPERTY_RESOURCE,
   FindingAttributes.JSON_PROPERTY_RESOURCE_DISCOVERY_DATE,
@@ -35,12 +38,21 @@
     value = "https://github.com/DataDog/datadog-api-client-java/blob/master/.generator")
 public class FindingAttributes {
   @JsonIgnore public boolean unparsed = false;
+  public static final String JSON_PROPERTY_DATADOG_LINK = "datadog_link";
+  private String datadogLink;
+
+  public static final String JSON_PROPERTY_DESCRIPTION = "description";
+  private String description;
+
   public static final String JSON_PROPERTY_EVALUATION = "evaluation";
   private FindingEvaluation evaluation;
 
   public static final String JSON_PROPERTY_EVALUATION_CHANGED_AT = "evaluation_changed_at";
   private Long evaluationChangedAt;
 
+  public static final String JSON_PROPERTY_EXTERNAL_ID = "external_id";
+  private String externalId;
+
   public static final String JSON_PROPERTY_MUTE = "mute";
   private FindingMute mute;
 
@@ -65,6 +77,48 @@ public class FindingAttributes {
   public static final String JSON_PROPERTY_VULNERABILITY_TYPE = "vulnerability_type";
   private FindingVulnerabilityType vulnerabilityType;
 
+  public FindingAttributes datadogLink(String datadogLink) {
+    this.datadogLink = datadogLink;
+    return this;
+  }
+
+  /**
+   * The Datadog relative link for this finding.
+   *
+   * @return datadogLink
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_DATADOG_LINK)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public String getDatadogLink() {
+    return datadogLink;
+  }
+
+  public void setDatadogLink(String datadogLink) {
+    this.datadogLink = datadogLink;
+  }
+
+  public FindingAttributes description(String description) {
+    this.description = description;
+    return this;
+  }
+
+  /**
+   * The description and remediation steps for this finding.
+   *
+   * @return description
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_DESCRIPTION)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public String getDescription() {
+    return description;
+  }
+
+  public void setDescription(String description) {
+    this.description = description;
+  }
+
   public FindingAttributes evaluation(FindingEvaluation evaluation) {
     this.evaluation = evaluation;
     this.unparsed |= !evaluation.isValid();
@@ -111,6 +165,27 @@ public void setEvaluationChangedAt(Long evaluationChangedAt) {
     this.evaluationChangedAt = evaluationChangedAt;
   }
 
+  public FindingAttributes externalId(String externalId) {
+    this.externalId = externalId;
+    return this;
+  }
+
+  /**
+   * The cloud-based ID for the resource related to the finding.
+   *
+   * @return externalId
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_EXTERNAL_ID)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public String getExternalId() {
+    return externalId;
+  }
+
+  public void setExternalId(String externalId) {
+    this.externalId = externalId;
+  }
+
   public FindingAttributes mute(FindingMute mute) {
     this.mute = mute;
     this.unparsed |= mute.unparsed;
@@ -353,8 +428,11 @@ public boolean equals(Object o) {
       return false;
     }
     FindingAttributes findingAttributes = (FindingAttributes) o;
-    return Objects.equals(this.evaluation, findingAttributes.evaluation)
+    return Objects.equals(this.datadogLink, findingAttributes.datadogLink)
+        && Objects.equals(this.description, findingAttributes.description)
+        && Objects.equals(this.evaluation, findingAttributes.evaluation)
         && Objects.equals(this.evaluationChangedAt, findingAttributes.evaluationChangedAt)
+        && Objects.equals(this.externalId, findingAttributes.externalId)
         && Objects.equals(this.mute, findingAttributes.mute)
         && Objects.equals(this.resource, findingAttributes.resource)
         && Objects.equals(this.resourceDiscoveryDate, findingAttributes.resourceDiscoveryDate)
@@ -369,8 +447,11 @@ public boolean equals(Object o) {
   @Override
   public int hashCode() {
     return Objects.hash(
+        datadogLink,
+        description,
         evaluation,
         evaluationChangedAt,
+        externalId,
         mute,
         resource,
         resourceDiscoveryDate,
@@ -386,10 +467,13 @@ public int hashCode() {
   public String toString() {
     StringBuilder sb = new StringBuilder();
     sb.append("class FindingAttributes {\n");
+    sb.append("    datadogLink: ").append(toIndentedString(datadogLink)).append("\n");
+    sb.append("    description: ").append(toIndentedString(description)).append("\n");
     sb.append("    evaluation: ").append(toIndentedString(evaluation)).append("\n");
     sb.append("    evaluationChangedAt: ")
         .append(toIndentedString(evaluationChangedAt))
         .append("\n");
+    sb.append("    externalId: ").append(toIndentedString(externalId)).append("\n");
     sb.append("    mute: ").append(toIndentedString(mute)).append("\n");
     sb.append("    resource: ").append(toIndentedString(resource)).append("\n");
     sb.append("    resourceDiscoveryDate: ")

src/test/resources/cassettes/features/v2/List_findings_returns_OK_response_with_details.freeze

@@ -0,0 +1 @@
+2025-05-20T12:11:24.321Z