ContextQMD
Back to Gitlabhq

NuGet API

doc/api/packages/nuget.md

18.11.220.1 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Use this API to interact with the NuGet package manager client.

[!warning] This API is used by the NuGet package manager client and is generally not meant for manual consumption.

These endpoints do not adhere to the standard API authentication methods. See the NuGet package registry documentation for details on which headers and token types are supported. Undocumented authentication methods might be removed in the future.

Retrieve a package index

Retrieves the index for a specified package, which includes a list of available versions.

plaintext
GET projects/:id/packages/nuget/download/:package_name/index
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
package_namestringyesThe name of the package.
shell
curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"

Example response:

json
{
  "versions": [
    "1.3.0.17"
  ]
}

Download a package file

Downloads a specified NuGet package file for a project. The metadata service provides this URL.

plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
package_namestringyesThe name of the package.
package_versionstringyesThe version of the package.
package_filenamestringyesThe name of the file.
shell
curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg"

Write the output to a file:

shell
curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/mynugetpkg.1.3.0.17.nupkg" > MyNuGetPkg.1.3.0.17.nupkg

This writes the downloaded file to MyNuGetPkg.1.3.0.17.nupkg in the current directory.

[!note] This API returns a 404 status when you use group endpoints. Use the NuGet package manager CLI to install packages with group endpoints to avoid this error.

Upload a package file

{{< history >}}

{{< /history >}}

Uploads a NuGet package file for a specified project.

  • For NuGet v3 feed:

    plaintext
    PUT projects/:id/packages/nuget

  • For NuGet V2 feed:

    plaintext
    PUT projects/:id/packages/nuget/v2
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
package_namestringyesThe name of the package.
package_versionstringyesThe version of the package.
package_filenamestringyesThe name of the file.

  • For NuGet v3 feed:

    shell
    curl --request PUT \
    --form 'package=@path/to/mynugetpkg.1.3.0.17.nupkg' \
    --user <username>:<personal_access_token> \
    --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/"

  • For NuGet v2 feed:

    shell
    curl --request PUT \
    --form 'package=@path/to/mynugetpkg.1.3.0.17.nupkg' \
    --user <username>:<personal_access_token> \
    --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2"

Upload a symbol package file

Uploads a specified NuGet symbol package file (.snupkg) for a project.

plaintext
PUT projects/:id/packages/nuget/symbolpackage
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
package_namestringyesThe name of the package.
package_versionstringyesThe version of the package.
package_filenamestringyesThe name of the file.
shell
curl --request PUT \
     --form 'package=@path/to/mynugetpkg.1.3.0.17.snupkg' \
     --user <username>:<personal_access_token> \
     --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolpackage"

Route prefix

For the remaining routes, there are two sets of identical routes that each make requests in different scopes:

  • Use the group-level prefix to make requests in a group's scope.
  • Use the project-level prefix to make requests in a single project's scope.

The examples in this document all use the project-level prefix.

Group-level

plaintext
/groups/:id/-/packages/nuget
AttributeTypeRequiredDescription
idstringyesThe group ID or full group path.

Project-level

plaintext
/projects/:id/packages/nuget
AttributeTypeRequiredDescription
idstringyesThe project ID or full project path.

Service Index

V2 source feed/protocol

Retrieves an XML document that represents the service index of the v2 NuGet source feed. Authentication is not required.

plaintext
GET <route-prefix>/v2

Example Request:

shell
curl "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2"

Example response:

xml
<?xml version="1.0" encoding="utf-8"?>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom" xml:base="https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2">
  <workspace>
    <atom:title type="text">Default</atom:title>
    <collection href="Packages">
      <atom:title type="text">Packages</atom:title>
    </collection>
  </workspace>
</service>

V3 source feed/protocol

{{< history >}}

  • Changed to be public in GitLab 16.1.

{{< /history >}}

Retrieves a list of available API resources. Authentication is not required.

plaintext
GET <route-prefix>/index

Example Request:

shell
curl --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/index"

Example response:

