NuGet API

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

This is the API documentation for NuGet Packages.

WARNING: This API is used by the NuGet package manager client and is generally not meant for manual consumption.

For instructions on how to upload and install NuGet packages from the GitLab Package Registry, see the NuGet package registry documentation.

NOTE: 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.

Package index

Returns the index for a given package, which includes a list of available versions:

GET projects/:id/packages/nuget/download/:package_name/index

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the project.
`package_name`	string	yes	The name of the package.

curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"

Example response:

{
  "versions": [
    "1.3.0.17"
  ]
}

Download a package file

Download a NuGet package file. The metadata service provides this URL.

GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the project.
`package_name`	string	yes	The name of the package.
`package_version`	string	yes	The version of the package.
`package_filename`	string	yes	The name of the file.

curl --user <username>:<personal_access_token> "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:

curl --user <username>:<personal_access_token> "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.

Upload a package file

Introduced in GitLab 16.2 for NuGet v2 feed.

Upload a NuGet package file:

For NuGet v3 feed:
```
PUT projects/:id/packages/nuget
```
For NuGet V2 feed:
```
PUT projects/:id/packages/nuget/v2
```

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the project.
`package_name`	string	yes	The name of the package.
`package_version`	string	yes	The version of the package.
`package_filename`	string	yes	The name of the file.

For NuGet v3 feed:

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

For NuGet v2 feed:

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

Upload a symbol package file

Upload a NuGet symbol package file (.snupkg):

PUT projects/:id/packages/nuget/symbolpackage

Attribute	Type	Required	Description
`id`	string	yes	The ID or full path of the project.
`package_name`	string	yes	The name of the package.
`package_version`	string	yes	The version of the package.
`package_filename`	string	yes	The name of the file.

curl --request PUT \
     --form 'package=@path/to/mynugetpkg.1.3.0.17.snupkg' \
     --user <username>:<personal_access_token> \
     "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

/groups/:id/-/packages/nuget

Attribute	Type	Required	Description
`id`	string	yes	The group ID or full group path.

Project-level

/projects/:id/packages/nuget

Attribute	Type	Required	Description
`id`	string	yes	The project ID or full project path.

Service Index

V2 source feed/protocol

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

curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```0

Example Request:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```1

Example response:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```2

### V3 source feed/protocol

> - [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/214674) to be public in GitLab 16.1.

Returns a list of available API resources.
Authentication is not required:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```3

Example Request:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```4

Example response:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```5

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/-`.

## Metadata Service

Returns metadata for a package:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```6

| Attribute      | Type   | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `package_name` | string | yes      | The name of the package. |

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```7

Example response:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```8

## Version Metadata Service

Returns metadata for a specific package version:

```shell
curl --user <username>:<personal_access_token> "https://gitlab.example.com/api/v4/projects/1/packages/nuget/download/MyNuGetPkg/index"
```9

| Attribute         | Type   | Required | Description |
| ----------------- | ------ | -------- | ----------- |
| `package_name`    | string | yes      | The name of the package.    |
| `package_version` | string | yes      | The version of the package. |

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

Example response:

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

## Search Service

Given a query, search for NuGet packages in the repository:

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

| Attribute    | Type    | Required | Description |
| ------------ | ------- | -------- | ----------- |
| `q`          | string  | yes      | The search query. |
| `skip`       | integer | no       | The number of results to skip. |
| `take`       | integer | no       | The number of results to return. |
| `prerelease` | boolean | no       | Include prerelease versions. Defaults to `true` if no value is supplied. |

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

Example response:

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

## Delete service

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/38275) in GitLab 16.5.

Delete a NuGet package:

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

| Attribute         | Type   | Required | Description |
| ----------------- | ------ | -------- | ----------- |
| `id`              | string | yes      | The ID or full path of the project. |
| `package_name`    | string | yes      | The name of the package. |
| `package_version` | string | yes      | The version of the package. |

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

Possible request responses:

| Status | Description |
| ------ | ----------- |
| `204`  | Package deleted |
| `401`  | Unauthorized |
| `403`  | Forbidden |
| `404`  | Not found |

## Download a debugging symbol file `.pdb`

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/416178) in GitLab 16.7.

Download a debugging symbol file (`.pdb`):

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

| Attribute         | Type   | Required | Description |
| ----------------- | ------ | -------- | ----------- |
| `file_name`       | string | yes      | The name of the file. |
| `signature`       | string | yes      | The signature of the file. |
| `Symbolchecksum` | string | yes      | Required header. The checksum of the file. |

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

Write the output to a file:

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

Possible request responses:

| Status | Description |
| ------ | ----------- |
| `200`  | File downloaded |
| `400`  | Bad request |
| `403`  | Forbidden |
| `404`  | Not found |

## V2 Feed Metadata Endpoints

> - Introduced in GitLab 16.3.

### $metadata endpoint

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

```plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
```0

```plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
```1

Example response:

```plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
```2

### OData package entry endpoints

> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127667) in GitLab 16.4.

| Endpoint | Description |
| -------- | ----------- |
| `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. |

```plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
```3

Example response:

```plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
```4

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.

```plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
```5

Example response:

```plaintext
GET projects/:id/packages/nuget/download/:package_name/:package_version/:package_filename
```6