Skip to content

COBS-1288: Add Insights alert instances OpenAPI - #1226

Open
adityasingh-beep wants to merge 1 commit into
digitalocean:mainfrom
adityasingh-beep:adityasingh/COBS-1288-Publish-OpenAPI-spec-for-Insights-alert-instances
Open

adityasingh-beep wants to merge 1 commit into
digitalocean:mainfrom
adityasingh-beep:adityasingh/COBS-1288-Publish-OpenAPI-spec-for-Insights-alert-instances

Conversation

@adityasingh-beep

@adityasingh-beep adityasingh-beep commented Sep 16, 2026

Copy link
Copy Markdown

Summary

  • Adds public OpenAPI for the read-only Insights alert instances endpoints under /v2/insights/alert-instances (COBS-1288):
    • GET /v2/insights/alert-instances — list, with status (active/resolved), rule_id, and resource_urn filters
    • GET /v2/insights/alert-instances/{id} — retrieve a single alert instance
  • Aligned to the Alerts Public Insights API RFC wire contract: snake_case fields, lowercase enums (severity: warning|critical, status: active|resolved), RFC 3339 timestamps, uuid ids, links/meta list envelope, page/per_page (default 20, max 200), scope insights:read.
  • Read-only surface: no create/update/delete, matching the Edge routing (GET only) merged for COBS-1287.

Note: the Jira ticket text says /v2/insights/alerts, but the deployed paths (Edge config + staging) are /v2/insights/alert-instances; this PR follows the deployed paths.

Test plan

  • Examples match RFC request/response shapes; all $refs resolve and examples validate strictly against the alert_instance schema
  • Routed end-to-end on staging (stage 2) through a Prism validation proxy: authenticated GET /v2/insights/alert-instances?status=active&page=1&per_page=20 returns 200 from api-service
  • Confirm api-service public DTO emits RFC wire format (staging currently still returns proto-style enums / pagination object / owner_uuid)
  • Validate a populated alert instance against this spec via the staging proxy
  • Reconcile shared Insights tag / parameters.yml with COBS-1289: Add Insights notification channels OpenAPI #1224 / COBS-1290: Add Insights alert rules OpenAPI #1225 (whichever merges last)
  • After merge, confirm docs regen publishes the new endpoints

Blocked by / ships after: COBS-1287 Edge routing.

Related: notification-channels draft #1224 (COBS-1289), alert-rules draft #1225 (COBS-1290).

Adds the read-only Insights alert instances endpoints:

- GET /v2/insights/alert-instances (list; filters: status, rule_id,
  resource_urn; standard page/per_page pagination with links/meta envelope)
- GET /v2/insights/alert-instances/{id}

Spec follows the agreed Alerts Public Insights API contract: snake_case
fields, lowercase enums (severity: warning|critical, status:
active|resolved), RFC 3339 timestamps, uuid identifiers, and the standard
DO list envelope via shared pages/meta components. Scope: insights:read,
matching the staging Edge routing for COBS-1287.

Co-authored-by: Cursor <cursoragent@cursor.com>
@adityasingh-beep
adityasingh-beep marked this pull request as ready for review September 16, 2026 13:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant