Add Insights enablement endpoints

specification/DigitalOcean-public.v2.yaml

@@ -438,8 +438,9 @@ tags:
       The DigitalOcean Insights API provides observability resources for
       monitoring your infrastructure, including alert rules that evaluate
       metrics, notification channels that deliver alert events, read-only
-      alert instances that record when alert rules fire, and PromQL and logs
-      query interfaces.
+      alert instances that record when alert rules fire, PromQL, logs, spans,
+      and traces query interfaces, and per-resource enablement of the metrics,
+      logs, and traces signals.
 
   - name: Kubernetes
     description: |-
@@ -2047,6 +2048,18 @@ paths:
     post:
       $ref: "resources/insights/insights_post_spansSearch.yml"
 
+  /v2/insights/resources:
+    get:
+      $ref: "resources/insights/insights_list_resources.yml"
+
+  /v2/insights/resources/{resource_urn}:
+    get:
+      $ref: "resources/insights/insights_get_resource.yml"
+
+  /v2/insights/resources/{resource_urn}/signals:
+    put:
+      $ref: "resources/insights/insights_update_resourceSignals.yml"
+
   /v1/consent:
     get:
       $ref: "resources/signals/signals_list_consents.yml"

specification/resources/insights/examples/curl/insights_get_resource.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/insights/resources/do:droplet:12345"

specification/resources/insights/examples/curl/insights_list_resources.yml

@@ -0,0 +1,5 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/insights/resources?filter.product_types=droplet&pagination.per_page=50"

specification/resources/insights/examples/curl/insights_update_resourceSignals.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X PUT \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"region":"nyc3","metrics":true,"logs":true}' \
+    "https://api.digitalocean.com/v2/insights/resources/do:droplet:12345/signals"

specification/resources/insights/insights_get_resource.yml

@@ -0,0 +1,46 @@
+operationId: insights_get_resource
+
+summary: Retrieve Resource Signal Enablement
+
+description: |
+  To retrieve the current metrics, logs, and traces signal enablement for a
+  single resource, send a GET request to
+  `/v2/insights/resources/{resource_urn}`.
+
+  A `404` is returned when no signal enablement has been recorded for the
+  resource.
+
+tags:
+  - Insights
+
+parameters:
+  - $ref: 'parameters.yml#/resource_urn_path'
+
+responses:
+  '200':
+    $ref: 'responses/resource.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/insights_get_resource.yml'
+
+security:
+  - bearer_auth:
+      - 'insights:read'

specification/resources/insights/insights_list_resources.yml

@@ -0,0 +1,53 @@
+operationId: insights_list_resources
+
+summary: List Resource Signal Enablement
+
+description: |
+  To list the resources in your account that have telemetry signal enablement
+  recorded, along with the current state of their metrics, logs, and traces
+  signals, send a GET request to `/v2/insights/resources`.
+
+  Results are paginated with `pagination.page` and `pagination.per_page`
+  (default `20`, maximum `200`) and can be sorted with `pagination.sort` and
+  `pagination.sort_direction`. Optionally filter by `filter.product_types` and
+  `filter.regions`.
+
+  A signal is omitted from a resource when no explicit enablement has ever been
+  recorded for it.
+
+tags:
+  - Insights
+
+parameters:
+  - $ref: 'parameters.yml#/resources_product_types'
+  - $ref: 'parameters.yml#/resources_regions'
+  - $ref: 'parameters.yml#/resources_page'
+  - $ref: 'parameters.yml#/resources_per_page'
+  - $ref: 'parameters.yml#/resources_sort'
+  - $ref: 'parameters.yml#/resources_sort_direction'
+
+responses:
+  '200':
+    $ref: 'responses/list_resources.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/insights_list_resources.yml'
+
+security:
+  - bearer_auth:
+      - 'insights:read'

specification/resources/insights/insights_update_resourceSignals.yml

