NPM Registry API

Overview

Schema
Client Errors
Authentication
Package
User
Search
Token
Trend

Schema

All API access is over HTTPS or HTTP, and accessed from the registry.npmjs.org domain. All data is sent and received as JSON.

$ curl -i https://registry.npmjs.org

HTTP/1.1 200 OK

{
  "db_name": "registry",
  "doc_count": 123772,
  "doc_del_count": 377,
  "update_seq": 685591,
  "purge_seq": 0,
  "compact_running": false,
  "disk_size": 634187899,
  "data_size": 445454185,
  "instance_start_time": "1420670152481614",
  "disk_format_version": 6,
  "committed_update_seq": 685591
}

Client Errors

Status: 4xx

{
  "error": "error_name",
  "reason": "error reason string"
}

Authentication

There are two ways to authenticate through the API.

Basic Authentication

$ curl -u "username:password" https://registry.npmjs.org

Bearer Authentication

$ curl -H "Authorization: Bearer ${UUId}" https://registry.npmjs.org

Failed login limit

$ curl -i -X "GET" -u "foo:pwd" \
    "https://registry.npmjs.com/-/user/org.couchdb.user:npm-user-service-testuser?write=true"

HTTP/1.1 401 Unauthorized

{"error":"unauthorized","reason":"Name or password is incorrect."}

Package

Read
Write

Get a single package

GET /:package

Response 200

HTTP/1.1 200 OK
Etag: "8UDCP753LFXOG42NMX88JAN40"

{
  "_id": "pedding",
  "_rev": "11-e6d1e6e96eaf72433fef6aaabe843af8",
  "name": "pedding",
  "description": "Just pedding for callback.",
  "dist-tags": {
    "latest": "1.0.0"
  },
  "versions": {
    "1.0.0": {
      "name": "pedding",
      "version": "1.0.0",
      "description": "Just pedding for callback.",
      "main": "index.js",
      "scripts": {
        "test": "make test-all"
      },
      "repository": {
        "type": "git",
        "url": "git://github.com/fengmk2/pedding.git"
      },
      "keywords": [
        "pedding",
        "callback"
      ],
      "devDependencies": {
        "contributors": "*",
        "mocha": "*",
        "mocha-phantomjs": "*",
        "component": "*",
        "chai": "*"
      },
      "author": {
        "name": "fengmk2",
        "email": "fengmk2@gmail.com"
      },
      "license": "MIT",
      "contributors": [
        {
          "name": "fengmk2",
          "email": "fengmk2@gmail.com",
          "url": "https://github.com/fengmk2"
        },
        {
          "name": "dead-horse",
          "email": "dead_horse@qq.com",
          "url": "https://github.com/dead-horse"
        }
      ],
      "gitHead": "b42a708414a704336e9dee570a963e2dbe43e529",
      "bugs": {
        "url": "https://github.com/fengmk2/pedding/issues"
      },
      "homepage": "https://github.com/fengmk2/pedding",
      "_id": "pedding@1.0.0",
      "_shasum": "7f5098d60307b4ef7240c3d693cb20a9473c6074",
      "_from": ".",
      "_npmVersion": "1.4.13",
      "_npmUser": {
        "name": "fengmk2",
        "email": "fengmk2@gmail.com"
      },
      "maintainers": [
        {
          "name": "fengmk2",
          "email": "fengmk2@gmail.com"
        },
        {
          "name": "dead-horse",
          "email": "dead_horse@qq.com"
        }
      ],
      "dist": {
        "shasum": "7f5098d60307b4ef7240c3d693cb20a9473c6074",
        "tarball": "http://registry.npmjs.org/pedding/-/pedding-1.0.0.tgz"
      },
      "directories": {}
    }
  },
  "readme": "# pedding\n readme...",
  "maintainers": [
    {
      "name": "fengmk2",
      "email": "fengmk2@gmail.com"
    },
    {
      "name": "dead-horse",
      "email": "dead_horse@qq.com"
    },
    {
      "name": "dead_horse",
      "email": "dead_horse@qq.com"
    }
  ],
  "time": {
    "modified": "2014-07-05T14:22:53.849Z",
    "created": "2012-09-18T14:46:08.346Z",
    "0.0.1": "2012-09-18T14:46:21.321Z",
    "0.0.2": "2013-06-22T08:26:45.125Z",
    "0.0.3": "2013-07-02T15:20:34.707Z",
    "1.0.0": "2014-07-05T11:08:51.614Z"
  },
  "author": {
    "name": "fengmk2",
    "email": "fengmk2@gmail.com"
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/fengmk2/pedding.git"
  },
  "keywords": [
    "pedding",
    "callback"
  ],
  "bugs": {
    "url": "https://github.com/fengmk2/pedding/issues"
  },
  "license": "MIT",
  "readmeFilename": "README.md",
  "homepage": "https://github.com/fengmk2/pedding",
  "contributors": [
    {
      "name": "fengmk2",
      "email": "fengmk2@gmail.com",
      "url": "https://github.com/fengmk2"
    },
    {
      "name": "dead-horse",
      "email": "dead_horse@qq.com",
      "url": "https://github.com/dead-horse"
    }
  ],
  "_attachments": {}
}

