Add OpenAPI spec for POST /api/v2/snapshot

.generator/schemas/v2/openapi.yaml

@@ -24622,6 +24622,184 @@ components:
         - findings
         - project
       type: object
+    CreateSnapshotAdditionalConfig:
+      description: Additional configuration options for snapshot creation.
+      properties:
+        template_variables:
+          $ref: "#/components/schemas/CreateSnapshotTemplateVariables"
+        timeseries_legend_type:
+          $ref: "#/components/schemas/CreateSnapshotTimeseriesLegendType"
+        timezone_offset_minutes:
+          description: Timezone offset in minutes from UTC. Positive values are west of UTC (for example, `300` for UTC-5). Use `0` for UTC.
+          example: 300
+          format: int64
+          type: integer
+      type: object
+    CreateSnapshotDataAttributesRequest:
+      description: Attributes for snapshot creation.
+      properties:
+        additional_config:
+          $ref: "#/components/schemas/CreateSnapshotAdditionalConfig"
+        end:
+          description: End of the time window for the snapshot, in milliseconds since Unix epoch.
+          example: 1692464800000
+          format: int64
+          type: integer
+        height:
+          description: The height of the rendered snapshot in pixels.
+          example: 185
+          format: int64
+          type: integer
+        is_authenticated:
+          description: Whether the snapshot requires authentication to view. Authenticated snapshots are scoped to the creating organization.
+          example: false
+          type: boolean
+        start:
+          description: Start of the time window for the snapshot, in milliseconds since Unix epoch.
+          example: 1692464000000
+          format: int64
+          type: integer
+        ttl:
+          $ref: "#/components/schemas/CreateSnapshotTTL"
+        widget_definition:
+          additionalProperties: {}
+          description: The widget definition to render as a snapshot. Must include a valid `type` field and non-empty `requests` array.
+          example:
+            requests:
+              - q: "avg:system.cpu.user{*}"
+            type: timeseries
+          type: object
+        width:
+          description: The width of the rendered snapshot in pixels.
+          example: 300
+          format: int64
+          type: integer
+      required:
+        - widget_definition
+        - start
+        - end
+      type: object
+    CreateSnapshotDataAttributesResponse:
+      description: Attributes of the created snapshot.
+      properties:
+        url:
+          description: The URL to access the rendered snapshot image.
+          example: https://app.datadoghq.com/api/v2/snapshot/view/public/60d/00000000-0000-0000-0000-000000000000/1692464400000-12345678-1234-5678-9abc-def123456789.png
+          type: string
+      required:
+        - url
+      type: object
+    CreateSnapshotDataRequest:
+      description: Data envelope for snapshot creation.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/CreateSnapshotDataAttributesRequest"
+        type:
+          $ref: "#/components/schemas/CreateSnapshotType"
+      required:
+        - type
+        - attributes
+      type: object
+    CreateSnapshotDataResponse:
+      description: Data envelope for the snapshot creation response.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/CreateSnapshotDataAttributesResponse"
+        id:
+          description: The unique identifier of the created snapshot.
+          example: 12345678-1234-5678-9abc-def123456789
+          type: string
+        type:
+          $ref: "#/components/schemas/CreateSnapshotType"
+      required:
+        - id
+        - type
+        - attributes
+      type: object
+    CreateSnapshotRequest:
+      description: Request body for creating a graph snapshot.
+      properties:
+        data:
+          $ref: "#/components/schemas/CreateSnapshotDataRequest"
+      required:
+        - data
+      type: object
+    CreateSnapshotResponse:
+      description: Response body for a snapshot creation request.
+      properties:
+        data:
+          $ref: "#/components/schemas/CreateSnapshotDataResponse"
+      required:
+        - data
+      type: object
+    CreateSnapshotTTL:
+      description: The time-to-live for the snapshot. This value corresponds to storage lifecycle policies that automatically delete the snapshot after the specified period.
+      enum:
+        - 30d
+        - 60d
+        - 90d
+        - 1y
+        - 2y
+        - inf
+      example: 60d
+      type: string
+      x-enum-varnames:
+        - THIRTY_DAYS
+        - SIXTY_DAYS
+        - NINETY_DAYS
+        - ONE_YEAR
+        - TWO_YEARS
+        - INFINITE
+    CreateSnapshotTemplateVariable:
+      description: A template variable definition for snapshot rendering.
+      properties:
+        name:
+          description: The template variable name.
+          example: host
+          type: string
+        prefix:
+          description: The tag prefix associated with the template variable. For example, a prefix of `host` with a value of `web-server-1` scopes the snapshot to `host:web-server-1`.
+          example: host
+          type: string
+        values:
+          description: The list of scoped values for this template variable.
+          example:
+            - web-server-1
+            - web-server-2
+          items:
+            description: A single scoped value for the template variable.
+            type: string
+          type: array
+      required:
+        - name
+        - prefix
+        - values
+      type: object
+    CreateSnapshotTemplateVariables:
+      description: List of template variable definitions for snapshot rendering.
+      items:
+        $ref: "#/components/schemas/CreateSnapshotTemplateVariable"
+      type: array
+    CreateSnapshotTimeseriesLegendType:
+      description: The legend display type for timeseries widgets. A value of `none` hides the legend entirely; omitting the field lets the frontend choose automatically.
+      enum:
+        - compact
+        - expanded
+        - none
+      example: expanded
+      type: string
+      x-enum-varnames:
+        - COMPACT
+        - EXPANDED
+        - NONE
+    CreateSnapshotType:
+      description: The type identifier for snapshot creation resources.
+      enum:
+        - create_snapshot
+      example: create_snapshot
+      type: string
+      x-enum-varnames:
+        - CREATE_SNAPSHOT
     CreateStatusPageRequest:
       description: Request object for creating a status page.
       example:
@@ -182746,6 +182924,63 @@ paths:
       x-unstable: |-
         **Note**: This endpoint is in public beta and it's subject to change.
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
+  /api/v2/snapshot:
+    post:
+      description: Create a snapshot of a graph widget. The snapshot is rendered asynchronously; the returned URL can be polled until the image is ready.
+      operationId: CreateSnapshot
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateSnapshotRequest"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                default:
+                  value:
+                    data:
+                      attributes:
+                        url: https://app.datadoghq.com/api/v2/snapshot/view/public/60d/00000000-0000-0000-0000-000000000000/1692464400000-12345678-1234-5678-9abc-def123456789.png
+                      id: 12345678-1234-5678-9abc-def123456789
+                      type: create_snapshot
+              schema:
+                $ref: "#/components/schemas/CreateSnapshotResponse"
+          description: OK
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Bad Request
+        "401":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Unauthorized
+        "403":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Forbidden
+        "404":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Not Found
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      summary: Create a graph snapshot
+      tags:
+        - Reporting and Sharing
+      x-unstable: |-
+        **Note**: This endpoint is in preview and is subject to change.
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/sourcemaps:
     delete:
       description: |-
@@ -197019,6 +197254,9 @@ tags:
       dashboard on a recurring cadence and delivers it to a set of recipients over email, Slack,
       or Microsoft Teams.
     name: Report Schedules
+  - description: |-
+      The Reporting and Sharing endpoints allow you to create snapshots of graph widgets and other shareable resources.
+    name: Reporting and Sharing
   - description: |-
       A restriction policy defines the access control rules for a resource, mapping a set of relations
       (such as editor and viewer) to a set of allowed principals (such as roles, teams, or users).

examples/v2/reporting-and-sharing/CreateSnapshot.java

@@ -0,0 +1,66 @@
+// Create a graph snapshot returns "OK" response
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.ReportingandSharingApi;
+import com.datadog.api.client.v2.model.CreateSnapshotAdditionalConfig;
+import com.datadog.api.client.v2.model.CreateSnapshotDataAttributesRequest;
+import com.datadog.api.client.v2.model.CreateSnapshotDataRequest;
+import com.datadog.api.client.v2.model.CreateSnapshotRequest;
+import com.datadog.api.client.v2.model.CreateSnapshotResponse;
+import com.datadog.api.client.v2.model.CreateSnapshotTTL;
+import com.datadog.api.client.v2.model.CreateSnapshotTemplateVariable;
+import com.datadog.api.client.v2.model.CreateSnapshotTimeseriesLegendType;
+import com.datadog.api.client.v2.model.CreateSnapshotType;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.Map;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.createSnapshot", true);
+    ReportingandSharingApi apiInstance = new ReportingandSharingApi(defaultClient);
+
+    CreateSnapshotRequest body =
+        new CreateSnapshotRequest()
+            .data(
+                new CreateSnapshotDataRequest()
+                    .attributes(
+                        new CreateSnapshotDataAttributesRequest()
+                            .additionalConfig(
+                                new CreateSnapshotAdditionalConfig()
+                                    .templateVariables(
+                                        Collections.singletonList(
+                                            new CreateSnapshotTemplateVariable()
+                                                .name("host")
+                                                .prefix("host")
+                                                .values(
+                                                    Arrays.asList("web-server-1", "web-server-2"))))
+                                    .timeseriesLegendType(
+                                        CreateSnapshotTimeseriesLegendType.EXPANDED)
+                                    .timezoneOffsetMinutes(300L))
+                            .end(1692464800000L)
+                            .height(185L)
+                            .isAuthenticated(false)
+                            .start(1692464000000L)
+                            .ttl(CreateSnapshotTTL.SIXTY_DAYS)
+                            .widgetDefinition(
+                                Map.ofEntries(
+                                    Map.entry("requests", "[{'q': 'avg:system.cpu.user{*}'}]"),
+                                    Map.entry("type", "timeseries")))
+                            .width(300L))
+                    .type(CreateSnapshotType.CREATE_SNAPSHOT));
+
+    try {
+      CreateSnapshotResponse result = apiInstance.createSnapshot(body);
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling ReportingandSharingApi#createSnapshot");
+      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/ApiClient.java

@@ -1242,6 +1242,7 @@ public class ApiClient {
           put("v2.getSLOReport", false);
           put("v2.getSLOReportJobStatus", false);
           put("v2.getSloStatus", false);
+          put("v2.createSnapshot", false);
           put("v2.getSPARecommendations", false);
           put("v2.getSPARecommendationsWithShard", false);
           put("v2.createAiCustomRule", false);