json
{
  "version": "3.0.0",
  "resources": [
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query",
      "@type": "SearchQueryService",
      "comment": "Filter and search for packages by keyword."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query",
      "@type": "SearchQueryService/3.0.0-beta",
      "comment": "Filter and search for packages by keyword."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query",
      "@type": "SearchQueryService/3.0.0-rc",
      "comment": "Filter and search for packages by keyword."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata",
      "@type": "RegistrationsBaseUrl",
      "comment": "Get package metadata."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata",
      "@type": "RegistrationsBaseUrl/3.0.0-beta",
      "comment": "Get package metadata."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata",
      "@type": "RegistrationsBaseUrl/3.0.0-rc",
      "comment": "Get package metadata."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download",
      "@type": "PackageBaseAddress/3.0.0",
      "comment": "Get package content (.nupkg)."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget",
      "@type": "PackagePublish/2.0.0",
      "comment": "Push and delete (or unlist) packages."
    },
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolpackage",
      "@type": "SymbolPackagePublish/4.9.0",
      "comment": "Push symbol packages."
    }
  ]
}

The URLs in the response have the same route prefix used to request them. If you request them with the group-level route, the returned URLs contain /groups/:id/-.

Retrieve package metadata

Retrieves metadata for a specified package.

plaintext
GET <route-prefix>/metadata/:package_name/index
AttributeTypeRequiredDescription
package_namestringyesThe name of the package.
shell
curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/index"

Example response:

json
{
  "count": 1,
  "items": [
    {
      "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
      "lower": "1.3.0.17",
      "upper": "1.3.0.17",
      "count": 1,
      "items": [
        {
          "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
          "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
          "catalogEntry": {
            "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
            "authors": "Author1, Author2",
            "dependencyGroups": [],
            "id": "MyNuGetPkg",
            "version": "1.3.0.17",
            "tags": "",
            "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
            "description": "Description of the package",
            "summary": "Description of the package",
            "published": "2023-05-08T17:23:25Z",
          }
        }
      ]
    }
  ]
}

Retrieve version metadata

Retrieves metadata for a specified package version.

plaintext
GET <route-prefix>/metadata/:package_name/:package_version
AttributeTypeRequiredDescription
package_namestringyesThe name of the package.
package_versionstringyesThe version of the package.
shell
curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17"

Example response:

json
{
  "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
  "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
  "catalogEntry": {
    "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
    "authors": "Author1, Author2",
    "dependencyGroups": [],
    "id": "MyNuGetPkg",
    "version": "1.3.0.17",
    "tags": "",
    "packageContent": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/1.3.0.17/helloworld.1.3.0.17.nupkg",
    "description": "Description of the package",
    "summary": "Description of the package",
    "published": "2023-05-08T17:23:25Z",
  }
}

Search for packages

Searches for NuGet packages in the repository based on a specified query.

plaintext
GET <route-prefix>/query
AttributeTypeRequiredDescription
qstringyesThe search query.
skipintegernoThe number of results to skip.
takeintegernoThe number of results to return.
prereleasebooleannoInclude prerelease versions. Defaults to true if no value is supplied.
shell
curl --user <username>:<personal_access_token> \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/query?q=MyNuGet"

Example response:

json
{
  "totalHits": 1,
  "data": [
    {
      "@type": "Package",
      "authors": "Author1, Author2",
      "id": "MyNuGetPkg",
      "title": "MyNuGetPkg",
      "description": "Description of the package",
      "summary": "Description of the package",
      "totalDownloads": 0,
      "verified": true,
      "version": "1.3.0.17",
      "versions": [
        {
          "@id": "https://gitlab.example.com/api/v4/projects/1/packages/nuget/metadata/MyNuGetPkg/1.3.0.17.json",
          "version": "1.3.0.17",
          "downloads": 0
        }
      ],
      "tags": ""
    }
  ]
}

Delete a package

{{< history >}}

{{< /history >}}

Deletes a specified NuGet package.

plaintext
DELETE projects/:id/packages/nuget/:package_name/:package_version
AttributeTypeRequiredDescription
idstringyesThe ID or full path of the project.
package_namestringyesThe name of the package.
package_versionstringyesThe version of the package.
shell
curl --request DELETE \
     --user <username>:<personal_access_token> \
     --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/MyNuGetPkg/1.3.0.17"

Possible request responses:

StatusDescription
204Package deleted
401Unauthorized
403Forbidden
404Not found

Download a debugging symbol file .pdb

{{< history >}}

{{< /history >}}

Downloads a specified debugging symbol file (.pdb).

plaintext
GET <route-prefix>/symbolfiles/:file_name/:signature/:file_name
AttributeTypeRequiredDescription
file_namestringyesThe name of the file.
signaturestringyesThe signature of the file.
SymbolchecksumstringyesRequired header. The checksum of the file.
shell
curl --header "Symbolchecksum: SHA256:<file_checksum>" \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolfiles/:file_name/:signature/:file_name"

