catalog

Resolve a list of Package Groups

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.

post/api/v1/catalog/resolve

Query parameters

candidate_pagesinteger

Request body

Example request

{
  "items": [
    {
      "descriptors": [
        {
          "attr_path": "curl",
          "install_id": "curl",
          "systems": [
            "x86_64-linux"
          ]
        },
        {
          "attr_path": "slack",
          "install_id": "slack",
          "systems": [
            "x86_64-linux"
          ]
        },
        {
          "attr_path": "xorg.xeyes",
          "install_id": "xeyes",
          "systems": [
            "x86_64-linux"
          ]
        }
      ],
      "name": "test"
    }
  ]
}

Response

A list of resolved package groups

Example response

{
  "items": [
    {
      "candidate_pages": [],
      "messages": [],
      "name": "test",
      "page": {
        "complete": true,
        "messages": [],
        "packages": [
          {
            "attr_path": "curl",
            "broken": false,
            "catalog": "nixpkgs",
            "derivation": "/nix/store/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-curl-8.5.0.drv",
            "description": "A command line tool for transferring files with URL syntax",
            "insecure": false,
            "install_id": "curl",
            "license": "curl",
            "locked_url": "https://github.com/flox/nixpkgs?rev=abc123def456",
            "missing_builds": false,
            "name": "curl-8.5.0",
            "outputs": [
              {
                "name": "out",
                "store_path": "/nix/store/bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb-curl-8.5.0"
              },
              {
                "name": "man",
                "store_path": "/nix/store/cccccccccccccccccccccccccccccccc-curl-8.5.0-man"
              }
            ],
            "outputs_to_install": [
              "out",
              "man"
            ],
            "pkg_path": "curl",
            "pname": "curl",
            "rev": "abc123def456",
            "rev_count": 12345,
            "rev_date": "2024-01-15T00:00:00Z",
            "scrape_date": "2024-01-15T00:00:00Z",
            "stabilities": [
              "stable"
            ],
            "system": "x86_64-linux",
            "unfree": false,
            "version": "8.5.0"
          }
        ],
        "page": 1,
        "url": "https://github.com/flox/nixpkgs?rev=abc123def456"
      }
    }
  ]
}

Changes

Changed in 23 of the 53 revisions of this API.485152

Aug 27, 20268ec561551880511See the full diff
- ▲
  the // response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  removed the required property /// from the response with the status
  response-required-property-removed
- ▲
  removed the required property /// from the response with the status
  response-required-property-removed
- ▲
  removed the required property /// from the response with the status
  response-required-property-removed
- ▲
  removed the required property /// from the response with the status
  response-required-property-removed
- ●
  removed the optional property /// from the response with the status
  response-optional-property-removed
- ○
  added to the // response property allOf list for the response status
  response-property-all-of-added
Aug 19, 20263541e86c7ef93See the full diff
- ●
  added the new archived enum value to the ////// response property for the response status
  response-property-enum-value-added
- ●
  added the new archived enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new archived enum value to the ///// response property for the response status
  response-property-enum-value-added
Nov 19, 2025e0ce91a85d9512See the full diff
- ●
  added the new broken enum value to the ////// response property for the response status
  response-property-enum-value-added
- ●
  added the new broken enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new broken enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new insecure enum value to the ////// response property for the response status
  response-property-enum-value-added
- ●
  added the new insecure enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new insecure enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new unfree enum value to the ////// response property for the response status
  response-property-enum-value-added
- ●
  added the new unfree enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new unfree enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new version_not_found enum value to the ////// response property for the response status
  response-property-enum-value-added
- ●
  added the new version_not_found enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new version_not_found enum value to the ///// response property for the response status
  response-property-enum-value-added
Jul 23, 202529c059f1823a1See the full diff
- ○
  the endpoint scheme security HTTPBasic was added to the API
  api-security-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jun 6, 2025eff897b30ae211See the full diff
- ●
  removed the optional property // from the response with the status
  response-optional-property-removed
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Jun 5, 2025820177159d9824See the full diff
- ●
  added the new resolution_logic enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new resolution_logic enum value to the ///// response property for the response status
  response-property-enum-value-added
- ○
  added the new optional query request parameter candidate_pages
  new-optional-request-parameter
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  removed the resolution_trace enum value from the //// response property for the response status
  response-property-enum-value-removed
- ○
  removed the resolution_trace enum value from the ///// response property for the response status
  response-property-enum-value-removed
Jun 3, 20252a00861f8e6b1See the full diff
- ○
  the request property default value false was removed
  request-property-default-value-removed
Mar 19, 2025dcd958492a6312See the full diff
- ▲
  the response property ///// became nullable for the status
  response-property-became-nullable
- ●
  added the new change_in_version_format enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new change_in_version_format enum value to the ///// response property for the response status
  response-property-enum-value-added
Feb 10, 2025b1a16c027df342See the full diff
- ●
  added the new missing_builds enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new missing_builds enum value to the ///// response property for the response status
  response-property-enum-value-added
- ●
  added the new unacceptable_licenses enum value to the //// response property for the response status
  response-property-enum-value-added
- ●
  added the new unacceptable_licenses enum value to the ///// response property for the response status
  response-property-enum-value-added
- ○
  added the new optional request property ////
  new-optional-request-property
- ○
  added the required property ///// to the response with the status
  response-required-property-added
Jan 15, 2025e11930b30d051See the full diff
- ○
  added the required property ///// to the response with the status
  response-required-property-added

Full history (23 revisions)