From c1495f7af32272abd312c68ab07f9c831f773f15 Mon Sep 17 00:00:00 2001 From: aupadhyay-shark Date: Sun, 11 Oct 2026 21:41:02 +0530 Subject: [PATCH 1/3] docs(FI-609): sync Signals deletion descriptions with product behavior Clarify hide + collection-off on create for agent and inference (fix stale inference wording that said analysis continues), failed-job retry, and that aggregated Insights/metrics may remain. Description-only; no schema/path/status-code changes. Co-authored-by: Cursor --- specification/DigitalOcean-public.v2.yaml | 3 +- .../models/create_deletion_request.yml | 6 ++-- .../resources/signals/models/deletion_job.yml | 5 ++- .../signals/signals_create_deletion.yml | 35 ++++++++++++------- 4 files changed, 31 insertions(+), 18 deletions(-) diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index 8314298d9..9c9842de1 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/specification/DigitalOcean-public.v2.yaml @@ -605,7 +605,8 @@ tags: 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. + permanently delete session, dialogue, and related Signals event data + (aggregated Insights or metrics summaries may still remain). - name: Sizes description: |- diff --git a/specification/resources/signals/models/create_deletion_request.yml b/specification/resources/signals/models/create_deletion_request.yml index eea28cfb5..fcd43da63 100644 --- a/specification/resources/signals/models/create_deletion_request.yml +++ b/specification/resources/signals/models/create_deletion_request.yml @@ -4,9 +4,9 @@ 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 data for one Harness Runtime + agent and requires `agent_id`. `inference` deletes data for the team's + Serverless Inference usage (omit `agent_id`). enum: - agent - inference diff --git a/specification/resources/signals/models/deletion_job.yml b/specification/resources/signals/models/deletion_job.yml index e2375ade5..44c765ed8 100644 --- a/specification/resources/signals/models/deletion_job.yml +++ b/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 session, dialogue, and + related event data for one Harness Runtime agent or for a team's Serverless + Inference usage. Aggregated Insights or metrics summaries may still remain. properties: team_id: type: integer diff --git a/specification/resources/signals/signals_create_deletion.yml b/specification/resources/signals/signals_create_deletion.yml index d7365e5f7..b3821577c 100644 --- a/specification/resources/signals/signals_create_deletion.yml +++ b/specification/resources/signals/signals_create_deletion.yml @@ -3,23 +3,32 @@ 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 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. + - `agent` — deletes sessions, dialogues, and signal reports for one Harness + Runtime agent. Requires `agent_id`. On create, that agent's data is hidden + from Signals reads immediately and Signals collection is disabled for the + agent. 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 - available until they expire. + team's Serverless Inference requests made at or before the deletion + watermark. On create, in-scope inference data is hidden from Signals reads + immediately and team inference collection (`source=inference`) is disabled. + + 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`, in-scope data stays + hidden and collection stays off; send the same create request again to retry. + Export files created earlier are not deleted and remain available until they + expire. + + Note: Deletion removes session, dialogue, and related Signals event data for + the requested scope. Aggregated Insights or metrics charts may still show + historical summary datapoints after deletion; those aggregates are not the + same as recoverable session or dialogue 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 From 3034befa63e137ca5a11226b9ef09450554cc1e1 Mon Sep 17 00:00:00 2001 From: aupadhyay-shark Date: Sun, 11 Oct 2026 21:44:24 +0530 Subject: [PATCH 2/3] docs(FI-609): prefer conversations; clarify team-wide inference and env id Use conversations wording, state inference deletion is team-wide, and document agent_id as the Harness Runtime Environment Config ID. Co-authored-by: Cursor --- specification/DigitalOcean-public.v2.yaml | 5 ++- .../models/create_deletion_request.yml | 14 ++++--- .../resources/signals/models/deletion_job.yml | 15 ++++---- .../signals/signals_create_deletion.yml | 37 ++++++++++--------- 4 files changed, 38 insertions(+), 33 deletions(-) diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index 9c9842de1..d1cac4d5f 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/specification/DigitalOcean-public.v2.yaml @@ -605,8 +605,9 @@ tags: 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 session, dialogue, and related Signals event data - (aggregated Insights or metrics summaries may still remain). + permanently delete Signals conversations for an agent or all Serverless + Inference conversations for a team (aggregated Insights or metrics + summaries may still remain). - name: Sizes description: |- diff --git a/specification/resources/signals/models/create_deletion_request.yml b/specification/resources/signals/models/create_deletion_request.yml index fcd43da63..b97c9e508 100644 --- a/specification/resources/signals/models/create_deletion_request.yml +++ b/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 Harness Runtime - agent and requires `agent_id`. `inference` deletes data for the team's - Serverless Inference usage (omit `agent_id`). + The scope of the deletion. `agent` deletes all Signals conversations for + one Harness Runtime agent and requires `agent_id`. `inference` deletes + all Serverless Inference Signals conversations for the entire team + (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 for the agent whose + conversations should be deleted. This value 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 diff --git a/specification/resources/signals/models/deletion_job.yml b/specification/resources/signals/models/deletion_job.yml index 44c765ed8..fcc0383ca 100644 --- a/specification/resources/signals/models/deletion_job.yml +++ b/specification/resources/signals/models/deletion_job.yml @@ -1,8 +1,8 @@ type: object description: >- - A deletion job that permanently removes Signals session, dialogue, and - related event data for one Harness Runtime agent or for a team's Serverless - Inference usage. Aggregated Insights or metrics summaries may still remain. + A deletion job that permanently removes Signals conversations for one + Harness Runtime agent, or all Serverless Inference Signals conversations + for a team. Aggregated Insights or metrics summaries may still remain. properties: team_id: type: integer @@ -16,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 conversations for one Harness + Runtime agent. `inference` deletes all Serverless Inference Signals + conversations for the entire team. enum: - agent - inference @@ -26,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 diff --git a/specification/resources/signals/signals_create_deletion.yml b/specification/resources/signals/signals_create_deletion.yml index b3821577c..1d3f6f18b 100644 --- a/specification/resources/signals/signals_create_deletion.yml +++ b/specification/resources/signals/signals_create_deletion.yml @@ -8,27 +8,28 @@ description: | Two deletion types are supported: - - `agent` — deletes sessions, dialogues, and signal reports for one Harness - Runtime agent. Requires `agent_id`. On create, that agent's data is hidden - from Signals reads immediately and Signals collection is disabled for the - agent. 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 at or before the deletion - watermark. On create, in-scope inference data is hidden from Signals reads - immediately and team inference collection (`source=inference`) is disabled. + - `agent` — deletes all 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, those + conversations are hidden from Signals reads immediately. Wait until the + job is `complete` before enabling Signals for the agent again. + - `inference` — deletes **all** Serverless Inference Signals conversations + for your **entire team** (team-wide; not per endpoint or model) collected + at or before the deletion watermark, and turns off team inference + collection (`source=inference`). Do not send `agent_id`. On create, those + 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`, in-scope data stays - hidden and collection stays off; send the same create request again to retry. - Export files created earlier are not deleted and remain available until they - expire. - - Note: Deletion removes session, dialogue, and related Signals event data for - the requested scope. Aggregated Insights or metrics charts may still show - historical summary datapoints after deletion; those aggregates are not the - same as recoverable session or dialogue content. + while a job is still active. If a job ends as `failed`, the conversations + stay hidden and collection stays off; send the same create request again to + retry. Export files created earlier are not deleted and remain available + until they expire. + + Note: Deletion removes the conversation data Signals collected for that + 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 From eac7af61a6e5f4bee631e07a6e50a9dff92cd23b Mon Sep 17 00:00:00 2001 From: aupadhyay-shark Date: Sun, 11 Oct 2026 21:50:58 +0530 Subject: [PATCH 3/3] docs(FI-609): tighten deletion descriptions for legal accuracy Prefer conversation-scoped wording, replace watermark jargon with at-or-before the deletion request, keep wait-before-re-enable and export retention, and align the Signals tag with conversations language. Co-authored-by: Cursor --- specification/DigitalOcean-public.v2.yaml | 12 +++---- .../models/create_deletion_request.yml | 16 ++++----- .../resources/signals/models/deletion_job.yml | 10 +++--- .../signals/signals_create_deletion.yml | 36 +++++++++---------- 4 files changed, 37 insertions(+), 37 deletions(-) diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index d1cac4d5f..dace9f4fc 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/specification/DigitalOcean-public.v2.yaml @@ -595,18 +595,18 @@ 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 conversations for an agent or all Serverless - Inference conversations for a team (aggregated Insights or metrics + 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 diff --git a/specification/resources/signals/models/create_deletion_request.yml b/specification/resources/signals/models/create_deletion_request.yml index b97c9e508..d1402af37 100644 --- a/specification/resources/signals/models/create_deletion_request.yml +++ b/specification/resources/signals/models/create_deletion_request.yml @@ -4,10 +4,10 @@ properties: type: type: string description: >- - The scope of the deletion. `agent` deletes all Signals conversations for - one Harness Runtime agent and requires `agent_id`. `inference` deletes - all Serverless Inference Signals conversations for the entire team - (omit `agent_id`). + 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 @@ -21,10 +21,10 @@ properties: type: string format: uuid description: >- - The Harness Runtime Environment Config ID for the agent whose - conversations should be deleted. This value is the agent UUID - (`agent_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 diff --git a/specification/resources/signals/models/deletion_job.yml b/specification/resources/signals/models/deletion_job.yml index fcc0383ca..cbdb90797 100644 --- a/specification/resources/signals/models/deletion_job.yml +++ b/specification/resources/signals/models/deletion_job.yml @@ -1,8 +1,8 @@ type: object description: >- A deletion job that permanently removes Signals conversations for one - Harness Runtime agent, or all Serverless Inference Signals conversations - for a team. Aggregated Insights or metrics summaries may still remain. + 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 @@ -16,9 +16,9 @@ properties: type: type: string description: >- - The scope of the deletion. `agent` deletes conversations for one Harness - Runtime agent. `inference` deletes all Serverless Inference Signals - conversations for the entire team. + 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 diff --git a/specification/resources/signals/signals_create_deletion.yml b/specification/resources/signals/signals_create_deletion.yml index 1d3f6f18b..93f652982 100644 --- a/specification/resources/signals/signals_create_deletion.yml +++ b/specification/resources/signals/signals_create_deletion.yml @@ -3,33 +3,33 @@ operationId: signals_create_deletion summary: Create a Data Deletion Job description: | - To permanently delete Signals data, send a POST request to + 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 all 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, those + - `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 **all** Serverless Inference Signals conversations - for your **entire team** (team-wide; not per endpoint or model) collected - at or before the deletion watermark, and turns off team inference - collection (`source=inference`). Do not send `agent_id`. On create, those - conversations are hidden from Signals reads immediately. + - `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`, the conversations - stay hidden and collection stays off; send the same create request again to - retry. Export files created earlier are not deleted and remain available - until they expire. - - Note: Deletion removes the conversation data Signals collected for that - scope. Aggregated Insights or metrics charts may still show historical - summary datapoints after deletion; those summaries are not the same as - recoverable conversation content. + 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