Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


This project is in maintenence status.

Build Status

This is a high level JS client for's REST API. Works as a Node.js module, tested on Node v 5+. Requires an NS1 account w/ an API key.

Using Gitflow so most up-to-date version will be in the develop branch.

Check out our API documentation at

All method signatures reflect endpoints from the NS1 REST API, documentation available at


$ npm install -s ns1

TLDR Example Usage

All methods return A+ style promises.

var NS1 = require('ns1')

NS1.set_api_key([your api key])

NS1.Zone.find().then(function(zones) {
  console.log(zones) //=> Array of NS1.Zone objects

NS1.Zone.find('').then(function(zone) {
  console.log(zone) //=> NS1.Zone object of just the zone
  zone.update({ zone: '' }).then(function(zone) {
    console.log(zone) //=> NS1.Zone object w/ updated info

NS1.Zone.create({ zone: '' }).then(function(zone) {
  console.log(zone) //=> Your newly created zone

new NS1.Zone({ zone: '' }).save().then(function(zone) {
  console.log(zone) //=> same as above

Code Usage

All objects (with the exception of NS1Request and RestResource) follow the resource concept and have static find and create methods for retrieving and creating objects of those types, respectively. For some objects, find can be passed with no arguments to get all objects of that data type, e.g. NS1.Zone.find().

Once you've retrieved an object from the server, you can use update and pass an object of values you'd like to update, or you can adjust the variables on the object's attributes object, and then call save.

All method signatures follow the NS1 API, so whatever is passed to "find" a record via GET requests listed on the api is the required argument for a find method call.

Some examples:

var NS1 = require('ns1')

NS1.set_api_key([your api key])

// find a record, records require zone + type info in string
.then(function(record) {
  return record.update({
    ttl: 300
}).then(function(record) {
  console.log(record.attributes.ttl) // ==> 300

// adding an email to a notification list
.then(function(list) {
    "config": {
      "email": ""
    "type": "email"

// manually send a request to the API
new NS1.NS1Request('get', '/zones/')
.then(function(zone) {


Pull Requests and issues are welcome. See the NS1 Contribution Guidelines for more information.