Response 404

HTTP/1.1 404 Object Not Found

{
  "error": "not_found",
  "reason": "document not found"
}

Get a special version or tag package

deprecated

GET /:package/:tag_or_version

Reponse 200

HTTP/1.1 200 OK
Etag: "1WJ4JF535RO3BDZR2BARXSGLY"
Content-Type: application/json
Cache-Control: max-age=60
Content-Length: 1183

{
  "name": "pedding",
  "version": "1.0.0",
  "description": "Just pedding for callback.",
  "main": "index.js",
  "scripts": {
    "test": "make test-all"
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/fengmk2/pedding.git"
  },
  "keywords": [
    "pedding",
    "callback"
  ],
  "devDependencies": {
    "contributors": "*",
    "mocha": "*",
    "mocha-phantomjs": "*",
    "component": "*",
    "chai": "*"
  },
  "author": {
    "name": "fengmk2",
    "email": "fengmk2@gmail.com"
  },
  "license": "MIT",
  "contributors": [
    {
      "name": "fengmk2",
      "email": "fengmk2@gmail.com",
      "url": "https://github.com/fengmk2"
    },
    {
      "name": "dead-horse",
      "email": "dead_horse@qq.com",
      "url": "https://github.com/dead-horse"
    }
  ],
  "gitHead": "b42a708414a704336e9dee570a963e2dbe43e529",
  "bugs": {
    "url": "https://github.com/fengmk2/pedding/issues"
  },
  "homepage": "https://github.com/fengmk2/pedding",
  "_id": "pedding@1.0.0",
  "_shasum": "7f5098d60307b4ef7240c3d693cb20a9473c6074",
  "_from": ".",
  "_npmVersion": "1.4.13",
  "_npmUser": {
    "name": "fengmk2",
    "email": "fengmk2@gmail.com"
  },
  "maintainers": [
    {
      "name": "fengmk2",
      "email": "fengmk2@gmail.com"
    },
    {
      "name": "dead-horse",
      "email": "dead_horse@qq.com"
    }
  ],
  "dist": {
    "shasum": "7f5098d60307b4ef7240c3d693cb20a9473c6074",
    "tarball": "http://registry.npmjs.org/pedding/-/pedding-1.0.0.tgz"
  },
  "directories": {}
}

Publish a new package

Authentication required.

PUT /:package

Input

{
  "_id": "pedding",
  "name": "pedding",
  "description": "Just pedding for callback.",
  "dist-tags": {
    "latest": "1.0.0"
  },
  "versions": {
    "1.0.0": {
      "name": "pedding",
      "version": "1.0.0",
      "description": "Just pedding for callback.",
      "main": "index.js",
      "scripts": {
        "test": "make test-all"
      },
      "repository": {
        "type": "git",
        "url": "git://github.com/fengmk2/pedding.git"
      },
      "keywords": [ "pedding","callback" ],
      "devDependencies": {
        "contributors": "*",
        "mocha": "*",
        "mocha-phantomjs": "*",
        "component": "*",
        "chai": "*"
      },
      "dependencies": {},
      "author": {
        "name": "fengmk2",
        "email": "fengmk2@gmail.com"
      },
      "license": "MIT",
      "contributors": [
        {
          "name": "fengmk2",
          "email": "fengmk2@gmail.com",
          "url": "https://github.com/fengmk2"
        },
        {
          "name": "dead-horse",
          "email": "dead_horse@qq.com",
          "url": "https://github.com/dead-horse"
        }
      ],
      "readme": "# pedding ...",
      "readmeFilename": "README.md",
      "gitHead": "b42a708414a704336e9dee570a963e2dbe43e529",
      "bugs": {
        "url": "https://github.com/fengmk2/pedding/issues"
      },
      "homepage": "https://github.com/fengmk2/pedding",
      "_id": "pedding@1.0.0",
      "_shasum": "7f5098d60307b4ef7240c3d693cb20a9473c6074",
      "_from": ".",
      "_npmVersion": "1.5.0-alpha-4",
      "_npmUser": {
        "name": "admin",
        "email": "fengmk2@gmail.com"
      },
      "maintainers": [
        {
          "name": "admin",
          "email": "fengmk2@gmail.com"
        }
      ],
      "dist": {
        "shasum": "7f5098d60307b4ef7240c3d693cb20a9473c6074",
        "tarball": "https://registry.npmjs.org/pedding/-/pedding-1.0.0.tgz"
      }
    }
  },
  "readme": "# pedding ...",
  "maintainers": [
    {
      "name": "admin",
      "email": "fengmk2@gmail.com"
    }
  ],
  "_attachments": {
    "pedding-1.0.0.tgz":{
      "content_type": "application/octet-stream",
      "data": "H4sIAAAAAAAAA+0aa3PbNjKf8Su...",
      "length": 2107
    }
  }
}

Response

Status: 201 Created

{
  "ok": true,
  "rev": "11-e6d1e6e96eaf72433fef6aaabe843af8"
}

Update a package's tag

Authentication required.

PUT /:package/:tag

Input

The total input body is the version string which's setting to the tag.

"1.0.0"

Response

Status: 201 Created

{
  "ok": true
}

Update a package's maintainers

Authentication required.

PUT /:package/-rev/:rev

Input

{
  "_id": "pedding",
  "_rev": "11-e6d1e6e96eaf72433fef6aaabe843af8",
  "maintainers":[
    { "name": "fengmk2", "email": "fengmk2@gmail.com" },
    { "name": "dead-horse", "email": "dead_horse@qq.com" }
  ]
}

Response

Status: 201 Created

{
  "ok": true,
  "id": "pedding",
  "rev": "12-bb300a90c9aeb779748b83ec1b744039"
}

Remove one version from package

Authentication required.
In any delete, note that the version number still cannot be reused.

PUT /:package/-rev/:rev

Input

Remove that specific version from the versions hash in the PUT body.

Example for removing 0.0.1 version:

{
  "_id": "pedding",
  "_rev": "12-bb300a90c9aeb779748b83ec1b744039",
  "name": "pedding",
  "description": "desc",
  "dist-tags": { "latest": "1.0.0" },
  "maintainers":
   [ ... ],
  "time":
   { ... },
  "users": {},
  "author": { ... },
  "repository": { ... },
  "versions":
   { "1.0.0":
      { ... },
     "0.0.3":
      { ... },
     "0.0.2":
      { ... } },
  "readme": "...",
  "homepage": "https://github.com/fengmk2/pedding",
  "bugs": { ... },
  "license": "MIT" }

