Add Product Analytics Server-Side Events API endpoint

config/_default/menus/api.en.yaml

@@ -9966,6 +9966,22 @@ menu:
           - ListProcesses
         unstable: []
         order: 1
+    - name: Product Analytics
+      url: /api/latest/product-analytics/
+      identifier: product-analytics
+      generated: true
+    - name: Send server-side events
+      url: '#send-server-side-events'
+      identifier: product-analytics-send-server-side-events
+      parent: product-analytics
+      generated: true
+      params:
+        versions:
+          - v2
+        operationids:
+          - SubmitProductAnalyticsEvent
+        unstable: []
+        order: 1
     - name: RUM
       url: /api/latest/rum/
       identifier: rum

content/en/api/latest/product-analytics/_index.md

@@ -0,0 +1,3 @@
+---
+title: Product Analytics
+---

content/en/api/v2/product-analytics/_index.md

@@ -0,0 +1,4 @@
+---
+title: Product Analytics
+headless: true
+---

data/api/v2/full_spec.yaml

@@ -41471,6 +41471,114 @@ components:
       type: string
       x-enum-varnames:
       - PROCESS
+    ProductAnalyticsServerSideEventError:
+      description: Error details.
+      properties:
+        detail:
+          description: Error message.
+          example: Malformed payload
+          type: string
+        status:
+          description: Error code.
+          example: '400'
+          type: string
+        title:
+          description: Error title.
+          example: Bad Request
+          type: string
+      type: object
+    ProductAnalyticsServerSideEventErrors:
+      description: Error response.
+      properties:
+        errors:
+          description: Structured errors.
+          items:
+            $ref: '#/components/schemas/ProductAnalyticsServerSideEventError'
+          type: array
+      type: object
+    ProductAnalyticsServerSideEventItem:
+      description: A Product Analytics server-side event.
+      properties:
+        account:
+          $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemAccount'
+        application:
+          $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemApplication'
+        event:
+          $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemEvent'
+        session:
+          $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemSession'
+        type:
+          $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemType'
+        usr:
+          $ref: '#/components/schemas/ProductAnalyticsServerSideEventItemUsr'
+      required:
+      - application
+      - event
+      - type
+      type: object
+    ProductAnalyticsServerSideEventItemAccount:
+      description: The account linked to your event.
+      properties:
+        id:
+          description: The account ID used in Datadog.
+          example: account-67890
+          type: string
+      required:
+      - id
+      type: object
+    ProductAnalyticsServerSideEventItemApplication:
+      description: The application in which you want to send your events.
+      properties:
+        id:
+          description: 'The application ID of your application. It can be found in
+            your
+
+            [application management page](https://app.datadoghq.com/rum/list).'
+          example: 123abcde-123a-123b-1234-123456789abc
+          type: string
+      required:
+      - id
+      type: object
+    ProductAnalyticsServerSideEventItemEvent:
+      description: Fields used for the event.
+      properties:
+        name:
+          description: The name of your event, which is used for search in the same
+            way as view or action names.
+          example: payment.processed
+          type: string
+      required:
+      - name
+      type: object
+    ProductAnalyticsServerSideEventItemSession:
+      description: The session linked to your event.
+      properties:
+        id:
+          description: The session ID captured by the SDK.
+          example: session-abcdef
+          type: string
+      required:
+      - id
+      type: object
+    ProductAnalyticsServerSideEventItemType:
+      description: The type of Product Analytics event. Must be `server` for server-side
+        events.
+      enum:
+      - server
+      example: server
+      type: string
+      x-enum-varnames:
+      - SERVER
+    ProductAnalyticsServerSideEventItemUsr:
+      description: The user linked to your event.
+      properties:
+        id:
+          description: The user ID used in Datadog.
+          example: user-12345
+          type: string
+      required:
+      - id
+      type: object
     Project:
       description: A Project
       properties:
@@ -78514,6 +78622,219 @@ paths:
       x-permission:
         operator: OPEN
         permissions: []
+  /api/v2/prodlytics:
+    post:
+      description: 'Send server-side events to Product Analytics. Server-side events
+        are retained for 15 months.
+
+
+        Server-Side events in Product Analytics are helpful for tracking events that
+        occur on the server,
+
+        as opposed to client-side events, which are captured by Real User Monitoring
+        (RUM) SDKs.
+
+        This allows for a more comprehensive view of the user journey by including
+        actions that happen on the server.
+
+        Typical examples could be `checkout.completed` or `payment.processed`.
+
+
+        Ingested server-side events are integrated into Product Analytics to allow
+        users to select and filter
+
+        these events in the event picker, similar to how views or actions are handled.
+
+
+        **Requirements:**
+
+        - At least one of `usr`, `account`, or `session` must be provided with a valid
+        ID.
+
+        - The `application.id` must reference a Product Analytics-enabled application.
+
+
+        **Custom Attributes:**
+
+        Any additional fields in the payload are flattened and searchable as facets.
+
+        For example, a payload with `{"customer": {"tier": "premium"}}` is searchable
+        with
+
+        the syntax `@customer.tier:premium` in Datadog.
+
+
+        The status codes answered by the HTTP API are:
+
+        - 202: Accepted: The request has been accepted for processing
+
+        - 400: Bad request (likely an issue in the payload formatting)
+
+        - 401: Unauthorized (likely a missing API Key)
+
+        - 403: Permission issue (likely using an invalid API Key)
+
+        - 408: Request Timeout, request should be retried after some time
+
+        - 413: Payload too large (batch is above 5MB uncompressed)
+
+        - 429: Too Many Requests, request should be retried after some time
+
+        - 500: Internal Server Error, the server encountered an unexpected condition
+        that prevented it from fulfilling the request, request should be retried after
+        some time
+
+        - 503: Service Unavailable, the server is not ready to handle the request
+        probably because it is overloaded, request should be retried after some time'
+      operationId: SubmitProductAnalyticsEvent
+      requestBody:
+        content:
+          application/json:
+            examples:
+              event-with-account:
+                description: Send a server-side event linked to an account.
+                summary: Event with account ID
+                value:
+                  account:
+                    id: account-456
+                  application:
+                    id: 123abcde-123a-123b-1234-123456789abc
+                  event:
+                    name: checkout.completed
+                  type: server
+              event-with-custom-attributes:
+                description: Send a server-side event with additional custom attributes.
+                summary: Event with custom attributes
+                value:
+                  application:
+                    id: 123abcde-123a-123b-1234-123456789abc
+                  customer:
+                    tier: premium
+                  event:
+                    name: payment.processed
+                  type: server
+                  usr:
+                    id: '123'
+              event-with-session:
+                description: Send a server-side event linked to a session.
+                summary: Event with session ID
+                value:
+                  application:
+                    id: 123abcde-123a-123b-1234-123456789abc
+                  event:
+                    name: form.submitted
+                  session:
+                    id: session-789
+                  type: server
+              simple-event-with-user:
+                description: Send a server-side event linked to a user.
+                summary: Simple event with user ID
+                value:
+                  application:
+                    id: 123abcde-123a-123b-1234-123456789abc
+                  event:
+                    name: payment.processed
+                  type: server
+                  usr:
+                    id: '123'
+            schema:
+              $ref: '#/components/schemas/ProductAnalyticsServerSideEventItem'
+        description: Server-side event to send (JSON format).
+        required: true
+      responses:
+        '202':
+          content:
+            application/json:
+              schema:
+                type: object
+          description: Request accepted for processing (always 202 empty JSON).
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Bad Request
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Unauthorized
+        '403':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Forbidden
+        '408':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Request Timeout
+        '413':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Payload Too Large
+        '429':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Too Many Requests
+        '500':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Internal Server Error
+        '503':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ProductAnalyticsServerSideEventErrors'
+          description: Service Unavailable
+      security:
+      - apiKeyAuth: []
+      servers:
+      - url: https://{subdomain}.{site}
+        variables:
+          site:
+            default: datadoghq.com
+            description: The regional site for customers.
+            enum:
+            - datadoghq.com
+            - us3.datadoghq.com
+            - us5.datadoghq.com
+            - ap1.datadoghq.com
+            - ap2.datadoghq.com
+            - datadoghq.eu
+          subdomain:
+            default: browser-intake
+            description: The subdomain where the API is deployed.
+      - url: '{protocol}://{name}'
+        variables:
+          name:
+            default: browser-intake-datadoghq.com
+            description: Full site DNS name.
+          protocol:
+            default: https
+            description: The protocol for accessing the API.
+      - url: https://{subdomain}.{site}
+        variables:
+          site:
+            default: datadoghq.com
+            description: Any Datadog deployment.
+          subdomain:
+            default: browser-intake
+            description: The subdomain where the API is deployed.
+      summary: Send server-side events
+      tags:
+      - Product Analytics
+      x-codegen-request-body-name: body
+      x-menu-order: 1
   /api/v2/product-analytics/accounts/facet_info:
     post:
       description: Get facet information for account attributes including possible
@@ -91545,6 +91866,18 @@ tags:
     See the [Live Processes page](https://docs.datadoghq.com/infrastructure/process/)
     for more information.
   name: Processes
+- description: 'Send server-side events to Product Analytics. Server-Side Events Ingestion
+    allows you to collect custom events
+
+    from any server-side source, and retains events for 15 months. Server-side events
+    are helpful for understanding
+
+    causes of a funnel drop-off which are external to the client-side (for example,
+    payment processing error).
+
+    See the [Product Analytics page](https://docs.datadoghq.com/product_analytics/)
+    for more information.'
+  name: Product Analytics
 - description: Manage your Real User Monitoring (RUM) applications, and search or
     aggregate your RUM events over HTTP. See the [RUM & Session Replay page](https://docs.datadoghq.com/real_user_monitoring/)
     for more information

data/api/v2/translate_actions.json

@@ -2141,6 +2141,12 @@
     "description": "Get all processes for your organization.",
     "summary": "Get all processes"
   },
+  "SubmitProductAnalyticsEvent": {
+    "description": "Send server-side events to Product Analytics. Server-side events are retained for 15 months.\n\nServer-Side events in Product Analytics are helpful for tracking events that occur on the server,\nas opposed to client-side events, which are captured by Real User Monitoring (RUM) SDKs.\nThis allows for a more comprehensive view of the user journey by including actions that happen on the server.\nTypical examples could be `checkout.completed` or `payment.processed`.\n\nIngested server-side events are integrated into Product Analytics to allow users to select and filter\nthese events in the event picker, similar to how views or actions are handled.\n\n**Requirements:**\n- At least one of `usr`, `account`, or `session` must be provided with a valid ID.\n- The `application.id` must reference a Product Analytics-enabled application.\n\n**Custom Attributes:**\nAny additional fields in the payload are flattened and searchable as facets.\nFor example, a payload with `{\"customer\": {\"tier\": \"premium\"}}` is searchable with\nthe syntax `@customer.tier:premium` in Datadog.\n\nThe status codes answered by the HTTP API are:\n- 202: Accepted: The request has been accepted for processing\n- 400: Bad request (likely an issue in the payload formatting)\n- 401: Unauthorized (likely a missing API Key)\n- 403: Permission issue (likely using an invalid API Key)\n- 408: Request Timeout, request should be retried after some time\n- 413: Payload too large (batch is above 5MB uncompressed)\n- 429: Too Many Requests, request should be retried after some time\n- 500: Internal Server Error, the server encountered an unexpected condition that prevented it from fulfilling the request, request should be retried after some time\n- 503: Service Unavailable, the server is not ready to handle the request probably because it is overloaded, request should be retried after some time",
+    "summary": "Send server-side events",
+    "request_description": "Server-side event to send (JSON format).",
+    "request_schema_description": "A Product Analytics server-side event."
+  },
   "GetAccountFacetInfo": {
     "description": "Get facet information for account attributes including possible values and counts",
     "summary": "Get account facet info",