diff --git a/specification/DigitalOcean-public.v2.yaml b/specification/DigitalOcean-public.v2.yaml index 8314298d9..dace9f4fc 100644 --- a/specification/DigitalOcean-public.v2.yaml +++ b/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: |- diff --git a/specification/resources/signals/models/create_deletion_request.yml b/specification/resources/signals/models/create_deletion_request.yml index eea28cfb5..d1402af37 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 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 diff --git a/specification/resources/signals/models/deletion_job.yml b/specification/resources/signals/models/deletion_job.yml index e2375ade5..cbdb90797 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 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 diff --git a/specification/resources/signals/signals_create_deletion.yml b/specification/resources/signals/signals_create_deletion.yml index d7365e5f7..93f652982 100644 --- a/specification/resources/signals/signals_create_deletion.yml +++ b/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;