Response

Status: 201 Created

{
  "ok": true
}

Remove all versions of a package

Authentication required.
In any delete, note that the version number still cannot be reused.

DELETE /:package/-rev/:rev

Response

Status: 201 Created

{
  "ok": true
}

Remove a tgz file from package

Authentication required.

DELETE /:tgzfilepath/-rev/:rev

Exmaple for removing https://registry.npmjs.org/pedding/-/pedding-0.0.1.tgz file:

DELETE /pedding/-/pedding-0.0.1.tgz/-rev/12-bb300a90c9aeb779748b83ec1b744039

Response

Status: 200 OK

{
  "ok": true
}

List packages since from a update time

GET /-/all/since?stale=update_after&startkey=:startkey

startkey is a ms timestamp

Response

$ curl -i "https://registry.npmjs.org/-/all/since?stale=update_after&startkey=1407255748643"

HTTP/1.1 200 OK

{
  "_updated": 1407255883282,
  "bacon-and-eggs": {
    "name": "bacon-and-eggs",
    "description": "A functional reactive Twitter API client in node",
    "dist-tags": {
      "latest": "0.0.4"
    },
    "maintainers": [
      {
        "name": "mikegroseclose",
        "email": "mike.groseclose@gmail.com"
      }
    ],
    "homepage": "http://github.com/mikegroseclose/bacon-and-eggs",
    "keywords": [
      "twitter",
      "api",
      "frp",
      "functional",
      "reactive",
      "bacon",
      "eggs",
      "oauth",
      "stream",
      "streams"
    ],
    "repository": {
      "type": "git",
      "url": "git://github.com/mikegroseclose/gulp-regex-replace.git"
    },
    "author": {
      "name": "Mike Groseclose",
      "email": "mike.groseclose@gmail.com",
      "url": "http://mikegroseclose.com"
    },
    "bugs": {
      "url": "https://github.com/mikegroseclose/gulp-regex-replace/issues"
    },
    "readmeFilename": "README.md",
    "time": {
      "modified": "2014-08-05T16:21:17.041Z"
    },
    "versions": {
      "0.0.4": "latest"
    }
  },
  "git-perm-rm": {
    "name": "git-perm-rm",
    "description": "Permanently remove a file or directory from a git repo including all related commit records.",
    "dist-tags": {
      "latest": "1.0.1"
    },
    "maintainers": [
      {
        "name": "kael",
        "email": "i@kael.me"
      }
    ],
    "homepage": "https://github.com/kaelzhang/git-perm-rm",
    "keywords": [
      "git",
      "rm",
      "git-perm-rm",
      "remove",
      "permanently"
    ],
    "repository": {
      "type": "git",
      "url": "git://github.com/kaelzhang/git-perm-rm.git"
    },
    "author": {
      "name": "Kael"
    },
    "bugs": {
      "url": "https://github.com/kaelzhang/git-perm-rm/issues"
    },
    "license": "MIT",
    "readmeFilename": "README.md",
    "time": {
      "modified": "2014-08-05T16:22:41.253Z"
    },
    "versions": {
      "1.0.1": "latest"
    }
  }
}

List package names by users

GET /-/by-user/$username[|$another1[|$another2...]]

username user name like fengmk2
also support multi users by name1|name2|name3

Response

$ curl -i "https://registry.npmjs.org/-/by-user/czy88840616"
$ curl -i "https://registry.npmjs.org/-/by-user/czy88840616|fengmk2|dead-horse"

HTTP/1.1 200 OK

{
  "czy88840616": [
    "easyconf",
    "egg",
    "flag",
    "gdp",
    "generator-webx-vm",
    "magic-cube",
    "rim",
    "tbuild",
    "test-publish",
    "velocity-parser",
    "vmarket",
    "wi"
  ]
}

User

Auth user
Get a single user
Add a new user
Update a exists user

Auth user

Authentication required.

