Introduction

This is unofficial documentation for both NuGet V2 and V3 HTTP package source protocol.

A package source is either V2 or V3. V1 package sources are not covered here.

Historically, the NuGet HTTP protocol has not been documented and has been an implementation detail between the official NuGet client (e.g. nuget.exe) and NuGet.org. As time went on, the HTTP protocol was closely inspected by parties outside of the NuGet team with the goal of providing alternate package sources and client implementations.

Because the protocol was never clearly documented, there are many subtle quirks between different server implementations. This document is an attempt to explain all of the HTTP endpoints available.

“Retro-specing” is the operative term!

Disclaimer

This is unofficial documentation and is still a work in progress. Although I am on the NuGet team, I am by no means the owner of the NuGet protocol. This document is meant for informational purposes and should not be seen at the protocol specification.

See the logo on this page? Yeah.

Terminology

A NuGet package is an archive containing some metadata and some assets. Typically these assets are .NET assemblies that a .NET project can consume (often through Visual Studio). However, there are packages used for other things including but certainly not limited to:

native dependencies (e.g. SQLite)
JavaScript (e.g. jQuery)
CSS (e.g. Bootstrap)
Windows applications (e.g. Firefox, via Chocolatey)
deployment packages (via Octopus Deploy)
And certainly many other creative things!

However, NuGet packages have these attributes:

Having the .nupkg file extension
Being a Zip archive in disguise
Containing a .nuspec in the root of the archive
Having an ID
Having a version number

The package ID is a human-readable string that package consumers configure into their projects or tooling so that the package can be fetched from their packages sources. The package ID is a case-insensitive string, although there are some quirks when it comes to casing.

The package version is SemVer 1.0.0 version string (although SemVer 2.0.0 support is coming). As a package changes over time, the package version is changes to reflect this but the package ID stays the same. Equivalency of two version strings in general is defined by the SemVer specification. However, NuGet package versions can have a fourth integer in the version number (to align with System.Version) and comparison is done in a case-insensitive manner. The best definition

The identity of a package is the two-tuple of package ID and package version. This pair is meant to unambiguously allow a package to be retrieved from a package source.

A package source is a collection of HTTP endpoints that allow a NuGet client to discover, download, and fetch metadata about NuGet packages. Each package source has a root URL that is configured into the client allowing all endpoints within the package source to be inferred based on the root URL.

The V3 protocol is the latest version of the package source protocol. Its data responses are serialized using JSON and has a built in mechanism for versioning of existing endpoints and addition of new endpoints. A V3 package source URL must end in index.json.

The V2 protocol is more widely supported by third party server implementations. Its data responses are serialized using XML. It looks a lot like an OData Version 2.0 feed but there are quirks and limitations on a V2 package source that are typically not there on an OData endpoint.

Quirks

Since the NuGet HTTP protocol was never documented in detail, it’s not always useful to make unqualified, firm statements in this document. For this reason, there will yellow notices when quirks or differences between server or client implementations should be noted. For example:

Where possible, any different behavior between client or server implementation will be enumerated and explained. To make the explanation of different implementations more terse, the following abbreviations will be used:

Quirk Abbreviations

Abbreviation	Implementation
MY	MyGet
NG	NuGetGallery (NuGet.org)
NS2	NuGet.Server on WCF
NS3	NuGet.Server on Web API
VS	Visual Studio Team Services (VSTS)

Authentication

Roles

There are typically two different roles when interacting with a package source:

reader: able to discover and download packages.
writer: able to upload and delete packages.

Some server implementations give the writer role access to all packages on the source. Other implementations only give access to the package IDs which were originally uploaded by that author.

NuGet.org, NuGet.Server, MyGet

The reader role is assigned to anonymous users. A caller can download any package from NuGet.org without providing any form of credentials.

The writer role authentication and authorization is achieved using the X-NuGet-ApiKey HTTP header.

Visual Studio Team Services (VSTS)

Authentication to VSTS is typically done using personal access tokens (PAT).

