NPM Registry API

Overview

Schema
Client Errors
Authentication
Package
User
Search

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": "https://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": "https://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": "https://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": "https://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": "https://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": "https://fengmk2.github.com",
      "title": "Homepage",
      "show": "<a rel=\"me\" href=\"https://fengmk2.github.com/\">https://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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!