GET /-/user/org.couchdb.user::username?write=true

Response 200

HTTP/1.1 200 OK
ETag: "5-a31b61ba3c50b50f7fcaf185e079e17a"

{
  "_id": "org.couchdb.user:npm-user-service-testuser",
  "_rev": "5-a31b61ba3c50b50f7fcaf185e079e17a",
  "password_scheme": "pbkdf2",
  "iterations": 10,
  "name": "npm-user-service-testuser",
  "email": "fengmk2@gmail.com",
  "type": "user",
  "roles": [],
  "date": "2015-01-04T08:28:51.378Z",
  "password_scheme": "pbkdf2",
  "iterations": 10,
  "derived_key": "644157c126b93356e6eba2c59fdf1b7ec644ebf2",
  "salt": "5d13874c0aa10751e35743bacd6eedd5"
}

Response 401

HTTP/1.1 401 Unauthorized

{
  "error": "unauthorized",
  "reason": "Name or password is incorrect."
}

Get a single user

GET /-/user/org.couchdb.user::username

Response 200

HTTP/1.1 200 OK
ETag: "32-984ee97e01aea166dcab6d1517c730e3"

{
  "_id": "org.couchdb.user:fengmk2",
  "_rev": "32-984ee97e01aea166dcab6d1517c730e3",
  "name": "fengmk2",
  "email": "fengmk2@gmail.com",
  "type": "user",
  "roles": [],
  "date": "2014-08-04T10:43:07.063Z",
  "fullname": "fengmk2",
  "avatar": "https://secure.gravatar.com/avatar/95b9d41231617a05ced5604d242c9670?s=50&d=retro",
  "freenode": "",
  "github": "fengmk2",
  "homepage": "http://fengmk2.github.com",
  "twitter": "fengmk2",
  "avatarMedium": "https://secure.gravatar.com/avatar/95b9d41231617a05ced5604d242c9670?s=100&d=retro",
  "avatarLarge": "https://secure.gravatar.com/avatar/95b9d41231617a05ced5604d242c9670?s=496&d=retro",
  "fields": [
    {
      "name": "fullname",
      "value": "fengmk2",
      "title": "Full Name",
      "show": "fengmk2"
    },
    {
      "name": "email",
      "value": "fengmk2@gmail.com",
      "title": "Email",
      "show": "<a href=\"mailto:fengmk2@gmail.com\">fengmk2@gmail.com</a>"
    },
    {
      "name": "github",
      "value": "fengmk2",
      "title": "Github",
      "show": "<a rel=\"me\" href=\"https://github.com/fengmk2\">fengmk2</a>"
    },
    {
      "name": "twitter",
      "value": "fengmk2",
      "title": "Twitter",
      "show": "<a rel=\"me\" href=\"https://twitter.com/fengmk2\">@fengmk2</a>"
    },
    {
      "name": "appdotnet",
      "value": "",
      "title": "App.net",
      "show": ""
    },
    {
      "name": "homepage",
      "value": "http://fengmk2.github.com",
      "title": "Homepage",
      "show": "<a rel=\"me\" href=\"http://fengmk2.github.com/\">http://fengmk2.github.com</a>"
    },
    {
      "name": "freenode",
      "value": "",
      "title": "IRC Handle",
      "show": ""
    }
  ],
  "appdotnet": "fengmk2"
}

Response 404

HTTP/1.1 404 Object Not Found

{
  "error": "not_found",
  "reason": "missing"
}

Add a new user

PUT /-/user/org.couchdb.user::username

Input

{
  "name": "admin",
  "password": "123",
  "email": "fengmk2@gmail.com",
  "_id": "org.couchdb.user:admin",
  "type": "user",
  "roles": [],
  "date": "2014-08-05T16:05:17.792Z"
}

Response 201

Status: 201 Created

{
  "ok": true,
  "id": "org.couchdb.user:fengmk2",
  "rev": "32-984ee97e01aea166dcab6d1517c730e3",
  "token": "85d32fad-bd43-4dd7-9451-4f7d907313a2"
}