The reader role is assigned to users with read access to the package feed and who are using a PAT that has the “Packaging (read)”, “Packaging (read and write)” or “Packaging (read, write, and manage)” scope.

The writer role is assigned to users with write access to the package feed and who are using a PAT that has the “Packaging (read and write)” or “Packaging (read, write, and manage)” scope.

The X-NuGet-ApiKey is required by the protocol but is ignored by VSTS since all authentication and authorization information is contained in the PAT.

V2 Protocol

Package entity

At the core of the V2 protocol is the OData package entity. A single package entity is represented by a <entry> element. A collection of package entities is represented by a <feed> element with zero or more <entry> child elements.

The identity (i.e. key) of the package entity is the Id and Version properties.

Properties from `<entry>`

The following elements are available on every known server implementation.

Element	Description
`<id>`, text content	URL to get metadata about a single package
`<content>`, `src` attribute	URL to download the .nupkg
`<summary>`, text content	Summary only when Summary is defined
`<author>`, `<name>` children	Authors, split into multiple values

The following properties vary from one server implementation to the next.

Element	Description	Availability
`<title>` as the ID, text content	ID of the package	NG, NS2, NS3, VS
`<title>` as the Title, text content	Title of the package	MY
`<summmay>` defaulting to Description	Only when Summary is not defined	MY
`<summary>` with no text content	Only when Summary is not defined	NS2
No `<summary>` element at all	Only when Summary is not defined	NG, NS3, VS

Properties from `<m:properties>`

These values are available under the <m:properties> element (a direct child of the <entry> element). The types are OData primitive data types.

The following elements are available on every known server implementation.

Element	Type
`<d:Copyright>`	Edm.String
`<d:Dependencies>`	Edm.String
`<d:Description>`	Edm.String
`<d:DownloadCount>`	Edm.Int32
`<d:IconUrl>`	Edm.String
`<d:IsAbsoluteLatestVersion>`	Edm.Boolean
`<d:IsLatestVersion>`	Edm.Boolean
`<d:IsPrerelease>`	Edm.Boolean
`<d:Language>`	Edm.String
`<d:LicenseUrl>`	Edm.String
`<d:MinClientVersion>`	Edm.String
`<d:NormalizedVersion>`	Edm.String
`<d:PackageSize>`	Edm.Int64
`<d:ProjectUrl>`	Edm.String
`<d:ReleaseNotes>`	Edm.String
`<d:RequireLicenseAcceptance>`	Edm.Boolean
`<d:Tags>`	Edm.String
`<d:Title>`	Edm.String
`<d:Version>`	Edm.String

The following properties vary from one server implementation to the next.

Element	Type	Availability
`<d:Authors>`	Edm.String	NG NS3 VS
`<d:Created>`	Edm.DateTime	MY NG VS
`<d:DevelopmentDependency>`	Edm.Boolean	NS2 NS3
`<d:GalleryDetailsUrl>`	Edm.String	MY NG
`<d:Id>`	Edm.String	MY NG NS3 VS
`<d:LastEdited>`	Edm.DateTime	MY NG VS
`<d:LastUpdated>`	Edm.DateTime	NG NS3 VS
`<d:LicenseNames>`	Edm.String	MY NG
`<d:LicenseReportUrl>`	Edm.String	MY NG
`<d:Listed>`	Edm.Boolean	NS2 NS3 VS
`<d:Owners>`	Edm.String	NS2 NS3
`<d:PackageHash>`	Edm.String	MY NG NS2 NS3
`<d:PackageHashAlgorithm>`	Edm.String	MY NG NS2 NS3
`<d:Published>`	Edm.DateTime	MY NG NS3 VS
`<d:ReportAbuseUrl>`	Edm.String	MY NG
`<d:Summary>`	Edm.String	NG NS2 NS3 VS
`<d:VersionDownloadCount>`	Edm.Int32	MY NG NS2 NS3

Client recommendations

Downloading .nupkgs

Tthe src attribute of the <content> element (a direct child element within the <entry>) is the URL to where the package (.nupkg file) can be downloaded. This download URL has no specific pattern. Clients should discover .nupkg URLs by inspecting the XML <content> element for the desired package and should not depend on the URLs having a particular structure.

Determining the package ID

Unfortunately, NuGet.Server on WCF (and perhaps other server implementations) do not include the ID in the <m:properties> element. All other server implementations do. To work around this, use the following algorithm to determine a package’s ID.

Check for the <d:Id> element under <d:properties>.
If it exists, use the text content found there.
If it does not exist, use the text content found under the <title> element (found under the <entry> element).

It may be tempting to parse the ID out of the URL found in the <id> element. However, this is not guaranteed to have SemVer 2.0.0 build metadata.

OData parameters

OData supports a number of standard query parameters to manipulate the result set.

Name	Required	Description
$filter	false	Used to determine if a package should be in the result set
$orderby	false	Used to sort the result set
$select	false	Used to return a subset of properties on each package.
$skip	false	Used for paging across the result set
$top	false	Used for paging across the result set

The query parameters have varying support across different endpoints and server implementations.

TODO: Document support for $count, $format, $expand, $inlinecount, etc.

Endpoint: push package

POST /nuget HTTP/1.1
Host: example.com
X-NuGet-ApiKey: meowmeow
Content-Length: 35195

(bytes of the .nupkg)

Invoke-WebRequest `
  -Method PUT `
  -Uri http://example.com/nuget/ `
  -InFile Kittens.1.2.0-beta.nupkg `
  -Headers @{ "X-NuGet-ApiKey" = "meowmeow" }

The above command returns a response like this:

HTTP/1.1 201 Created
Content-Length: 0
Date: Sat, 18 Feb 2017 17:04:18 GMT

This endpoint is used to add new packages and replace existing packages. The identity (package ID and version) of the package being pushed is defined in the .nuspec of uploaded package.

Server	Supports package replace
NuGetGallery	no
NuGet.Server	no, unless `allowOverrideExistingPackageOnPush` is set to `true`
MyGet	yes, unless “Forbid overwriting of existing packages?” package setting is enabled
VSTS	no

HTTP Request

PUT http://example.com/nuget

NuGetGallery accepts POST requests in addition to PUT.

Headers

Name	Required	Description
X-NuGet-ApiKey	true	The API key used to authenticate the caller.

Request Body

The request body can come in one of two forms.

Multipart Form Data

The request header Content-Type is multipart/form-data and the first item in the response body is the raw bytes of the .nupkg being pushed. Subsequent items in the multipart body are ignored.

Raw Bytes

If the response body is not multipart/form-data, the entire request body is assumed to be the raw bytes of the .nupkg being pushed.

Response

Status Code	Meaning
201 Created	The package has been successfully uploaded
400 Bad Request	The package in the request body could not be extracted or has invalid metadata
401 Unauthorized	The provided API key or credentials are not valid
403 Forbidden	The provided API key or credentials does not have write access to the provided package ID
409 Conflict	A package with the provided identity already exists

TODO: document which server implementations return what status codes.

The official NuGet client treats all 200-level responses as success and everything else as a failure.

Endpoint: delete package

DELETE /nuget/Kittens/1.2.0-beta HTTP/1.1
Host: example.com
X-NuGet-ApiKey: meowmeow

Invoke-WebRequest `
  -Method DELETE `
  -Uri http://example.com/nuget/Kittens/1.2.0-beta `
  -Headers @{ "X-NuGet-ApiKey" = "meowmeow" }

The above command returns a response like this:

HTTP/1.1 204 No Content
Content-Length: 0
Date: Sat, 18 Feb 2017 17:04:18 GMT

This endpoint is used to delete an existing package. Server implementations are allowed to implement the delete operation either as complete package removal or as the unlist operation.

Server	Delete or unlist
NuGetGallery	unlist
NuGet.Server	delete, unless `enableDelisting` is set to `true`

TODO: document MyGet and VSTS

HTTP Request

DELETE http://example.com/nuget/{package ID}/{package version}

URL Parameters

