docs(FI-609): sync Signals deletion descriptions with product behavior

specification/DigitalOcean-public.v2.yaml

@@ -595,17 +595,19 @@ tags:
   - name: Signals
     description: |-
       The DigitalOcean Signals API provides observability for agent
-      conversations, such as Harness Runtime sessions and Serverless
+      conversations, such as Harness Runtime conversations and Serverless
       Inference chat completions, detecting behavioral signals such as
       user disengagement, execution failures, and satisfaction indicators.
 
       Use the consent endpoints to manage whether signals collection is
       enabled — per agent for Harness Runtime (`source=agent`) and per team
       for Serverless Inference chat completions (`source=inference`) — the
-      session endpoints to browse agent conversations and their detected
-      signals, the export endpoints to create downloadable archives of
-      signals data for offline analysis, and the deletion endpoints to
-      permanently delete signals data.
+      session endpoints to browse conversations and their detected signals,
+      the export endpoints to create downloadable archives of signals data
+      for offline analysis, and the deletion endpoints to permanently delete
+      Signals conversations for an agent or Serverless Inference
+      conversations for a whole team (aggregated Insights or metrics
+      summaries may still remain).
 
   - name: Sizes
     description: |-

specification/resources/signals/models/create_deletion_request.yml

@@ -4,9 +4,10 @@ properties:
   type:
     type: string
     description: >-
-      The scope of the deletion. `agent` deletes data for one agent and
-      requires `agent_id`. `inference` deletes data for the team's Serverless
-      Inference requests.
+      The scope of the deletion. `agent` deletes Signals conversations for one
+      Harness Runtime agent and requires `agent_id`. `inference` deletes
+      Serverless Inference Signals conversations for the whole team
+      (team-wide; omit `agent_id`).
     enum:
       - agent
       - inference
@@ -20,9 +21,10 @@ properties:
     type: string
     format: uuid
     description: >-
-      The agent whose data should be deleted. For Harness Runtime, this is the
-      Environment Config ID. Required when `type` is `agent`; must be omitted
-      when `type` is `inference`.
+      The Harness Runtime Environment Config ID of the agent whose
+      conversations should be deleted. This is the agent UUID (`agent_id`).
+      Required when `type` is `agent`; must be omitted when `type` is
+      `inference`.
     example: 01a10d3f-2c09-764f-99f8-458e521627f3
 required:
   - type

specification/resources/signals/models/deletion_job.yml

@@ -1,5 +1,8 @@
 type: object
-description: A deletion job that permanently removes signals data for an agent or for a team's Serverless Inference usage.
+description: >-
+  A deletion job that permanently removes Signals conversations for one
+  Harness Runtime agent, or Serverless Inference Signals conversations for a
+  whole team. Aggregated Insights or metrics summaries may still remain.
 properties:
   team_id:
     type: integer
@@ -13,8 +16,9 @@ properties:
   type:
     type: string
     description: >-
-      The scope of the deletion. `agent` deletes data for one agent.
-      `inference` deletes data for the team's Serverless Inference requests.
+      The scope of the deletion. `agent` deletes Signals conversations for one
+      Harness Runtime agent. `inference` deletes Serverless Inference Signals
+      conversations for the whole team.
     enum:
       - agent
       - inference
@@ -23,8 +27,8 @@ properties:
     type: string
     format: uuid
     description: >-
-      The agent whose data is being deleted. For Harness Runtime, this is the
-      Environment Config ID. Only present for `agent` deletions.
+      The Harness Runtime Environment Config ID (agent UUID) whose
+      conversations are being deleted. Only present for `agent` deletions.
     example: 01a10d3f-2c09-764f-99f8-458e521627f3
   status:
     type: string

specification/resources/signals/signals_create_deletion.yml

@@ -3,24 +3,34 @@ operationId: signals_create_deletion
 summary: Create a Data Deletion Job
 
 description: |
-  To permanently delete signals data, send a POST request to
-  `/v1/signals/deletions`.
+  To permanently delete Signals conversation data, send a POST request to
+  `/v1/signals/deletions`. Deletion cannot be undone.
 
   Two deletion types are supported:
 
-  - `agent` — deletes sessions, dialogues, and signal reports for one agent.
-    Requires `agent_id`. The agent's data is hidden immediately and signals
-    collection is disabled for the agent, even if the job later fails. Wait
-    until the job is complete before enabling signals for the agent again.
-  - `inference` — deletes sessions, dialogues, and signal reports for the
-    team's Serverless Inference requests made before the deletion. Signals
-    continues to analyze new requests.
-
-  Deletion is permanent and cannot be undone. The job runs asynchronously;
-  poll the get endpoint to check status. To retry a failed job, send the same
-  request again. Export files created earlier are not deleted and remain
+  - `agent` — deletes Signals conversations for one Harness Runtime agent and
+    turns off collection for that agent. Requires `agent_id`, which is the
+    agent's Environment Config ID (the agent UUID). On create, matching
+    conversations are hidden from Signals reads immediately. Wait until the
+    job is `complete` before enabling Signals for the agent again.
+  - `inference` — deletes Serverless Inference Signals conversations for your
+    whole team (team-wide; not limited to one endpoint or model) that were
+    collected at or before the deletion request, and turns off team inference
+    collection (`source=inference`). Do not send `agent_id`. On create,
+    matching conversations are hidden from Signals reads immediately.
+
+  The job runs asynchronously; poll the get endpoint until `status` is
+  `complete` or `failed`. DigitalOcean may retry transient processing errors
+  while a job is still active. If a job ends as `failed`, matching
+  conversations stay hidden and collection stays off; send the same create
+  request again to retry. Earlier export files are not deleted and remain
   available until they expire.
 
+  Note: Deletion removes Signals conversation data for the requested scope.
+  Aggregated Insights or metrics charts may still show historical summary
+  datapoints after deletion. Those summaries are not the same as recoverable
+  conversation content.
+
   The endpoint is idempotent: if a queued or running job already exists for
   the same target, it is returned with `200 OK`. A new job returns
   `202 Accepted`. Each team can have a limited number of active jobs;