Add Signals API endpoints to OpenAPI spec (FI-610)

specification/DigitalOcean-public.v2.yaml

@@ -577,6 +577,18 @@ tags:
     description: |-
       Security CSPM endpoints for scans, scan findings, and settings.
 
+  - name: Signals
+    description: |-
+      The DigitalOcean Signals API provides observability for agent
+      conversations, such as Harness Runtime sessions 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 for each agent, the session endpoints to browse agent
+      conversations and their detected signals, and the export endpoints
+      to create downloadable archives of signals data for offline analysis.
+
   - name: Sizes
     description: |-
       The sizes objects represent different packages of hardware resources that
@@ -754,6 +766,7 @@ x-tagGroups:
       - Reserved IPv6
       - Reserved IPv6 Actions
       - Security
+      - Signals
       - Sizes
       - Snapshots
       - Spaces Keys
@@ -1827,6 +1840,44 @@ paths:
     post:
       $ref: "resources/insights/insights_post_logsSearch.yml"
 
+  /v1/consent:
+    get:
+      $ref: "resources/signals/signals_list_consents.yml"
+
+  /v1/consent/{agent_id}:
+    get:
+      $ref: "resources/signals/signals_get_consent.yml"
+
+    put:
+      $ref: "resources/signals/signals_update_consent.yml"
+
+  /v1/signals/agents/{agent_id}/sessions:
+    get:
+      $ref: "resources/signals/signals_list_sessions.yml"
+
+  /v1/signals/sessions/{session_id}/dialogues:
+    get:
+      $ref: "resources/signals/signals_list_dialogues.yml"
+
+  /v1/signals/exports:
+    get:
+      $ref: "resources/signals/signals_list_exports.yml"
+
+    post:
+      $ref: "resources/signals/signals_create_export.yml"
+
+  /v1/signals/exports/options:
+    get:
+      $ref: "resources/signals/signals_get_export_options.yml"
+
+  /v1/signals/exports/{export_id}:
+    get:
+      $ref: "resources/signals/signals_get_export.yml"
+
+  /v1/signals/exports/{export_id}/download:
+    get:
+      $ref: "resources/signals/signals_get_export_download.yml"
+
   /v2/kubernetes/clusters:
     get:
       $ref: "resources/kubernetes/kubernetes_list_clusters.yml"

specification/resources/signals/examples/curl/signals_create_export.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"agent_id":"01a0f3d5-b58d-7c99-a743-7ca0397b7f5d","signal_type":["ExecutionFailureToolNotFound"]}' \
+    "https://api.digitalocean.com/v1/signals/exports"

specification/resources/signals/examples/curl/signals_get_consent.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/consent/019fb3d2-8a56-72cc-8bf9-9d21510b2a99"

specification/resources/signals/examples/curl/signals_get_export.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/signals/exports/9f13c09c-c877-436b-9863-dcc39c9dd737"

specification/resources/signals/examples/curl/signals_get_export_download.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/signals/exports/9f13c09c-c877-436b-9863-dcc39c9dd737/download"

specification/resources/signals/examples/curl/signals_get_export_options.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/signals/exports/options"

specification/resources/signals/examples/curl/signals_list_consents.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/consent"

specification/resources/signals/examples/curl/signals_list_dialogues.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/signals/sessions/01a0f3d5-d5f1-798a-9352-2cd8f8b81e78/dialogues?limit=20"

specification/resources/signals/examples/curl/signals_list_exports.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/signals/exports?limit=20"

specification/resources/signals/examples/curl/signals_list_sessions.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v1/signals/agents/019fb3d2-8a56-72cc-8bf9-9d21510b2a99/sessions?limit=20"

specification/resources/signals/examples/curl/signals_update_consent.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X PUT \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"enabled":true}' \
+    "https://api.digitalocean.com/v1/consent/019fb3d2-8a56-72cc-8bf9-9d21510b2a99"

specification/resources/signals/models/agent_consent.yml

