Search API
GET /api/v1/search
Section titled “GET /api/v1/search”Search
RBAC: viewer (entry gate app:read). Entitlement: ui.global_search.
Fuzzy-ish search across apps, VMs, hosts and store entries.
An empty or single-character query returns nothing rather than everything: a palette that dumps the whole inventory on first keystroke is noise, and the operator has a nav for browsing.
ENTITLEMENTS ARE PER GROUP, and the route-level dependency is deliberately
gone. ui.global_search still gates apps, VMs and hosts, exactly as it
gated the whole endpoint before; store.catalog gates the store group, the
same flag the Store’s own routes use (api/catalog.py). A caller with
neither is 403ed on ui.global_search, which is the response this route
already gave that caller, so nothing that could see this endpoint before
loses anything.
Moving the check inside is what makes store-only possible at all, and it
is the one restructuring with a real hazard: the four groups must stay
independently gated, so that dropping the route-level dependency cannot
hand an app, VM or host row to a caller who could not have seen this
endpoint at all a moment ago. Both halves of every group’s condition, the
entitlement AND _visible, are load bearing.
Queries under 2 characters return no results. Up to 8 results per kind. Each result section is additionally filtered, per request, against that resource’s own permission (app:read, vm:read, host:read, catalog:read), so a viewer without host:read never sees a host in the results.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | no |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful Response | any |
| 422 | Validation Error | HTTPValidationError |