Deprecated search endpoints

This document records the deprecation status of every legacy search endpoint.

Vetrix's deprecation contract for these endpoints is:

1. The endpoint continues to serve traffic with its current contract — API-level back-compat is preserved for personal-access-token consumers, third-party scripts, and any integrations the project does not control.
2. The handler doc-comment marks it Deprecated and identifies the supported replacement path. Code-review bots and IDE tooling that honour the // Deprecated: Go convention surface the deprecation to anyone editing the affected code.
3. The README API table marks the row Deprecated and links back here.
4. No new feature work lands on the deprecated handler. Bug fixes are triaged but should be evaluated against the cost of removing the handler entirely.
5. Removal happens in a follow-up run once telemetry confirms zero or negligible external traffic on the deprecated path.

Current status

Endpoint	Status	Frontend caller?	Internal Go caller?	Replacement
GET /api/v1/search	Active	Yes (/search)	Yes (site-search fallback)	n/a — this is the canonical unified entry point
GET /api/v1/search/code	Deprecated	No (per-type FE wrappers retired)	No	GET /api/v1/search?types=code
GET /api/v1/search/suggest	Deprecated	No (type-ahead removed)	No	None — type-ahead removed; reintroduce only if needed
GET /api/v1/pages/search	Deprecated	No (PageSearchBar + orphan pagesApi.searchPages and web/src/components/pages/search/* removed)	No (site-search fallback uses pages.Store.SearchPages directly)	GET /api/v1/search?types=pages
GET /api/v1/repos/:owner/:repo/issues/search	Active	Yes (searchIssues in web/src/lib/api/issues.ts)	n/a	Differentiated from list ?q= by ts_rank scoring + facets
GET /api/v1/repos/:owner/:repo/symbols	Active	Yes (repoSymbolsApi)	n/a	n/a
GET /api/v1/repos/:owner/:repo/symbols/:sym/definition	Active	Yes (repoSymbolsApi)	n/a	n/a

Endpoint-by-endpoint detail

GET /api/v1/search/code — Deprecated

Per-type code search with full-text matching across user-accessible repositories. Returns a CodeSearchResponse envelope keyed by files[] with line-level matches and short context windows.

The unified /api/v1/search?types=code endpoint supersedes per-type endpoints by surfacing code, pages, issues, MRs, and symbols in one grouped response (SiteSearchResponse). The /search UI is wired exclusively to the unified endpoint, and all per-type frontend wrappers (web/src/lib/api/codeSearch.ts, the symbols-page caller of searchCode) have been retired.

The route stays mounted because personal-access-token consumers and third-party scripts may still hit it. The response envelope is frozen at its original shape and no new feature work lands here.

Removal criteria: zero external HTTP hits over a one-month telemetry window.

GET /api/v1/search/suggest — Deprecated

Type-ahead suggestions for the global search input (symbol-name and file-path completions).

The unified-search UX submits to navigate to /search rather than offering inline type-ahead. The TopNav search input does not call this endpoint, and nothing else does. The OpenSearch Suggester infrastructure under the handler remains as scaffolding for a future reintroduction of type-ahead, but the route itself is dead code.

The route stays mounted pending a second pass to confirm no out-of-tree consumer (an unscoped admin script, an internal tool that cannot be grepped) depends on it.

Removal criteria: if telemetry confirms zero traffic, the handler (internal/api/search_suggest.go), test (search_suggest_test.go), and route registration (internal/api/router.go) can be removed in a single follow-up commit. The internal/opensearch.Searcher.Suggest method should be retained for potential reintroduction.

GET /api/v1/pages/search — Deprecated

Permission-filtered full-text page search across spaces, with q, space, label, author, from, to, limit, and offset query parameters. The handler returns a {results, limit, offset} envelope with headline and rank fields per result.

The frontend caller (PageSearchBar — a "Search pages…" input rendered at the top of the /pages list) has been removed; the TopNav global search and /search?types=pages page are the sole search entry points for authenticated users. The regression test web/src/__tests__/pages/pagesNoNonNavSearch.test.tsx pins the absence of non-nav search inputs on /pages. The orphan frontend caller chain (pagesApi.searchPages, buildSearchQuery, and the unmounted web/src/components/pages/search/* family) has also been removed, so no frontend code path issues a request against this HTTP route.

The route stays mounted for API back-compat: PATs and external scripts may call it directly. The deprecation target is only the HTTP route in front of the store, not the store logic — the Postgres pages.Store.SearchPages method is the load-bearing implementation and is still actively consumed by the site-search fallback in internal/api/site_search_fallback.go, which calls the store directly without traversing this HTTP route. The Postgres-backed store method stays exactly as it is.

Removal criteria: confirm zero external HTTP traffic on /api/v1/pages/search. Removal would strip the route registration in internal/api/router.go and the pagesHandler.SearchPages method.