Name	Required	Description
{package ID}	true	The ID of the package to be deleted
{package version}	true	The version of the package to be deleted

Headers

Name	Required	Description
`X-NuGet-ApiKey`	true	The API key used to authenticate the caller.

Response

Status Code	Meaning
204 No Content	The package was successfully deleted or unlisted
404 Bad Request	The provided package identity does not exist
401 Unauthorized	The provided API key or credentials are not valid
403 Forbidden	The provided API key or credentials does not have write access to the provided package ID

TODO: document which server implementations return what status codes.

The official NuGet client treats all 200-level responses as success and everything else as a failure.

Endpoint: enumerate packages

GET /nuget/Packages()?$filter=IsAbsoluteLatestVersion&$orderby=Id&$skip=4&$top=1 HTTP/1.1
Host: example.com

Invoke-WebRequest `
  -Uri http://example.com/nuget/Packages()?$filter=IsAbsoluteLatestVersion&$orderby=Id&$skip=4&$top=2

The above command returns an XML response like this:

HTTP/1.1 200 OK
Content-Length: 3724
Content-Type: application/atom+xml;type=feed;charset=utf-8
Date: Sat, 18 Feb 2017 17:04:18 GMT

<?xml version="1.0" encoding="UTF-8"?>
<feed 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="http://example.com/nuget">
  <id>http://schemas.datacontract.org/2004/07/</id>
  <title />
  <updated>2017-02-18T21:38:03Z</updated>
  <link rel="self" href="http://example.com/nuget/Packages" />
  <entry>
    <id>http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
    <link rel="self" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
    <title type="text">Kittens</title>
    <updated>2017-02-07T09:28:34Z</updated>
    <author>
      <name>joelverhagen</name>
    </author>
    <content type="application/zip" src="http://example.com/nuget/package/Kittens/1.2.0-beta" />
    <m:properties>
      <d:Version>1.2.0-beta</d:Version>
      <d:NormalizedVersion>1.2.0-beta</d:NormalizedVersion>
      <d:Copyright m:null="true" />
      <d:Dependencies />
      <d:Description>Descriptions are important!</d:Description>
      <d:DownloadCount m:type="Edm.Int32">27</d:DownloadCount>
      <d:IconUrl m:null="true" />
      <d:IsLatestVersion m:type="Edm.Boolean">false</d:IsLatestVersion>
      <d:IsAbsoluteLatestVersion m:type="Edm.Boolean">true</d:IsAbsoluteLatestVersion>
      <d:IsPrerelease m:type="Edm.Boolean">true</d:IsPrerelease>
      <d:Language m:null="true" />
      <d:PackageSize m:type="Edm.Int64">4103</d:PackageSize>
      <d:ProjectUrl m:null="true" />
      <d:ReleaseNotes m:null="true" />
      <d:RequireLicenseAcceptance m:type="Edm.Boolean">false</d:RequireLicenseAcceptance>
      <d:Tags m:null="true" />
      <d:Title m:null="true" />
      <d:MinClientVersion m:null="true" />
      <d:LicenseUrl m:null="true" />
    </m:properties>
  </entry>
  <entry>
    <id>http://example.com/nuget/Packages(Id='Puppies',Version='0.1.0')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" href="http://example.com/nuget/Packages(Id='Puppies',Version='0.1.0')" />
    <link rel="self" href="http://example.com/nuget/Packages(Id='Puppies',Version='0.1.0')" />
    <title type="text">Puppies</title>
    <updated>2017-02-07T09:28:34Z</updated>
    <author>
      <name>joelverhagen</name>
    </author>
    <content type="application/zip" src="http://example.com/nuget/package/Puppies/0.1.0" />
    <m:properties>
      <d:Version>0.1.0</d:Version>
      <d:NormalizedVersion>0.1.0</d:NormalizedVersion>
      <d:Copyright m:null="true" />
      <d:Dependencies />
      <d:Description />
      <d:DownloadCount m:type="Edm.Int32">2</d:DownloadCount>
      <d:IconUrl m:null="true" />
      <d:IsLatestVersion m:type="Edm.Boolean">true</d:IsLatestVersion>
      <d:IsAbsoluteLatestVersion m:type="Edm.Boolean">true</d:IsAbsoluteLatestVersion>
      <d:IsPrerelease m:type="Edm.Boolean">false</d:IsPrerelease>
      <d:Language m:null="true" />
      <d:PackageSize m:type="Edm.Int64">8309</d:PackageSize>
      <d:ProjectUrl m:null="true" />
      <d:ReleaseNotes m:null="true" />
      <d:RequireLicenseAcceptance m:type="Edm.Boolean">false</d:RequireLicenseAcceptance>
      <d:Tags m:null="true" />
      <d:Title m:null="true" />
      <d:MinClientVersion m:null="true" />
      <d:LicenseUrl m:null="true" />
    </m:properties>
  </entry>
</feed>

This endpoint is used to enumerate all packages available on the V2 package source.

HTTP Request

GET http://example.com/nuget/Packages

Query Parameters

Name	Required
`$filter`	false
`$orderby`	false
`$select`	false
`$skip`	false
`$top`	false

TODO: document the availability for these parameters.

Note the NuGet.org has implemented filtering on specific combinations of OData query parameters.

Response

The response body is an XML document containing a collection of package entities. There can be zero or more package entities.

TODO: document when the URL to the next page is available.

Status Code	Meaning
200 OK	The result set has been returned
400 Bad Request	The parameter values are invalid or the set of parameters is not supported

Endpoint: get a single package

GET /nuget/Packages(Id='Kittens',Version='1.2.0-beta') HTTP/1.1
Host: example.com

Invoke-WebRequest `
  -Uri http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')

