feat: add CRUD REST API for saved searches (/api/v2/saved-searches)

[ankitcharolia]

Summary

Adds full CRUD endpoints for saved searches to the external API (/api/v2/saved-searches), enabling infrastructure-as-code tooling to provision saved searches programmatically.

The SavedSearch mongoose model and toExternalJSON() method already existed — only the router and its registration were missing.

New endpoints:

Method	Path	Description
GET	/api/v2/saved-searches	List all saved searches for the team
POST	/api/v2/saved-searches	Create a saved search
GET	/api/v2/saved-searches/:id	Get a saved search by ID
PUT	/api/v2/saved-searches/:id	Update a saved search
DELETE	/api/v2/saved-searches/:id	Delete a saved search

Screenshots or video

Before	After
/api/v2/saved-searches → 404	GET /api/v2/saved-searches → { data: [...] }

How to test on Vercel preview

Steps:

1. Obtain a Bearer token from Team Settings → API Keys
2. curl -H 'Authorization: Bearer <token>' <preview-url>/api/v2/saved-searches — should return { "data": [] }
3. POST a new saved search with name, sourceId, and optional where/whereLanguage/select/orderBy/tags
4. Verify GET/PUT/DELETE round-trips work correctly
5. Confirm that saved searches created here appear in the UI and can be referenced in alerts via savedSearchId

References

• Closes feat: add CRUD REST API for saved searches (/api/v2/saved-searches) #2543
• Follows the same pattern as packages/api/src/routers/external-api/v2/connections.ts
• Integration tests in packages/api/src/routers/external-api/__tests__/savedSearches.test.ts

[vercel]

@ankitcharolia is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 7391f48

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Minor
@hyperdx/app	Minor
@hyperdx/otel-collector	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Summary

This PR adds saved-search CRUD support to the external API. The main changes are:

• New /api/v2/saved-searches list, create, read, update, and delete routes.
• Team-scoped source validation for saved-search create and update.
• Full-replace update behavior for optional saved-search fields.
• Cascade deletion of alerts that reference a deleted saved search.
• OpenAPI docs, changeset, and integration coverage for the new endpoints.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
packages/api/src/routers/external-api/v2/savedSearches.ts	Adds the saved-search CRUD router with validation, team-scoped access, source ownership checks, and full-replace update handling.
packages/api/src/controllers/savedSearch.ts	Adds replacement update support and updates saved-search deletion to remove referencing alerts first.
packages/api/src/routers/external-api/v2/index.ts	Registers the saved-searches router behind the existing external API middleware.

_{Reviews (14): Last reviewed commit: "Merge branch 'main' into feat/saved-sear..." | Re-trigger Greptile}

[github-actions]

Deep Review

✅ No critical issues found. No P0/P1 ship-blockers: every handler scopes queries to the authenticated team, input is length-bounded via zod, no injection or auth-bypass path exists, and the loose fieldsToSet typing still type-checks (so CI is not broken). The items below are correctness/reliability recommendations and nits.

🟡 P2 — recommended

• packages/api/src/routers/external-api/v2/savedSearches.ts:42 — Internally-created saved searches with whereLanguage: 'promql' or a non-empty where and no whereLanguage are returned by GET but rejected by POST/PUT, so an external client cannot round-trip-edit them without silently altering query semantics.
  • Fix: Tolerate promql and where-without-whereLanguage on the write path, or document such searches as read-only through the external API.
  • _{adversarial, api-contract}
• packages/api/src/controllers/savedSearch.ts:71 — The reordered cascade delete removes referencing alerts before the search with no transaction, so a failure at the findOneAndDelete step leaves the search live but its alerts permanently gone, silently disabling its monitoring.
  • Fix: Wrap both deletes in a mongoose session/transaction, or guarantee the delete is retried to convergence and document that requirement.
  • _{reliability, adversarial}
• packages/api/src/routers/external-api/v2/savedSearches.ts:339 — The OpenAPI docs declare application/json Error bodies for 401/403/404, but the handlers use res.sendStatus(), which returns a plain-text body with no { message } payload.
  • Fix: Return res.status(n).json({ message }) for these paths, or update the OpenAPI responses to document an empty/plain body.
  • _api-contract