@@ -0,0 +1,38 @@
+type: object
+description: Consent details for a specific agent, including an allowed flag.
+properties:
+  id:
+    type: integer
+    description: The unique numeric identifier for the consent record.
+    example: 13
+  team_id:
+    type: integer
+    description: The team ID that owns this consent record.
+    example: 39449946
+  agent_id:
+    type: string
+    format: uuid
+    description: The unique identifier of the agent. For Harness Runtime, this is the Environment Config ID.
+    example: 019fb3d2-8a56-72cc-8bf9-9d21510b2a99
+  enabled:
+    type: boolean
+    description: Whether signals collection is enabled for this agent.
+    example: true
+  allowed:
+    type: boolean
+    description: >-
+      Whether the team is permitted to use signals for this agent. This is
+      determined by the platform and cannot be set by the user.
+    example: true
+  updated_at:
+    type: string
+    format: date-time
+    description: A time value given in ISO8601 combined date and time format.
+    example: "2026-08-10T10:09:25.738533Z"
+required:
+  - id
+  - team_id
+  - agent_id
+  - enabled
+  - allowed
+  - updated_at

specification/resources/signals/models/consent_record.yml

@@ -0,0 +1,31 @@
+type: object
+description: A consent record indicating whether signals collection is enabled for an agent.
+properties:
+  id:
+    type: integer
+    description: The unique numeric identifier for the consent record.
+    example: 13
+  team_id:
+    type: integer
+    description: The team ID that owns this consent record.
+    example: 39449946
+  agent_id:
+    type: string
+    format: uuid
+    description: The unique identifier of the agent. For Harness Runtime, this is the Environment Config ID.
+    example: 019fb3d2-8a56-72cc-8bf9-9d21510b2a99
+  enabled:
+    type: boolean
+    description: Whether signals collection is enabled for this agent.
+    example: true
+  updated_at:
+    type: string
+    format: date-time
+    description: A time value given in ISO8601 combined date and time format.
+    example: "2026-08-10T10:09:25.738533Z"
+required:
+  - id
+  - team_id
+  - agent_id
+  - enabled
+  - updated_at

specification/resources/signals/models/create_export_request.yml

@@ -0,0 +1,37 @@
+type: object
+description: Request body to create a new signals data export.
+properties:
+  agent_id:
+    type: string
+    format: uuid
+    description: The agent whose data should be exported. For Harness Runtime, this is the Environment Config ID.
+    example: 01a0f3d5-b58d-7c99-a743-7ca0397b7f5d
+  signal_type:
+    type: array
+    items:
+      type: string
+    description: >-
+      Filter the export to only include the specified signal types. Use the
+      export options endpoint to list available values.
+    example:
+      - ExecutionFailureToolNotFound
+  session_ids:
+    type: array
+    description: Optional list of specific session IDs to include in the export.
+    items:
+      type: string
+      format: uuid
+    example:
+      - 01a0f3d5-d5f1-798a-9352-2cd8f8b81e78
+  start_time:
+    type: string
+    format: date-time
+    description: Include only sessions that started at or after this timestamp.
+    example: "2026-09-01T00:00:00Z"
+  end_time:
+    type: string
+    format: date-time
+    description: Include only sessions that started at or before this timestamp.
+    example: "2026-10-01T00:00:00Z"
+required:
+  - agent_id

specification/resources/signals/models/export_download.yml

@@ -0,0 +1,15 @@
+type: object
+description: A pre-signed download URL for a completed export.
+properties:
+  download_url:
+    type: string
+    format: uri
+    description: A temporary pre-signed URL to download the export archive.
+    example: "https://example-bucket.nyc3.digitaloceanspaces.com/exports/3f2a1c4e-5b6d-4e7f-8a9b-0c1d2e3f4a5b/9f13c09c-c877-436b-9863-dcc39c9dd737.json.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=EXAMPLE"
+  expires_at:
+    type: integer
+    description: Unix timestamp when the download URL expires. The URL is valid for 15 minutes.
+    example: 1791390640
+required:
+  - download_url
+  - expires_at