The above command returns an XML response like this:

HTTP/1.1 200 OK
Content-Length: 1905
Content-Type: application/atom+xml;type=feed;charset=utf-8
Date: Sat, 18 Feb 2017 17:04:18 GMT

<?xml version="1.0" encoding="UTF-8"?>
<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="http://example.com/nuget">
  <id>http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')</id>
  <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
  <link rel="edit" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
  <link rel="self" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
  <title type="text">Kittens</title>
  <updated>2017-02-07T09:28:34Z</updated>
  <author>
    <name>joelverhagen</name>
  </author>
  <content type="application/zip" src="http://example.com/nuget/package/Kittens/1.2.0-beta" />
  <m:properties>
    <d:Version>1.2.0-beta</d:Version>
    <d:NormalizedVersion>1.2.0-beta</d:NormalizedVersion>
    <d:Copyright m:null="true" />
    <d:Dependencies />
    <d:Description>Descriptions are important!</d:Description>
    <d:DownloadCount m:type="Edm.Int32">27</d:DownloadCount>
    <d:IconUrl m:null="true" />
    <d:IsLatestVersion m:type="Edm.Boolean">false</d:IsLatestVersion>
    <d:IsAbsoluteLatestVersion m:type="Edm.Boolean">true</d:IsAbsoluteLatestVersion>
    <d:IsPrerelease m:type="Edm.Boolean">true</d:IsPrerelease>
    <d:Language m:null="true" />
    <d:PackageSize m:type="Edm.Int64">4103</d:PackageSize>
    <d:ProjectUrl m:null="true" />
    <d:ReleaseNotes m:null="true" />
    <d:RequireLicenseAcceptance m:type="Edm.Boolean">false</d:RequireLicenseAcceptance>
    <d:Tags m:null="true" />
    <d:Title m:null="true" />
    <d:MinClientVersion m:null="true" />
    <d:LicenseUrl m:null="true" />
  </m:properties>
</entry>

This endpoint is used to fetch metadata about a single package.

HTTP Request

GET http://example.com/nuget/Packages(Id='{package ID}',Version='{package version}')

URL Parameters

Name	Required	Description
{package ID}	true	The ID of the package fetched
{package version}	true	The version of the package to be fetched

TODO: document what OData query parameters are supported

Response

The response body is an XML document containing a single package entity.

