2021-06-08 01:23:25 +05:30
---
stage: Package
group: Package
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.example/handbook/engineering/ux/technical-writing/#assignments
---
2021-11-11 11:23:49 +05:30
# npm API **(FREE)**
2021-06-08 01:23:25 +05:30
This is the API documentation for [npm Packages ](../../user/packages/npm_registry/index.md ).
WARNING:
This API is used by the [npm package manager client ](https://docs.npmjs.com/ )
and is not meant for manual consumption.
For instructions on how to upload and install npm packages from the GitLab
package registry, see the [npm package registry documentation ](../../user/packages/npm_registry/index.md ).
NOTE:
These endpoints do not adhere to the standard API authentication methods.
See the [npm package registry documentation ](../../user/packages/npm_registry/index.md )
for details on which headers and token types are supported.
## Download a package
Downloads the npm package. This URL is provided by the [metadata endpoint ](#metadata ).
```plaintext
GET projects/:id/packages/npm/:package_name/-/:file_name
```
| Attribute | Type | Required | Description |
| ----------------- | ------ | -------- | ----------- |
| `id` | string | yes | The ID or full path of the project. |
| `package_name` | string | yes | The name of the package. |
| `file_name` | string | yes | The name of the package file. |
```shell
curl --header "Authorization: Bearer < personal_access_token > " "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@my-scope/my-pkg-0.0.1.tgz"
```
Write the output to a file:
```shell
curl --header "Authorization: Bearer < personal_access_token > " "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@my-scope/my-pkg-0.0.1.tgz" >> @myscope/my -pkg-0.0.1.tgz
```
This writes the downloaded file to `@myscope/my-pkg-0.0.1.tgz` in the current directory.
## Upload a package file
Upload a package.
```plaintext
PUT projects/:id/packages/npm/:package_name
```
2021-11-11 11:23:49 +05:30
| Attribute | Type | Required | Description |
|----------------|--------|----------|-------------------------------------|
| `id` | string | yes | The ID or full path of the project. |
| `package_name` | string | yes | The name of the package. |
| `versions` | string | yes | Package version information. |
2021-06-08 01:23:25 +05:30
```shell
curl --request PUT
--header "Content-Type: application/json"
--data @./path/to/metadata/file.json
--header "Authorization: Bearer < personal_access_token > " \
"https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg"
```
The metadata file content is generated by npm, but looks something like this:
```json
{
"_attachments": {
"@myscope/my-pkg-1.3.7.tgz": {
"content_type": "application/octet-stream",
"data": "H4sIAAAAAAAAE+1TQUvDMBjdeb/iI4edZEldV2dPwhARPIjiyXlI26zN1iYhSeeK7L+bNJtednMg4l4OKe+9PF7DF0XzNS0ZVmEfr4wUgxODEJLEMRzjPRJyCYPJNCFRlCTE+dzH1PvJqYscQ2ss1a7KT3PCv8DX/kfwMQRAgjYMpYBuIoIzKtwy6MILG6YNl8Jr0XgyvgpswUyuubJ75TGMDuSaUcsKyDooa1C6De6G8t7GRcG2br4CGxKME3wDR1hmrLexvJKwQLdaS52CkOAFMIrlfMlZsUAwGgHbcgsRcid3fdqade9SFz7u9a1naGsrqX3gHbcPNINDyydWcmN1By+W19x2oU7NcyZMfwn3z/PAqTaruanmUix5+V3UXVKq9yEoRZW1yqQYl9zWNBvnssFUcbyJsdJyxXJrcHQdz8gsTg6PzGChGty3H+6Gvz0BZ5xxxn/FJ1EDRNIACAAA",
"length": 354
}
},
"_id": "@myscope/my-pkg",
"description": "Package created by me",
"dist-tags": {
"latest": "1.3.7"
},
"name": "@myscope/my-pkg",
"readme": "ERROR: No README data found!",
"versions": {
"1.3.7": {
"_id": "@myscope/my-pkg@1.3.7",
"_nodeVersion": "12.18.4",
"_npmVersion": "6.14.6",
"author": {
"name": "GitLab Package Registry Utility"
},
"description": "Package created by me",
"dist": {
"integrity": "sha512-loy16p+Dtw2S43lBmD3Nye+t+Vwv7Tbhv143UN2mwcjaHJyBfGZdNCTXnma3gJCUSE/AR4FPGWEyCOOTJ+ev9g==",
"shasum": "4a9dbd94ca6093feda03d909f3d7e6bd89d9d4bf",
"tarball": "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@myscope/my-pkg-1.3.7.tgz"
},
"keywords": [],
"license": "ISC",
"main": "index.js",
"name": "@myscope/my-pkg",
"publishConfig": {
"@myscope:registry": "https://gitlab.example.com/api/v4/projects/1/packages/npm"
},
"readme": "ERROR: No README data found!",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"version": "1.3.7"
}
}
}
```
## Route prefix
For the remaining routes, there are two sets of identical routes that each make requests in
different scopes:
- Use the instance-level prefix to make requests in the scope of the entire instance.
- 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.
### Instance-level
```plaintext
/packages/npm`
```
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id` | string | yes | The group ID or full group path. |
### Project-level
```plaintext
/projects/:id/packages/npm`
```
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id` | string | yes | The project ID or full project path. |
## Metadata
Returns the metadata for a given package.
```plaintext
GET < route-prefix > /:package_name
```
| Attribute | Type | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `package_name` | string | yes | The name of the package. |
```shell
curl --header "Authorization: Bearer < personal_access_token > " "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg"
```
Example response:
```json
{
"name": "@myscope/my-pkg",
"versions": {
"0.0.2": {
"name": "@myscope/my-pkg",
"version": "0.0.1",
"dist": {
"shasum": "93abb605b1110c0e3cca0a5b805e5cb01ac4ca9b",
"tarball": "https://gitlab.example.com/api/v4/projects/1/packages/npm/@myscope/my-pkg/-/@myscope/my-pkg-0.0.1.tgz"
}
}
},
"dist-tags": {
"latest": "0.0.1"
}
}
```
The URLs in the response have the same route prefix used to request them. If you request them with
the instance-level route, the returned URLs contain `/api/v4/packages/npm` .
## Dist-Tags
### List tags
> Introduced in GitLab 12.7.
Lists the dist-tags for the package.
```plaintext
GET < route-prefix > /-/package/:package_name/dist-tags
```
| Attribute | Type | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `package_name` | string | yes | The name of the package. |
```shell
curl --header "Authorization: Bearer < personal_access_token > " "https://gitlab.example.com/api/v4/projects/1/packages/npm/-/package/@myscope/my-pkg/dist-tags"
```
Example response:
```json
{
"latest": "2.1.1",
"stable": "1.0.0"
}
```
The URLs in the response have the same route prefix used to request them. If you request them with
the instance-level route, the returned URLs contain `/api/v4/packages/npm` .
### Create or update a tag
> Introduced in GitLab 12.7.
Create or update a dist-tag.
```plaintext
PUT < route-prefix > /-/package/:package_name/dist-tags/:tag
```
| Attribute | Type | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `package_name` | string | yes | The name of the package. |
| `tag` | string | yes | The tag to be created or updated. |
| `version` | string | yes | The version to be tagged. |
```shell
curl --request PUT --header "Authorization: Bearer < personal_access_token > " "https://gitlab.example.com/api/v4/projects/1/packages/npm/-/package/@myscope/my-pkg/dist-tags/stable"
```
This endpoint responds successfully with `204 No Content` .
### Delete a tag
> Introduced in GitLab 12.7.
Delete a dist-tag.
```plaintext
DELETE < route-prefix > /-/package/:package_name/dist-tags/:tag
```
| Attribute | Type | Required | Description |
| -------------- | ------ | -------- | ----------- |
| `package_name` | string | yes | The name of the package. |
| `tag` | string | yes | The tag to be created or updated. |
```shell
curl --request DELETE --header "Authorization: Bearer < personal_access_token > " "https://gitlab.example.com/api/v4/projects/1/packages/npm/-/package/@myscope/my-pkg/dist-tags/stable"
```
This endpoint responds successfully with `204 No Content` .