Write the output to a file:

shell
curl --header "Symbolchecksum: SHA256:<file_checksum>" \
  --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/symbolfiles/mynugetpkg.pdb/k813f89485474661234z7109cve5709eFFFFFFFF/mynugetpkg.pdb" > mynugetpkg.pdb

Possible request responses:

StatusDescription
200File downloaded
400Bad request
403Forbidden
404Not found

V2 Feed Metadata Endpoints

{{< history >}}

  • Introduced in GitLab 16.3.

{{< /history >}}

$metadata endpoint

Authentication is not required. Returns metadata for a V2 feed available endpoints:

plaintext
GET <route-prefix>/v2/$metadata
shell
curl --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2/$metadata"

Example response:

xml
<edmx:Edmx xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" Version="1.0">
  <edmx:DataServices xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:DataServiceVersion="2.0" m:MaxDataServiceVersion="2.0">
    <Schema xmlns="http://schemas.microsoft.com/ado/2006/04/edm" Namespace="NuGetGallery.OData">
      <EntityType Name="V2FeedPackage" m:HasStream="true">
        <Key>
          <PropertyRef Name="Id"/>
          <PropertyRef Name="Version"/>
        </Key>
        <Property Name="Id" Type="Edm.String" Nullable="false"/>
        <Property Name="Version" Type="Edm.String" Nullable="false"/>
        <Property Name="Authors" Type="Edm.String"/>
        <Property Name="Dependencies" Type="Edm.String"/>
        <Property Name="Description" Type="Edm.String"/>
        <Property Name="DownloadCount" Type="Edm.Int64" Nullable="false"/>
        <Property Name="IconUrl" Type="Edm.String"/>
        <Property Name="Published" Type="Edm.DateTime" Nullable="false"/>
        <Property Name="ProjectUrl" Type="Edm.String"/>
        <Property Name="Tags" Type="Edm.String"/>
        <Property Name="Title" Type="Edm.String"/>
        <Property Name="LicenseUrl" Type="Edm.String"/>
      </EntityType>
    </Schema>
    <Schema xmlns="http://schemas.microsoft.com/ado/2006/04/edm" Namespace="NuGetGallery">
      <EntityContainer Name="V2FeedContext" m:IsDefaultEntityContainer="true">
        <EntitySet Name="Packages" EntityType="NuGetGallery.OData.V2FeedPackage"/>
        <FunctionImport Name="FindPackagesById" ReturnType="Collection(NuGetGallery.OData.V2FeedPackage)" EntitySet="Packages">
          <Parameter Name="id" Type="Edm.String" FixedLength="false" Unicode="false"/>
        </FunctionImport>
      </EntityContainer>
    </Schema>
  </edmx:DataServices>
</edmx:Edmx>

OData package entry endpoints

{{< history >}}

{{< /history >}}

EndpointDescription
GET projects/:id/packages/nuget/v2/Packages()?$filter=(tolower(Id) eq '<package_name>')Returns an OData XML document containing information about the package with the given name.
GET projects/:id/packages/nuget/v2/FindPackagesById()?id='<package_name>'Returns an OData XML document containing information about the package with the given name.
GET projects/:id/packages/nuget/v2/Packages(Id='<package_name>',Version='<package_version>')Returns an OData XML document containing information about the package with the given name and version.
shell
curl --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2/Packages(Id='mynugetpkg',Version='1.0.0')"

Example response:

xml
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2">
    <id>https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2/Packages(Id='mynugetpkg',Version='1.0.0')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
    <title type="text">mynugetpkg</title>
    <content type="application/zip" src="https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/mynugetpkg/1.0.0/mynugetpkg.1.0.0.nupkg"/>
    <m:properties>
      <d:Version>1.0.0</d:Version>
    </m:properties>
 </entry>

[!note] GitLab doesn't receive an authentication token for the Packages() and FindPackagesByID() endpoints, so the latest version of the package cannot be returned. You must provide the version when you install or upgrade a package with the NuGet v2 feed.

shell
curl --url "https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2/Packages()?$filter=(tolower(Id) eq 'mynugetpkg')"

Example response:

xml
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xml:base="https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2">
    <id>https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2/Packages(Id='mynugetpkg',Version='')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
    <title type="text">mynugetpkg</title>
    <content type="application/zip" src="https://gitlab.example.com/api/v4/projects/1/packages/nuget/v2"/>
    <m:properties>
      <d:Version></d:Version>
    </m:properties>
 </entry>