Status Code	Meaning
200 OK	The package exists and the metadata has been returned
404 Not Found	No package with the provided package ID and version exists

Endpoint: find packages by ID

GET /nuget/FindPackagesById()?id='Kittens' HTTP/1.1
Host: example.com

Invoke-WebRequest `
  -Uri http://example.com/nuget/FindPackagesById()?id='Kittens'

The above command returns an XML response like this:

HTTP/1.1 200 OK
Content-Length: 3823
Content-Type: application/atom+xml;type=feed;charset=utf-8
Date: Sat, 18 Feb 2017 17:04:18 GMT

<?xml version="1.0" encoding="UTF-8"?>
<feed 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="http://example.com/nuget">
  <id>http://schemas.datacontract.org/2004/07/</id>
  <title />
  <updated>2017-02-18T21:38:03Z</updated>
  <link rel="self" href="http://example.com/nuget/Packages" />
  <entry>
    <id>http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
    <link rel="self" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
    <title type="text">Kittens</title>
    <updated>2017-02-07T09:28:34Z</updated>
    <author>
      <name>joelverhagen</name>
    </author>
    <content type="application/zip" src="http://example.com/nuget/package/Kittens/1.2.0-beta" />
    <m:properties>
      <d:Version>1.2.0-beta</d:Version>
      <d:NormalizedVersion>1.2.0-beta</d:NormalizedVersion>
      <d:Copyright m:null="true" />
      <d:Dependencies />
      <d:Description>Descriptions are important!</d:Description>
      <d:DownloadCount m:type="Edm.Int32">27</d:DownloadCount>
      <d:IconUrl m:null="true" />
      <d:IsLatestVersion m:type="Edm.Boolean">false</d:IsLatestVersion>
      <d:IsAbsoluteLatestVersion m:type="Edm.Boolean">false</d:IsAbsoluteLatestVersion>
      <d:IsPrerelease m:type="Edm.Boolean">true</d:IsPrerelease>
      <d:Language m:null="true" />
      <d:PackageSize m:type="Edm.Int64">4103</d:PackageSize>
      <d:ProjectUrl m:null="true" />
      <d:ReleaseNotes m:null="true" />
      <d:RequireLicenseAcceptance m:type="Edm.Boolean">false</d:RequireLicenseAcceptance>
      <d:Tags m:null="true" />
      <d:Title m:null="true" />
      <d:MinClientVersion m:null="true" />
      <d:LicenseUrl m:null="true" />
    </m:properties>
  </entry>  
  <entry>
    <id>http://example.com/nuget/Packages(Id='Kittens',Version='1.3.0')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.3.0')" />
    <link rel="self" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.3.0')" />
    <title type="text">Kittens</title>
    <updated>2017-02-07T09:28:34Z</updated>
    <author>
      <name>joelverhagen</name>
    </author>
    <content type="application/zip" src="http://example.com/nuget/package/Kittens/1.3.0" />
    <m:properties>
      <d:Version>1.3.0</d:Version>
      <d:NormalizedVersion>1.3.0</d:NormalizedVersion>
      <d:Copyright m:null="true" />
      <d:Dependencies />
      <d:Description>Descriptions are important! Especially when a package releases a stable version.</d:Description>
      <d:DownloadCount m:type="Edm.Int32">739</d:DownloadCount>
      <d:IconUrl m:null="true" />
      <d:IsLatestVersion m:type="Edm.Boolean">true</d:IsLatestVersion>
      <d:IsAbsoluteLatestVersion m:type="Edm.Boolean">true</d:IsAbsoluteLatestVersion>
      <d:IsPrerelease m:type="Edm.Boolean">false</d:IsPrerelease>
      <d:Language m:null="true" />
      <d:PackageSize m:type="Edm.Int64">4431</d:PackageSize>
      <d:ProjectUrl m:null="true" />
      <d:ReleaseNotes m:null="true" />
      <d:RequireLicenseAcceptance m:type="Edm.Boolean">false</d:RequireLicenseAcceptance>
      <d:Tags m:null="true" />
      <d:Title m:null="true" />
      <d:MinClientVersion m:null="true" />
      <d:LicenseUrl m:null="true" />
    </m:properties>
  </entry>
  <link rel="next" href="http://example.com/nuget/FindPackagesById()?id=%27Kittens%27&$skip=2" />
</feed>

This endpoint is used to enumerate all versions of a given package ID.

HTTP Request

GET http://example.com/nuget/FindPackagesById()?id='{package ID}'

Query Parameters

Name	Required	Description
`id`	true	Package ID to fetch all of the versions. Note that the ID must be surrounded in single quotes.

Name	Required	Availability
`$filter`	false	MY, NG, NS2, NS3, VS
`$orderby`	false	MY, NG, NS2, NS3
`$select`	false	MY, NG (bug), NS2, NS3
`$skip`	false	MY, NG, NS2, NS3
`$top`	false	MY, NG, NS2, NS3

Response

The response body is an XML document containing a collection of package entities. There can be zero or more package entities. If the package ID does not exist on the package source, an empty result set is returned.

For large result sets (packages that have many versions), a <link rel="next" href="..." /> element can be returned. This should be followed to fetch the next set of results.

Status Code	Meaning
200 OK	The result set has been returned
404 Bad Request	The provided set of query parameters is not valid or not supported

Endpoint: search for packages

GET /nuget/Search()?searchTerm='kittens'&targetFramework=''&includePrerelease=true HTTP/1.1
Host: example.com

Invoke-WebRequest `
  -Uri http://example.com/nuget/Search()?searchTerm='kittens'&targetFramework=''&includePrerelease=true

