Packages
The Packages API provides several pgutil commands (available as pgutil packages) and HTTP endpoints to query, download, publish, delete, and perform other operations on packages in package-based feeds, regardless of the package type.
pgutil Commands
All HTTP endpoints of the Packages API are available as pgutil commands.
To find the list of commands available in pgutil, simply run pgutil packages --help. See Getting started with pgutil to learn more.
Available HTTP Endpoints
- List Packages - lists the packages in a feed, filtered as specified
- List Package Versions - describes all versions of a package, filtered as specified
- Download Package - downloads a package file
- Upload Package - uploads a package file to a feed
- Delete Package - deletes a package from a feed
- Set Package Status - sets the listed or deprecated status of a specified package
- Repackage Package - repackages a package
- Promote Package - promotes a package
- Show Package Metadata - displays metadata about a package*
* Only available as a pgutil command.
The Packages API is available starting from ProGet 2023.0
With the exception of Repackage and Promote, these endpoints currently only work with packages stored in ProGet (i.e. local or cached packages). To query remote packages from connectors, you'll need to use the API specific to the feed type.
Also note that Maven, Docker, and Bower don't have "packages" like other feed types, and will not work with this API.
Authenticating to Packages API
The following is a summary of access types and their corresponding requirements for various API keys types and endpoints within this API.
| Access Type | Requirements |
|---|---|
| System API Keys | Use/Manage Feeds |
| Feed API Keys | View/Download is required for all endpointsAdd/Repackage is required for Upload Package and Repackage PackageOverwrite/Delete is required for Delete PackagePromote is required for Promote Package |
| Personal API Key | View & Download Packages is required for List Packages and List Package VersionsPublish Packages is required for Upload PackagePromote Packages is required for Promote PackageAdminister or Manage Feed is required for Delete Package, Set Package Status, and Repackage Package. These will also grant permissions for all other endpoints. |
| No API Key | anonymous or authenticated user must have at least View & Download Packages |
To specify an API Key, use the request header (X-ApiKey), querystring (key), or api:«api-key» as the username. See API Key Usage to learn more.
For example, to authenticate with the API key abc12345 to the query packages endpoint, you could specify the API key as follows:
curl -X GET --header "X-ApiKey: abc12345" "https://proget.corp.local/api/packages/MyNugetFeed/versions"
If the provided API key is either missing, unknown/incorrect or does not have permission, the following message is returned:
403 The specified API key does not have the proper permissions to perform this action.
Package Identifiers (Group/Name/Version vs Purl)
Endpoints that work with a single package version (e.g. downloading, deleting, etc.) require identifying a single version package using querystring parameters. This can be done by specifying multiple parameters (name and version, and sometimes group and qualifier) or a single parameter (purl).
Documentation Conventions
In the operations that require package version identifier, we will use «package-identifiers»to reference the one or multiple parameters that you can use.
Using Multiple Parameters to Identify a Package
Identifying a package version requires up to four different components, depending on the type of package.
| Argument | Details | Endpoints Used |
|---|---|---|
name |
the name/id of package to download | all |
version |
the version of package to download | all |
group |
used only by Universal and npm feeds; for npm, this is the "scope" with the the @ replaced by %40 |
query package version, query latest package, download package, delete package, set package status |
qualifier |
used by some feeds (like Debian and rubygems) for attributes like architecture | query package version, query latest package, download package, delete package, set package status |
To download version 12.3.1 of the @angular/animation package, you would need to construct a url as follows:
/api/packages/NpmFeed/download?group=angular&name=animation&version=12.3.1
To download version 3.9.2-3 of the python3 package with the amd64 architecture, you would need to construct a url as follows:
/api/packages/MyDebianFeed/download?group=main&name=python3&version=3.9.2-3&qualifier=arch%3Damd64
Using a Purl to Identify a Package
To simplify package identification, you can also specify a purl (i.e. Package Url) that is compatible across all package types. These work with any endpoint that works with a single package version (e.g. deleting, downloading, promoting, etc.)
To download version 12.3.1 of the @angular/animation package, you would need to construct a purl as follows:
/api/packages/NpmFeed/download?purl=pkg:npm/%40angular/animation@12.3.1
This follows the purl-spec, and you can also find it on the PackageVersion Object
Note: purl are intended for single package endpoints only, and cannot be used with endpoints that return multiple packages (e.g. list, list versions, etc.)