Response 409

User already exists

HTTP/1.1 409 Conflict

{
  "error": "conflict",
  "reason": "Document update conflict."
}

Update a exists user

Authentication required.

PUT /-/user/org.couchdb.user::username/-rev/:rev

Input

{
  "name": "admin",
  "password": "123",
  "email": "fengmk2@gmail.com",
  "_id": "org.couchdb.user:admin",
  "type": "user",
  "roles": [],
  "date": "2014-08-05T16:05:17.792Z",
  "_rev": "2-1a18c3d73ba42e863523a399ff3304d8"
}

Response

Status: 201 Created

{
  "ok": true,
  "id": "org.couchdb.user:fengmk2",
  "rev": "3-bb300a90c9aeb779748b83ec1b744039"
}

Search

Token

Create token
List token
Delete token

Create token

Authentication required.

POST /-/npm/v1/tokens

Input

{
  "password": "123",
  "readonly": false,
  "cidr_whitelist": [
    "127.0.0.1"
  ]
}

Response 200

HTTP/1.1 200 OK

{
  "token": "85d32fad-bd43-4dd7-9451-4f7d907313a2",
  "key": "d06309a210570ef71cd9c7bd4849e7e96eeaa841976e63326436f6fd320dc4bbd452710e4e0fedc2efc2ea4a793b7159e95e9596e85e00dee26adc3f8afbb97f",
  "cidr_whitelist": [ "127.0.0.1" ],
  "created": "2015-01-04T08:28:51.378Z",
  "updated": "2015-01-04T08:28:51.378Z",
  "readonly": false
}

List token

Authentication required.

GET /-/npm/v1/tokens

Input

perPage=10&page=0

Response 200

{
  "objects": [{
    "token": "85d32f...7313a2",
    "key": "d06309a210570ef71cd9c7bd4849e7e96eeaa841976e63326436f6fd320dc4bbd452710e4e0fedc2efc2ea4a793b7159e95e9596e85e00dee26adc3f8afbb97f",
    "cidr_whitelist": [ "127.0.0.1" ],
    "created": "2015-01-04T08:28:51.378Z",
    "updated": "2015-01-04T08:28:51.378Z",
    "readonly": false
  }]
}

Delete token

Authentication required.

GET /-/npm/v1/tokens/token/:UUID

Response 204

Trend

get download trends for a package

GET /downloads/range/:start::end/:pkgName

Response 200

HTTP/1.1 200 OK

// /downloads/range/2024-01-01:2024-12-31/cnpmcore
{
  "downloads": [
    // ...
    { "day": "2024-01-03", "downloads": 2 },
    { "day": "2024-05-30", "downloads": 16 }
  ],
  "versions": {
    // ...
    "3.61.1": [{ "day": "2024-05-30", "downloads": 5 }],
    "3.61.2": [{ "day": "2024-05-30", "downloads": 5 }],
    "3.61.3": [{ "day": "2024-05-30", "downloads": 6 }]
  }
}

Files

registry-api.md

Latest commit

History

registry-api.md

File metadata and controls

NPM Registry API

Overview

Schema

Client Errors

Authentication

Basic Authentication

Bearer Authentication

Failed login limit

Package

Get a single package

Response 200

Response 404

Get a special version or tag package

Reponse 200

Publish a new package

Input

Response

Update a package's tag

Input

Response

Update a package's maintainers

Input

Response

Remove one version from package

Input

Response

Remove all versions of a package

Response

Remove a tgz file from package

Response

List packages since from a update time

Response

List package names by users

Response

User

Auth user

Response 200

Response 401

Get a single user

Response 200

Response 404

Add a new user

Input

Response 201

Response 409

Update a exists user

Input

Response

Search

Token

Create token

Input

Response 200

List token

Input

Response 200

Delete token

Response 204

Trend

get download trends for a package

Response 200