The above command returns an XML response like this:

HTTP/1.1 200 OK
Content-Length: 3823
Content-Type: application/atom+xml;type=feed;charset=utf-8
Date: Sat, 18 Feb 2017 17:04:18 GMT

<?xml version="1.0" encoding="UTF-8"?>
<feed 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="http://example.com/nuget">
  <id>http://schemas.datacontract.org/2004/07/</id>
  <title />
  <updated>2017-02-18T21:38:03Z</updated>
  <link rel="self" href="http://example.com/nuget/Packages" />
  <entry>
    <id>http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
    <link rel="self" href="http://example.com/nuget/Packages(Id='Kittens',Version='1.2.0-beta')" />
    <title type="text">Kittens</title>
    <updated>2017-02-07T09:28:34Z</updated>
    <author>
      <name>joelverhagen</name>
    </author>
    <content type="application/zip" src="http://example.com/nuget/package/Kittens/1.2.0-beta" />
    <m:properties>
      <d:Version>1.2.0-beta</d:Version>
      <d:NormalizedVersion>1.2.0-beta</d:NormalizedVersion>
      <d:Copyright m:null="true" />
      <d:Dependencies />
      <d:Description>Descriptions are important!</d:Description>
      <d:DownloadCount m:type="Edm.Int32">27</d:DownloadCount>
      <d:IconUrl m:null="true" />
      <d:IsLatestVersion m:type="Edm.Boolean">false</d:IsLatestVersion>
      <d:IsAbsoluteLatestVersion m:type="Edm.Boolean">false</d:IsAbsoluteLatestVersion>
      <d:IsPrerelease m:type="Edm.Boolean">true</d:IsPrerelease>
      <d:Language m:null="true" />
      <d:PackageSize m:type="Edm.Int64">4103</d:PackageSize>
      <d:ProjectUrl m:null="true" />
      <d:ReleaseNotes m:null="true" />
      <d:RequireLicenseAcceptance m:type="Edm.Boolean">false</d:RequireLicenseAcceptance>
      <d:Tags m:null="true" />
      <d:Title m:null="true" />
      <d:MinClientVersion m:null="true" />
      <d:LicenseUrl m:null="true" />
    </m:properties>
  </entry>
  <entry>
    <id>http://example.com/nuget/Packages(Id='Puppies',Version='0.1.0')</id>
    <category term="V2FeedPackage" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
    <link rel="edit" href="http://example.com/nuget/Packages(Id='Puppies',Version='0.1.0')" />
    <link rel="self" href="http://example.com/nuget/Packages(Id='Puppies',Version='0.1.0')" />
    <title type="text">Puppies</title>
    <updated>2017-02-07T09:28:34Z</updated>
    <author>
      <name>joelverhagen</name>
    </author>
    <content type="application/zip" src="http://example.com/nuget/package/Puppies/0.1.0" />
    <m:properties>
      <d:Version>0.1.0</d:Version>
      <d:NormalizedVersion>0.1.0</d:NormalizedVersion>
      <d:Copyright m:null="true" />
      <d:Dependencies />
      <d:Description>A package that is definitely not about kittens.</d:Description>
      <d:DownloadCount m:type="Edm.Int32">2</d:DownloadCount>
      <d:IconUrl m:null="true" />
      <d:IsLatestVersion m:type="Edm.Boolean">true</d:IsLatestVersion>
      <d:IsAbsoluteLatestVersion m:type="Edm.Boolean">true</d:IsAbsoluteLatestVersion>
      <d:IsPrerelease m:type="Edm.Boolean">false</d:IsPrerelease>
      <d:Language m:null="true" />
      <d:PackageSize m:type="Edm.Int64">8309</d:PackageSize>
      <d:ProjectUrl m:null="true" />
      <d:ReleaseNotes m:null="true" />
      <d:RequireLicenseAcceptance m:type="Edm.Boolean">false</d:RequireLicenseAcceptance>
      <d:Tags m:null="true" />
      <d:Title m:null="true" />
      <d:MinClientVersion m:null="true" />
      <d:LicenseUrl m:null="true" />
    </m:properties>
  </entry>
  <link rel="next" href="http://example.com/nuget/FindPackagesById()?id=%27Kittens%27&$skip=2" />
</feed>

This endpoint is used to search package metadata for an arbitrary search term. This is the primary method used to discovery packages on a package source.

HTTP Request

GET http://example.com/nuget/Search()?searchTerm='{search term}'&targetFramework='{target frameworks}'&includePrerelease={true | false}

Query Parameters

Name	Required	Description
`searchTerm`	true	The search term to look for in package metadata
`targetFramework`	true	Zero or more target framework monikers, seperated by `
`includePrerelease`	true	`true` or `false` dictating whether prerelease packages should be included in the output

In general, the searchTerm is tokenized (typically by whitespace) and used to match terms found in a package’s title, ID, description, and tags. What set of fields are searched and how the search term is tokenized varies greatly from one server implementation to the next.

In the example to the right, the Puppies package is matched because its description contains the search term “kittens”.

TODO: document the availability of the standard OData parameters

Response

The response body is an XML document containing a collection of package entities. There can be zero or more package entities. If the search term, target monikers, or prerelease flag eliminate all results, an empty result set is returned.

For large result sets (packages that have many versions), a <link rel="next" href="..." /> element can be returned. This should be followed to fetch the next set of results.

Status Code	Meaning
200 OK	The result set has been returned
404 Bad Request	A required parameter is missing or the provided set of query parameters is not valid or not supported

Introduction

Disclaimer

Terminology

Quirks

Quirk Abbreviations

Authentication

Roles

NuGet.org, NuGet.Server, MyGet

Visual Studio Team Services (VSTS)

V2 Protocol

Package entity

Properties from <entry>

Properties from <m:properties>

Client recommendations

Downloading .nupkgs

Determining the package ID

OData parameters

Endpoint: push package

HTTP Request

Headers

Request Body

Multipart Form Data

Raw Bytes

Response

Endpoint: delete package

HTTP Request

URL Parameters

Headers

Response

Endpoint: enumerate packages

HTTP Request

Query Parameters

Response

Endpoint: get a single package

HTTP Request

URL Parameters

Response

Endpoint: find packages by ID

HTTP Request

Query Parameters

Response

Endpoint: search for packages

HTTP Request

Query Parameters

Response

Properties from `<entry>`

Properties from `<m:properties>`