---
title: "List packages available in a catalog"
method: GET
path: "/api/v1/catalog/catalogs/{catalog_name}/packages"
tags: ["catalogs"]
---

# List packages available in a catalog

`GET /api/v1/catalog/catalogs/{catalog_name}/packages`

## Request

- The document declares no server URL.
- Auth: one of:
  - HTTP bearer
  - HTTP basic

Lists available packages in a catalog

Path Parameters:
- **catalog_name**: The name of the catalog

Returns:
- **UserPackageList**

## Path parameters

- `catalog_name` string, required

## Response `200`

The list of packages

- UserPackageList
  - `items` UserPackage[], required
    - `catalog` string, required
    - `name` string, required
    - `original_url` string, nullable
    - `lifecycle` PackageLifecycleInfo: Lifecycle state a package has been placed in, with the policy that state implies. Absent (null) means ordinary circulation.
      - `state` string, required: The lifecycle state a package is in, for example 'archived'. New states may be added over time; clients should branch on policy rather than on this value.
      - `source` string, required: The authority that placed the package in its lifecycle state, for example 'publisher'. New sources may be added over time.
      - `effective_at` string, date-time, required: When the state took effect.
      - `reason` string, nullable: Why the package entered this state, as recorded by the source.
      - `replacement` string, nullable: Installable reference to a suggested substitute: catalog_name/attr_path for a catalog package, a bare attr_path for a base-catalog package.
      - `message` string, nullable: Publisher-authored note to show alongside the state.
      - `policy` LifecyclePolicy, required: What a lifecycle state permits, one boolean per capability. Clients should branch on these capabilities rather than on the state name, so a state added later renders correct affordances without a client release.
        - `visible_in_discovery` boolean, required: Whether the package appears where users browse: search results, listings, and package summaries.
        - `allows_name_resolution` boolean, required: Whether name-based resolution may select this package. False does not mean the package is gone; a manifest naming it resolves to some other package or fails outright.
        - `allows_exact_pin` boolean, required: Whether a lockfile pinning this exact package still resolves. Environments locked before the state changed keep resolving.
        - `allows_publish` boolean, required: Whether a new build may be published to this package.
        - `warning_required` boolean, required: Whether a consumer that honors the package anyway, in practice the exact-pin path, must surface a warning.

## Other responses

- `404`: The catalog could not be found.
- `422`: The request parameters are invalid

## Changes

- **2026-08-27** `8ec561551880`: 1 info
  - added the optional property `items/items/lifecycle` to the response with the `200` status
- **2026-07-28** `05d6283fc201`: 1 warning
  - changed the pattern of the `path` request parameter `catalog_name` from `[a-zA-Z0-9\-_]{3,64}` to `^[a-zA-Z0-9\-_]{3,63}$`
- **2025-07-25** `29c059f1823a`: 1 info
  - the endpoint scheme security `HTTPBasic` was added to the API
- **2025-03-27** `5e278301f159`: 1 info
  - response property `items/items/original_url` deprecated
- **2025-03-20** `dcd958492a63`: 2 breaking, 2 info
  - the response property `items/items/original_url` became nullable for the status `200`
  - the response property `items/items/original_url` became optional for the status `200`
  - api tag `catalogs` added
  - api tag `user_catalogs` removed

[Operation history](https://skmtc.dev/flox/apis/floxhub-catalog-server/changes/api/v1/catalog/catalogs/:catalog_name/packages/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.dev/flox/apis/floxhub-catalog-server/revisions/6731453cd7cd?raw)