---
title: "Search for packages"
method: GET
path: "/api/v1/catalog/search"
tags: ["catalog"]
---

# Search for packages

`GET /api/v1/catalog/search`

Search the catalog(s) under the given criteria for matching packages.

Required Query Parameters:
- **system**: The system architecture to search for (e.g., x86_64-linux)

Optional Query Parameters:
- **search_term**: The search term to filter packages by
- **catalogs**: Comma separated list of catalog names to search; defaults to
  all catalogs. Note: when searching base catalog, search_term is required.
- **page**: Page number for pagination (default: 0)
- **pageSize**: Page size for pagination (default: 10)
Returns:
- **PackageSearchResult**: A list of PackageInfoSearch items and total count

## Query parameters

- `system` 'aarch64-darwin' | 'aarch64-linux' | 'x86_64-darwin' | 'x86_64-linux' | 'invalid', required
- `search_term` string, nullable
- `catalogs` string, nullable
- `page` integer
- `pageSize` integer

## Response `200`

A list of matching packages

- PackageSearchResult
  - `items` PackageInfoSearch[], required
    - `attr_path` string, required
    - `catalog` string, nullable, required
    - `pkg_path` string, required
    - `name` string, required
    - `pname` string, required
    - `version` string, nullable, required — While version should always be present, (and is required in the PackageResolutionInfo model), there are cases where it has been historically optional and thus is carried forward here. Published derivations have an Optional version and this same model is used for both published derivations and base catalog derivations. For this reason we cannot make it required here until/if we unify those models and ensure every derivation does in fact have a version.
    - `description` string, nullable, required
    - `stabilities` string[], required
    - `system` 'aarch64-darwin' | 'aarch64-linux' | 'x86_64-darwin' | 'x86_64-linux' | 'invalid', required
    - `deprecation` DeprecationInfo — Deprecation metadata for a package from nixpkgs aliases.nix
      - `kind` 'renamed' | 'removed' | 'deprecated', required — Package deprecation category from nixpkgs aliases.nix
      - `replacement` string, nullable
      - `message` string, nullable
  - `total_count` integer, required

## Other responses

- `422` — The search terms given could not be processed

## Changes

- **2026-08-27** `8ec561551880` — 2 breaking, 4 warning, 1 info
  - the `items/items/deprecation` response's property type changed from `object` to no type for status `200`
  - removed the required property `items/items/deprecation/kind` from the response with the `200` status
  - for the `query` request parameter `page`, the min was set to `0.00`
  - for the `query` request parameter `pageSize`, the min was set to `0.00`
  - …3 more
- **2026-07-23** `05d6283fc201` — 1 breaking, 1 warning, 1 info
  - for the `query` request parameter `search_term`, the minLength was increased from `0` to `2`
  - for the `query` request parameter `search_term`, the maxLength was set to `200`
  - removed the pattern `[a-zA-Z0-9\-\.\\@%_,]{2,200}` from the `query` request parameter `search_term`
- **2026-03-18** `b99206a49d27` — 1 info
  - added the optional property `items/items/deprecation` to the response with the `200` status
- **2025-07-23** `29c059f1823a` — 1 info
  - the endpoint scheme security `HTTPBasic` was added to the API
- **2025-04-18** `03a19e372fd8` — 1 breaking, 1 info
  - for the `query` request parameter `catalogs`, default value `nixpkgs` was removed
  - the `query` request parameter `search_term` became optional

[Full history](https://skmtc.dev/flox/apis/floxhub-catalog-server/changes/api/v1/catalog/search/get.md)

---

[API](https://skmtc.dev/flox/apis/floxhub-catalog-server.md) · [All operations](https://skmtc.dev/flox/apis/floxhub-catalog-server/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flox/floxhub-catalog-server/revisions/8ec561551880/schema)