specification/resources/signals/models/export_job.yml

@@ -0,0 +1,64 @@
+type: object
+description: An export job that produces a downloadable archive of signals data.
+properties:
+  export_id:
+    type: string
+    format: uuid
+    description: The unique identifier for the export job.
+    example: 9f13c09c-c877-436b-9863-dcc39c9dd737
+  agent_id:
+    type: string
+    format: uuid
+    description: The agent whose data is being exported. For Harness Runtime, this is the Environment Config ID.
+    example: 01a0f3d5-b58d-7c99-a743-7ca0397b7f5d
+  status:
+    type: string
+    description: The current status of the export job.
+    enum:
+      - pending
+      - processing
+      - complete
+      - failed
+    example: complete
+  filters:
+    type: object
+    description: The filters applied to this export.
+    properties:
+      signal_type:
+        type: array
+        items:
+          type: string
+        description: Signal types included in the export.
+        example:
+          - ExecutionFailureToolNotFound
+      session_ids:
+        type: array
+        items:
+          type: string
+        description: Specific session IDs included in the export.
+        example:
+          - 01a0f3d5-d5f1-798a-9352-2cd8f8b81e78
+  created_at:
+    type: integer
+    description: Unix timestamp when the export was created.
+    example: 1791036405
+  completed_at:
+    type: integer
+    nullable: true
+    description: Unix timestamp when the export completed, or null if still in progress.
+    example: 1791036405
+  expires_at:
+    type: integer
+    nullable: true
+    description: Unix timestamp when the export download link expires.
+    example: 1791641205
+  error_message:
+    type: string
+    nullable: true
+    description: Error message if the export failed, or null on success.
+    example: null
+required:
+  - export_id
+  - agent_id
+  - status
+  - created_at

specification/resources/signals/models/export_options.yml

@@ -0,0 +1,28 @@
+type: object
+description: Available filter options for creating exports.
+properties:
+  filters:
+    type: object
+    properties:
+      signal_type:
+        type: array
+        description: The list of valid signal type values that can be used when creating an export.
+        items:
+          type: string
+        example:
+          - DisengagementEscalation
+          - DisengagementNegativeStance
+          - DisengagementQuit
+          - EnvironmentExhaustionApiError
+          - EnvironmentExhaustionContextOverflow
+          - ExecutionFailureToolNotFound
+          - ExecutionLoopsRetry
+          - MisalignmentCorrection
+          - SatisfactionConfirmation
+          - SatisfactionGratitude
+          - SatisfactionSuccess
+          - StagnationRepetition
+    required:
+      - signal_type
+required:
+  - filters

specification/resources/signals/models/list_consents.yml

@@ -0,0 +1,10 @@
+type: object
+description: A wrapper for a list of consent records.
+properties:
+  consents:
+    type: array
+    description: A list of consent records for the team's agents.
+    items:
+      $ref: 'consent_record.yml'
+required:
+  - consents

specification/resources/signals/models/session.yml

@@ -0,0 +1,27 @@
+type: object
+description: A session represents a conversation monitored by Signals, such as a Harness Runtime agent session or a Serverless Inference chat completion.
+properties:
+  session_id:
+    type: string
+    format: uuid
+    description: The unique identifier for the session.
+    example: 01a0f3d5-d5f1-798a-9352-2cd8f8b81e78
+  total_turns:
+    type: integer
+    description: The total number of conversation turns in this session.
+    example: 5
+  started_at:
+    type: string
+    format: date-time
+    description: When the session started.
+    example: "2026-09-15T14:30:00Z"
+  duration_seconds:
+    type: number
+    description: The duration of the session in seconds.
+    example: 120.5
+  signal_count:
+    type: integer
+    description: The number of signals detected in this session.
+    example: 3
+required:
+  - session_id