@@ -0,0 +1,64 @@
+operationId: insights_update_resourceSignals
+
+summary: Update Resource Signal Enablement
+
+description: |
+  To enable or disable telemetry signals for a resource, send a PUT request to
+  `/v2/insights/resources/{resource_urn}/signals`.
+
+  This endpoint uses merge semantics. Set `metrics`, `logs`, or `traces` to
+  `true` or `false` to change that signal; omit a signal to leave it unchanged.
+  At least one signal must be set.
+
+  `region` is only used when the resource has no existing enablement. On later
+  updates, omit it or send the stored value; changing the region is rejected
+  with a `400`.
+
+  Requires both the `insights:update` and `insights:create` scopes.
+
+tags:
+  - Insights
+
+parameters:
+  - $ref: 'parameters.yml#/resource_urn_path'
+
+requestBody:
+  required: true
+  content:
+    application/json:
+      schema:
+        $ref: 'models/resource_signals_update_request.yml'
+      example:
+        region: nyc3
+        metrics: true
+        logs: true
+
+responses:
+  '200':
+    $ref: 'responses/resource.yml'
+
+  '400':
+    $ref: '../../shared/responses/bad_request.yml'
+
+  '401':
+    $ref: '../../shared/responses/unauthorized.yml'
+
+  '404':
+    $ref: '../../shared/responses/not_found.yml'
+
+  '429':
+    $ref: '../../shared/responses/too_many_requests.yml'
+
+  '500':
+    $ref: '../../shared/responses/server_error.yml'
+
+  default:
+    $ref: '../../shared/responses/unexpected_error.yml'
+
+x-codeSamples:
+  - $ref: 'examples/curl/insights_update_resourceSignals.yml'
+
+security:
+  - bearer_auth:
+      - 'insights:update'
+      - 'insights:create'

specification/resources/insights/models/enablement_resource.yml

@@ -0,0 +1,24 @@
+type: object
+description: The current telemetry signal enablement for a single resource.
+required:
+  - resource_urn
+  - product_type
+properties:
+  resource_urn:
+    type: string
+    description: The uniform resource name (URN) of the resource.
+    example: do:droplet:12345
+  product_type:
+    type: string
+    description: The product type of the resource, for example `droplet` or `kubernetes`.
+    example: droplet
+  region:
+    type: string
+    description: The region slug for region-specific resources. Omitted when the resource has no region.
+    example: nyc3
+  metrics:
+    $ref: 'resource_signal_state.yml'
+  logs:
+    $ref: 'resource_signal_state.yml'
+  traces:
+    $ref: 'resource_signal_state.yml'

specification/resources/insights/models/list_resources_response.yml

@@ -0,0 +1,10 @@
+type: object
+description: Response body for listing resource signal enablement.
+properties:
+  resources:
+    type: array
+    description: Resources with recorded signal enablement. Omitted when none match.
+    items:
+      $ref: 'enablement_resource.yml'
+  pagination:
+    $ref: 'resources_pagination_response.yml'

specification/resources/insights/models/resource_response.yml

@@ -0,0 +1,7 @@
+type: object
+description: Response body wrapping a single resource's signal enablement.
+required:
+  - resource
+properties:
+  resource:
+    $ref: 'enablement_resource.yml'

specification/resources/insights/models/resource_signal_state.yml

@@ -0,0 +1,15 @@
+type: object
+description: >-
+  The enablement state of a single telemetry signal (metrics, logs, or traces)
+  for a resource. A signal state is omitted from a resource when no explicit
+  enablement has ever been recorded for that signal.
+properties:
+  enabled:
+    type: boolean
+    description: Whether the signal is enabled for the resource.
+    example: true
+  effective_at:
+    type: string
+    format: date-time
+    description: When this signal state last changed.
+    example: '2026-10-01T12:00:00Z'

specification/resources/insights/models/resource_signals_update_request.yml

@@ -0,0 +1,25 @@
+type: object
+description: >-
+  Request body for updating a resource's signal enablement. At least one of
+  `metrics`, `logs`, or `traces` must be set. Signals that are omitted are left
+  unchanged.
+properties:
+  region:
+    type: string
+    description: >-
+      The region slug for region-specific resources. Only used when the
+      resource has no existing enablement. On later updates, omit it or send the
+      stored value; changing the region is rejected.
+    example: nyc3
+  metrics:
+    type: boolean
+    description: Enable or disable the metrics signal. Omit to leave unchanged.
+    example: true
+  logs:
+    type: boolean
+    description: Enable or disable the logs signal. Omit to leave unchanged.
+    example: true
+  traces:
+    type: boolean
+    description: Enable or disable the traces signal. Omit to leave unchanged.
+    example: false

specification/resources/insights/models/resources_pagination_response.yml

@@ -0,0 +1,19 @@
+type: object
+description: Page-based pagination metadata for a resources list.
+properties:
+  page:
+    type: integer
+    description: The current page number.
+    example: 1
+  pages:
+    type: integer
+    description: The total number of pages.
+    example: 3
+  per_page:
+    type: integer
+    description: The number of items per page.
+    example: 20
+  total:
+    type: integer
+    description: The total number of resources across all pages.
+    example: 42