---
title: "Resolve a list of Package Groups"
method: POST
path: "/api/v1/catalog/resolve"
tags: ["catalog"]
---

# Resolve a list of Package Groups

`POST /api/v1/catalog/resolve`

Resolves a list of package groups, each being a list of package descriptors.

Required Body:
- **groups**: An object with an `items` array of PackageGroups to resolve.

Optional Query Parameters:
- **candidate_pages**: Number of additional candidate pages to return
  (default: 0)

Returns:
- **ResolvedPackageGroups**: An object with an `items` array of
  `ResolvedPackageGroup` items.

Resolution Rules:
- Each `PackageGroup` is resolved independently.
- Each page that has packages meeting all descriptors in the group is
  returned.
- The latest complete page includes full package details.
- Additional candidate pages are returned without full details.

PackageDescriptor Fields:
- **install_id**: [required] Reference identifier for the package in the
  manifest. Used for error messages and result correlation.
- **attr_path**: [required] The nix attribute path to match exactly.
- **systems**: [required] List of systems to resolve for (e.g.,
  x86_64-linux).
- **version**: [optional] Version constraint. Can be a literal version or
  semver constraint. Packages whose version cannot be parsed as semver are
  excluded when using semver constraints.
- **derivation**: [optional] Specific derivation path to match.
- **allow_pre_releases**: [optional] Include pre-release versions when using
  semver constraints (default: False).
- **allow_broken**: [optional] Include packages marked as broken
  (default: False).
- **allow_unfree**: [optional] Include packages with unfree licenses
  (default: True).
- **allow_insecure**: [optional] Include packages marked as insecure
  (default: False).
- **allowed_licenses**: [optional] List of acceptable license identifiers.
- **allow_missing_builds**: [optional] Include packages without confirmed
  build artifacts (default: False). If resolution fails with this
  constraint, it may be relaxed with a warning message.

## Query parameters

- `candidate_pages` integer

## Request body

- PackageGroups
  - `items` PackageGroup[], required
    - `name` string, required
    - `stability` string, nullable
    - `descriptors` PackageDescriptor[], required
      - `install_id` string, required
      - `attr_path` string, required
      - `systems` PackageSystem[], required
      - `version` string, nullable
      - `allow_pre_releases` boolean, nullable
      - `allow_unfree` boolean, nullable
      - `allow_broken` boolean, nullable
      - `allow_insecure` boolean, nullable
      - `allowed_licenses` string[], nullable
      - `allow_missing_builds` boolean, nullable
      - `derivation` string, nullable

## Response `200`

A list of resolved package groups

- ResolvedPackageGroups
  - `items` ResolvedPackageGroup[], required
    - `name` string, required
    - `page` CatalogPage
      - `page` integer, required
      - `url` string, required
      - `packages` ResolvedPackageDescriptor[], nullable
        - `catalog` string, nullable
        - `attr_path` string, required
        - `pkg_path` string, required
        - `derivation` string, required
        - `name` string, required
        - `pname` string, required
        - `version` string, required
        - `system` 'aarch64-darwin' | 'aarch64-linux' | 'x86_64-darwin' | 'x86_64-linux' | 'invalid', required
        - `outputs` PackageOutput[], required
          - `name` string, required
          - `store_path` string, required
        - `outputs_to_install` string[], nullable, required
        - `description` string, nullable, required
        - `license` string, nullable, required
        - `locked_url` string, required
        - `rev` string, required
        - `rev_count` integer, required
        - `rev_date` string, date-time, required
        - `broken` boolean, nullable, required
        - `insecure` boolean, nullable, required
        - `unfree` boolean, nullable, required
        - `missing_builds` boolean, nullable, required
        - `stabilities` string[], nullable, required
        - `scrape_date` string, date-time, nullable, required
        - `cache_uri` string, nullable
        - `install_id` string, required
      - `messages` ResolutionMessageGeneral[], required
        - `level` 'trace' | 'info' | 'warning' | 'error', required
        - `type` 'general' | 'resolution_logic' | 'attr_path_not_found' | 'constraints_too_tight' | 'attr_path_not_found.not_in_catalog' | 'attr_path_not_found.systems_not_on_same_page' | 'attr_path_not_found.not_found_for_all_systems' | 'missing_builds' | 'unacceptable_licenses' | 'change_in_version_format' | 'unfree' | 'insecure' | 'broken' | 'version_not_found', required
        - `message` string, required
        - `context` object, required
      - `complete` boolean, required
    - `candidate_pages` CatalogPage[], nullable
      - `page` integer, required
      - `url` string, required
      - `packages` ResolvedPackageDescriptor[], nullable
        - `catalog` string, nullable
        - `attr_path` string, required
        - `pkg_path` string, required
        - `derivation` string, required
        - `name` string, required
        - `pname` string, required
        - `version` string, required
        - `system` 'aarch64-darwin' | 'aarch64-linux' | 'x86_64-darwin' | 'x86_64-linux' | 'invalid', required
        - `outputs` PackageOutput[], required
          - `name` string, required
          - `store_path` string, required
        - `outputs_to_install` string[], nullable, required
        - `description` string, nullable, required
        - `license` string, nullable, required
        - `locked_url` string, required
        - `rev` string, required
        - `rev_count` integer, required
        - `rev_date` string, date-time, required
        - `broken` boolean, nullable, required
        - `insecure` boolean, nullable, required
        - `unfree` boolean, nullable, required
        - `missing_builds` boolean, nullable, required
        - `stabilities` string[], nullable, required
        - `scrape_date` string, date-time, nullable, required
        - `cache_uri` string, nullable
        - `install_id` string, required
      - `messages` ResolutionMessageGeneral[], required
        - `level` 'trace' | 'info' | 'warning' | 'error', required
        - `type` 'general' | 'resolution_logic' | 'attr_path_not_found' | 'constraints_too_tight' | 'attr_path_not_found.not_in_catalog' | 'attr_path_not_found.systems_not_on_same_page' | 'attr_path_not_found.not_found_for_all_systems' | 'missing_builds' | 'unacceptable_licenses' | 'change_in_version_format' | 'unfree' | 'insecure' | 'broken' | 'version_not_found', required
        - `message` string, required
        - `context` object, required
      - `complete` boolean, required
    - `messages` ResolutionMessageGeneral[], required
      - `level` 'trace' | 'info' | 'warning' | 'error', required
      - `type` 'general' | 'resolution_logic' | 'attr_path_not_found' | 'constraints_too_tight' | 'attr_path_not_found.not_in_catalog' | 'attr_path_not_found.systems_not_on_same_page' | 'attr_path_not_found.not_found_for_all_systems' | 'missing_builds' | 'unacceptable_licenses' | 'change_in_version_format' | 'unfree' | 'insecure' | 'broken' | 'version_not_found', required
      - `message` string, required
      - `context` object, required

## Other responses

- `422` — Request validation error

---

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