COBS-1288: Add Insights alert instances OpenAPI

specification/DigitalOcean-public.v2.yaml

@@ -395,6 +395,14 @@ tags:
       To interact with images, you will generally send requests to the images
       endpoint at /v2/images.
 
+  - name: Insights
+    description: |-
+      The DigitalOcean Insights API provides observability resources for
+      monitoring your infrastructure, including alert rules that evaluate
+      metrics, notification channels that deliver alert events, and read-only
+      alert instances that record when alert rules fire against your
+      resources.
+
   - name: Kubernetes
     description: |-
       [DigitalOcean Kubernetes](https://docs.digitalocean.com/products/kubernetes/)
@@ -715,6 +723,7 @@ x-tagGroups:
       - Functions
       - Image Actions
       - Images
+      - Insights
       - Kubernetes
       - Load Balancers
       - Monitoring
@@ -1647,6 +1656,14 @@ paths:
     get:
       $ref: "resources/images/imageActions_get.yml"
 
+  /v2/insights/alert-instances:
+    get:
+      $ref: "resources/insights/insights_list_alertInstances.yml"
+
+  /v2/insights/alert-instances/{id}:
+    get:
+      $ref: "resources/insights/insights_get_alertInstance.yml"
+
   /v2/kubernetes/clusters:
     get:
       $ref: "resources/kubernetes/kubernetes_list_clusters.yml"

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

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/insights/alert-instances/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

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

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/insights/alert-instances?status=active&page=1&per_page=20"

specification/resources/insights/insights_get_alertInstance.yml

@@ -0,0 +1,39 @@
+operationId: insights_get_alertInstance
+
+summary: Retrieve an Alert Instance
+
+description: |
+  To retrieve a single alert instance, send a GET request to
+  `/v2/insights/alert-instances/{id}`.
+
+tags:
+  - Insights
+
+parameters:
+  - $ref: 'parameters.yml#/alert_instance_id'
+
+responses:
+  '200':
+    $ref: 'responses/alert_instance_response.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_alertInstance.yml'
+
+security:
+  - bearer_auth:
+      - 'insights:read'

specification/resources/insights/insights_list_alertInstances.yml

@@ -0,0 +1,53 @@
+operationId: insights_list_alertInstances
+
+summary: List Alert Instances
+
+description: |
+  To list alert instances for your account, send a GET request to
+  `/v2/insights/alert-instances`. Alert instances are read-only records of
+  alert rule firings against your resources.
+
+  Results can optionally be filtered by `status`, `rule_id`, or
+  `resource_urn`.
+
+  Results are ordered by `triggered_at` descending (newest first). Because
+  the list is append-only and continuously growing, offset-based pagination
+  is best-effort: newly triggered instances may shift older rows onto
+  subsequent pages between fetches. For stable pagination, filter by
+  `rule_id` or a fixed time window on the client side.
+
+tags:
+  - Insights
+
+parameters:
+  - $ref: '../../shared/parameters.yml#/per_page'
+  - $ref: '../../shared/parameters.yml#/page'
+  - $ref: 'parameters.yml#/alert_instance_status'
+  - $ref: 'parameters.yml#/rule_id'
+  - $ref: 'parameters.yml#/resource_urn'
+
+responses:
+  '200':
+    $ref: 'responses/list_alert_instances_response.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_alertInstances.yml'
+
+security:
+  - bearer_auth:
+      - 'insights:read'

specification/resources/insights/models/alert_instance.yml

@@ -0,0 +1,70 @@
+type: object
+description: |
+  A read-only record of an alert rule firing against a resource.
+required:
+  - id
+  - rule_id
+  - severity
+  - status
+  - value
+  - triggered_at
+  - last_triggered_at
+properties:
+  id:
+    type: string
+    format: uuid
+    description: A unique identifier for the alert instance.
+    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  rule_id:
+    type: string
+    format: uuid
+    description: ID of the alert rule that fired this alert instance.
+    example: 8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
+  severity:
+    type: string
+    description: Severity of the breached threshold.
+    enum:
+      - warning
+      - critical
+    example: warning
+  status:
+    type: string
+    description: Current status of the alert instance.
+    enum:
+      - active
+      - resolved
+    example: active
+  resource_urn:
+    type: string
+    description: |
+      URN of the DigitalOcean resource the alert fired for. May be an empty
+      string for alerts fired on non-resource-bound signals (for example,
+      cluster/pod/namespace-scoped Kubernetes alerts).
+    example: do:droplet:12345
+  value:
+    type: number
+    format: double
+    description: The observed metric value that breached the threshold.
+    example: 87.5
+  triggered_at:
+    type: string
+    format: date-time
+    description: Time the alert instance first fired.
+    example: '2026-09-03T10:15:00Z'
+  last_triggered_at:
+    type: string
+    format: date-time
+    description: Time the alert instance most recently fired.
+    example: '2026-09-03T10:45:00Z'
+  resolved_at:
+    type: string
+    format: date-time
+    description: |
+      Time the alert instance resolved. Only present when `status` is
+      `resolved`.
+    example: '2026-09-03T11:00:00Z'
+  last_notified_at:
+    type: string
+    format: date-time
+    description: Time a notification was last sent for this alert instance.
+    example: '2026-09-03T10:15:00Z'

specification/resources/insights/parameters.yml

@@ -0,0 +1,46 @@
+alert_instance_id:
+  in: path
+  name: id
+  description: A unique identifier for an alert instance.
+  required: true
+  schema:
+    type: string
+    format: uuid
+  example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+
+alert_instance_status:
+  in: query
+  name: status
+  required: false
+  description: |
+    Optional filter. When set, only alert instances with this status are
+    returned.
+  schema:
+    type: string
+    enum:
+      - active
+      - resolved
+  example: active
+
+rule_id:
+  in: query
+  name: rule_id
+  required: false
+  description: |
+    Optional filter. When set, only alert instances fired by the alert rule
+    with this ID are returned.
+  schema:
+    type: string
+    format: uuid
+  example: 8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
+
+resource_urn:
+  in: query
+  name: resource_urn
+  required: false
+  description: |
+    Optional filter. When set, only alert instances that fired for this
+    resource URN are returned.
+  schema:
+    type: string
+  example: do:droplet:12345

specification/resources/insights/responses/alert_instance_response.yml

@@ -0,0 +1,33 @@
+description: >-
+  The response will be a JSON object with a key called `alert_instance`
+  containing the standard attributes associated with an alert instance.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      type: object
+      required:
+        - alert_instance
+      properties:
+        alert_instance:
+          $ref: '../models/alert_instance.yml'
+    example:
+      alert_instance:
+        id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+        rule_id: 8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
+        severity: critical
+        status: resolved
+        resource_urn: do:droplet:12345
+        value: 95.2
+        triggered_at: '2026-09-02T08:00:00Z'
+        last_triggered_at: '2026-09-02T08:30:00Z'
+        resolved_at: '2026-09-02T09:00:00Z'
+        last_notified_at: '2026-09-02T08:00:00Z'

specification/resources/insights/responses/list_alert_instances_response.yml

@@ -0,0 +1,40 @@
+description: >-
+  The response will be a JSON object with a key called `alert_instances`. This
+  will be set to an array of alert instance objects, each of which will contain
+  the standard attributes associated with an alert instance.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      allOf:
+        - type: object
+          properties:
+            alert_instances:
+              type: array
+              items:
+                $ref: '../models/alert_instance.yml'
+        - $ref: '../../../shared/pages.yml#/pagination'
+        - $ref: '../../../shared/meta.yml'
+    example:
+      alert_instances:
+        - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
+          rule_id: 8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
+          severity: warning
+          status: active
+          resource_urn: do:droplet:12345
+          value: 87.5
+          triggered_at: '2026-09-03T10:15:00Z'
+          last_triggered_at: '2026-09-03T10:45:00Z'
+          last_notified_at: '2026-09-03T10:15:00Z'
+      links:
+        pages: {}
+      meta:
+        total: 1