• packages/api/src/routers/external-api/__tests__/savedSearches.test.ts:729 — No test asserts cross-team alert-cascade isolation on DELETE; the reorder now relies solely on the untested team filter inside deleteSavedSearchAlerts.
  • Fix: Add a case creating another team's alert that references the same savedSearch, delete as the current team (expect 404), and assert the other team's alert still exists.
  • _testing

🔵 P3 nitpicks (7)

• packages/api/src/routers/external-api/v2/savedSearches.ts:596 — fieldsToSet typed as Record<string, unknown> erases the replaceSavedSearch typed contract and masks a POST-vs-PUT inconsistency: POST stores updatedBy via userId?.toString() (string) while PUT assigns the raw ObjectId; runtime is safe because mongoose accepts an ObjectId ref.
  • Fix: Type fieldsToSet as Partial<SavedSearchWithoutId & { updatedBy?: string }> and set updatedBy: userId?.toString() to match the create path.
• packages/api/src/routers/external-api/v2/savedSearches.ts:126 — The field definitions (maxLength/enum/example) are hand-written across the SavedSearch, CreateSavedSearchRequest, and UpdateSavedSearchRequest OpenAPI schemas plus the zod bodySchema, so a bound change must land in four places and can silently drift.
  • Fix: Compose the request schemas from a shared component via $ref/allOf, keeping only create/update deltas inline.
• packages/api/src/routers/external-api/v2/savedSearches.ts:24 — boundedFilterSchema re-implements the shared FilterSchema by hand purely to add .max() bounds, so a new filter type or operator added upstream would silently diverge.
  • Fix: Derive the bounded schema from the shared FilterSchema union rather than re-declaring its shape.
• packages/api/src/routers/external-api/v2/savedSearches.ts:336 — GET / runs SavedSearch.find({ team }).sort({ name: 1 }) with no limit or pagination, returning an unbounded result set; impact is low at realistic per-team sizes.
  • Fix: Add a bounded default page size and cursor/offset pagination consistent with other list endpoints.
• packages/api/src/controllers/savedSearch.ts:71 — The alert-first delete ordering's partial-failure/retry claim is asserted only in a comment, with no fault-injection test.
  • Fix: Add a controller-level test mocking findOneAndDelete to reject after deleteSavedSearchAlerts resolves, asserting error propagation and safe retryability.
• packages/api/src/routers/external-api/v2/savedSearches.ts:338 — The teamId == null → 403 guard is duplicated in all five handlers (pre-existing pattern shared with sibling external-api routers).
  • Fix: Extract a requireTeam middleware that attaches a non-null teamId and 403s once, then drop the per-handler guard.
• packages/api/src/mcp/tools/savedSearches/index.ts — The new external DELETE has no MCP counterpart (get + save tools exist, but no clickstack_delete_saved_search), so an agent has create/read/update but not delete parity; pre-existing gap surfaced by this PR.
  • Fix: File a follow-up to add a deleteSavedSearch MCP tool mirroring the existing deleteDashboard pattern.

---

Reviewers (12): correctness, security, adversarial, api-contract, reliability, kieran-typescript, testing, maintainability, project-standards, performance, agent-native, learnings-researcher.

Testing gaps:

• Cross-team alert-cascade isolation on DELETE is unverified (P2 above).
• Delete partial-failure state (alerts gone, search survives) has no fault-injection coverage.
• No round-trip test for internally-created searches with whereLanguage: 'promql', non-empty where without whereLanguage, or fields exceeding external maxLength — all rejected by the external write schema.
• No test asserts the zod bounds match the documented OpenAPI maxLength/maxItems values, so doc↔enforcement drift would go undetected.

Notes: security and performance returned no findings. project-standards confirmed the changeset and router conventions match the connections.ts reference; its only flag (setBusinessContext instrumentation) is a pre-existing directory-wide convention and was dropped. No prior learnings exist in docs/solutions/ for this area.

[pulpdrew]

Hey @ankitcharolia - thank you for the contribution! Unfortunately it seems like a team member was concurrently working on the same thing in #2586 as part of ongoing terraform-provider work. We will likely move ahead with #2586 and close this PR, but if you have any thoughts on #2586 or think it will not cover your use-case, please let us know or feel free to comment there.