3 Steps to Optimizing Application Performance with Multi-CDN - REGISTER NOW!

APIs

Introduction

This is the documentation for NS1's API (v1), which allows you to manage your zones and records, data sources and feeds, account settings and users, and other aspects of your NS1 account. You can do everything you're used to doing in my.nsone.net in our API — and more!

The NS1 API is a standard REST API with JSON responses. The HTTP method you use — GETPUTPOST, or DELETE — determines the kind of action to be taken by the API. In the case of PUT and POST requests, you will generally send us a JSON body in your request with the details of the resource you're creating or updating.

Most API requests are authenticated with a simple API Key, which you must specify in the X-NSONE-Key request header. You can manage your API Keys in my.nsone.net. You should treat your API Keys as secrets! You should also give them only the minimal access needed for your application.

Client Libraries

API Examples

Copy CodeCreate a new DNS zone

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"newzone.com", "nx_ttl":60}' https://api.nsone.net/v1/zones/newzone.com

Copy CodeCreate a new secondary DNS zone

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"newzone.com", "secondary": {"enabled":true, "primary_ip":"1.2.3.4"}}' https://api.nsone.net/v1/zones/newzone.com

Copy CodeCreate a new zone allowing AXFR and sending NOTIFY to a slave

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"newzone.com", "primary": {"enabled":true, "secondaries":[ {"ip":"1.2.3.4", "port":53, "notify":true} ]}}' https://api.nsone.net/v1/zones/newzone.com

Copy CodeList active zones

curl -X GET -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' https://api.nsone.net/v1/zones

Copy CodeImport a new zone from a zone file

curl -X PUT -F [email protected] -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' https://api.nsone.net/v1/import/zonefile/example.com

Copy CodeCreate a simple A record

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"arecord.example.com", "type":"A", "answers":[{"answer":["1.2.3.4"]}]}' https://api.nsone.net/v1/zones/example.com/arecord.example.com/A

Copy CodeCreate a linked A record

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"linked-record.example.com", "type":"A", "link":"arecord.example2.com", "answers": []}' https://api.nsone.net/v1/zones/example.com/linked-record.example.com/A

Copy CodeCreate an MX record with multiple answers

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"example.com", "type":"MX", "answers":[{"answer":[5, "mail1.example.com"]}, {"answer":[10, "mail2.example.com"]}]}' https://api.nsone.net/v1/zones/example.com/example.com/MX

Copy CodeCreate a record with GEOTARGET_REGIONAL

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"georegion.example.com", "type":"A", "answers":[{"answer":["1.1.1.1"], "meta":{"georegion":["US-EAST"]}}, {"answer":["9.9.9.9"], "meta":{"georegion":["US-WEST"]}}], "filters":[{"filter":"geotarget_regional", "config":{}}, {"filter":"select_first_n", "config":{"N":1}}]}' https://api.nsone.net/v1/zones/example.com/georegion.example.com/A

This creates an A record with two answers: a server (1.1.1.1) in the US-EAST geotargeting region, and a server (9.9.9.9) in the US-WEST geotargeting region. We also add the GEOTARGET_REGIONAL filter first in the filter chain (it needs no configuration); and follow it with the SELECT_FIRST_N filter with N set to 1, which picks the closest answer.

Copy CodeDisable use of edns-client-subnet data for a record

curl -X POST -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"use_client_subnet":false}' https://api.nsone.net/v1/zones/example.com/example.com/A

Copy CodeConnect a Cloudwatch data source

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"sourcetype":"cloudwatch", "name":"My Cloudwatch Topic", "config":{}}' https://api.nsone.net/v1/data/sources

After creating the Cloudwatch data source in NSONE, create an SNS topic in your Amazon account, connect any alerts you want to feed to NSONE to that topic, and create an HTTPS subscription for the topic with the NSONE Feed URL (https://api.nsone.net/v1/feed/:feedid). New data feeds for this source should specify the Alarm Name of a Cloudwatch alarm.

Copy CodeConnect a feed from a Rackspace data source

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"server.example.com alert", "config":{"entity_id":"enAAAAA", "alarm_id":"alAAAAA"}}' https://api.nsone.net/v1/data/feeds/f443e609c9a9182b3dab56b7abd744342

You must have already connected a Rackspace Cloud Monitoring data source. In this example we specify Cloud Monitoring Entity and Alarm ids — we can also optionally specify a Check id.

Copy CodePush an update to an NS1 API data feed

curl -X POST -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"server-1": {"up":false}, "server-2": {"up":true}}' https://api.nsone.net/v1/feed/a53252f9e583c6708331a1daeb172e12

In this case we assume two data feeds already exist for an NSONE API data source. The data feeds have labels server-1 and server-2 (we might connect them to answers representing those servers in some DNS records). This update tells NSONE that server-1 is down, and server-2 is up. Any records which have their up meta key connected to one of these feeds will be affected.

Copy CodeCreate a new ping monitor

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"1.2.3.4 Ping Check", "job_type":"ping", "region_scope":"fixed", "regions":["lga","sin","ams"], "frequency":60, "config":{"host":"1.2.3.4"}, "rules":[{"key":"loss", "comparison":"<", "value":75.0}], "notify_list":"52cc775a2db2861b55176727"}' https://api.nsone.net/v1/monitoring/jobs

This creates a simple ping job that runs in three monitoring regions: lga (New York), sin (Singapore), and ams (Amsterdam). The host is pinged from all regions each 60 seconds and a rule is configured to fail the monitor if packet loss exceeds 75%. When the job's status changes, notifications are sent to the specified notification list immediately.

Copy CodeCreate a new TCP/HTTPS monitor

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"1.2.3.4:443 HTTPS check", "job_type":"tcp", "region_scope":"fixed", "regions":["lga"], "frequency":60, "config":{"host":"1.2.3.4", "port":443, "send":"HEAD / HTTP/1.0\r\n\r\n", "ssl":"1"}, "rules":[{"key":"output", "comparison":"contains", "value":"200 OK"}], "notify_delay":300, "notify_list":"52cc775a2db2861b55176727"}' https://api.nsone.net/v1/monitoring/jobs

This creates a simple tcp job that runs in the lga (New York) monitoring region. Every 60 seconds a TCP connection is opened to port 443 on the host; an SSL session is negotiated; and a simple HEAD request is sent. String escapes are interpreted in the send parameter. Then, if a response is returned it is tested to see if it contains "200 OK". If not or if no response is returned, the monitor fails, but a notification is only sent if the monitor remains down for 300 seconds.

Copy CodeCreate a new notification list that pushes to Data Feeds

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"Critical Notifications", "notify_list":[ {"type":"email", "config":{"email":"[email protected]"}}, {"type":"datafeed", "config":{"sourceid":"b85579edee904f0f204a6eb07b3f8a1f"}} ]}' https://api.nsone.net/v1/lists

We create a new list to receive monitoring notifications. Notifications will be sent to both an email address ([email protected]) and to an NSONE Data Source for use with NSONE's DNS metadata. To connect a datafeed notifier, the sourceid must be a nsone_monitoring Data Source. Status changes for monitors connected to this notification list will be delivered to the Data Source, and if a Data Feed is configured under the source for the monitor, then the changes will be pushed to all metadata tables connected to the Data Feed.

Copy CodeInvite a new user with full access to your account

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"username":"newuser", "name":"New User", "email":"[email protected]"}' https://api.nsone.net/v1/account/users/newuser

An invitation email will be sent to [email protected] allowing them to set a password and log in to my.nsone.net.

Copy CodeCreate an API Key that can only view one zone

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"My Application", "permissions":{"dns":{"view_zones":true, "manage_zones":false, "zones_allow_by_default":false, "zones_allow":["example.com"]}, "account":{"manage_account_settings":false, "manage_payment_methods":false, "manage_plan":false, "manage_teams":false, "manage_users":false, "manage_apikeys":false, "view_activity_log":false, "view_invoices":false}, "data":{"manage_datasources":false, "manage_datafeeds":false, "push_to_datafeeds":false}, "monitoring":{"manage_lists":false, "manage_jobs":false, "view_jobs":false} }}' https://api.nsone.net/v1/account/apikeys

You must explicitly deny permissions you do not want a new API Key (or User) to have. Since zones_allow_by_default is false, the user will have access only to zones in zones_allow. We grant this user access to example.com only — and since they only have view_zones access, they can only look at the zone's configuration and stats, and can make no changes.

Copy CodeGet usage by zone with graphs for last 24 hours

curl -X GET -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' "https://api.nsone.net/v1/stats/usage?expand=true&period=24h"

Copy CodeGet account-wide usage by billing tier for last 30 days

curl -X GET -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' "https://api.nsone.net/v1/stats/usage?period=30d&aggregate=false&by_tier=true"

Usage is returned broken down by billing tier with arrays like [<static>, <dynamic>, <intelligent>].

Zones & Records

Zones

GET /zones

GET Get list of active zones

Returns all active zones and basic zone configuration details for each.

Copy CodeList active zones

curl -X GET -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' https://api.nsone.net/v1/zones

Request URL:

https://api.nsone.net/v1/zones

Example Response:

[
  {
    "id": "520422af9f782d37dffb588b",
    "ttl": 3600,
    "nx_ttl": 3600,
    "retry": 7200,
    "zone": "example.com",
    "refresh": 43200,
    "expiry": 1209600,
    "dns_servers": [
      "dns1.p03.nsone.net",
      "dns2.p03.nsone.net",
      "dns3.p03.nsone.net",
      "dns4.p03.nsone.net"
    ],
    "networks": [0],
    "network_pools": ["p03"],
    "meta": {},
    "hostmaster": "[email protected]"
  },
  {
    "id": "520422c99f782d37dffb5892",
    "ttl": 3600,
    "nx_ttl": 3600,
    "retry": 7200,
    "zone": "nsoneisgreat.com",
    "refresh": 43200,
    "expiry": 1209600,
    "dns_servers": [
      "dns1.p04.nsone.net",
      "dns2.p04.nsone.net",
      "dns3.p04.nsone.net",
      "dns4.p04.nsone.net"
    ],
    "networks": [0],
    "network_pools": ["p04"],
    "meta": {},
    "hostmaster": "[email protected]"
  }
]

GET /zones/:zone

GET Get a zone's details

Returns a single active Zone and its basic configuration details. For convenience, a list of records in the zone, and some basic details of each record, is also included.

Request URL:

https://api.nsone.net/v1/zones/:zone

Example URL:

https://api.nsone.net/v1/zones/example.com

Example Response:

{
  "id": "520422af9f782d37dffb588b",
  "hostmaster": "[email protected]",
  "ttl": 3600,
  "nx_ttl": 3600,
  "retry": 7200,
  "zone": "example.com",
  "refresh": 43200,
  "expiry": 1209600,
  "dns_servers": [
    "dns1.p03.nsone.net",
    "dns2.p03.nsone.net",
    "dns3.p03.nsone.net",
    "dns4.p03.nsone.net"
  ],
  "networks": [0],
  "network_pools": ["p03"],
  "primary": {
    "enabled": false,
    "secondaries": []
  },
  "records": [
    {
      "id": "520422af9f782d37dffb5890",
      "type": "NS",
      "tier": 1,
      "ttl": 3600,
      "short_answers": [
        "dns1.p03.nsone.net",
        "dns2.p03.nsone.net",
        "dns3.p03.nsone.net",
        "dns4.p03.nsone.net"
      ],
      "domain": "example.com"
    },
    {
      "id": "520519509f782d58bb4df419",
      "type": "A",
      "tier": 1,
      "ttl": 3600,
      "short_answers": [
        "1.2.3.4"
      ],
      "domain": "www.example.com"
    }
  ],
  "meta": {}
}

PUT /zones/:zone

PUT Create a new DNS zone

You must include a JSON body in the request with basic details of the zone. The only required element in the body is zone, the zone domain name. You may create a standard zone (which has its own configuration and records), a linked zone (which points to an existing standard zone, reusing its configuration and records), or a secondary zone (which slaves DNS records from an external primary DNS server). For non-linked zones, you may specify optional zone configuration by including ttl (SOA record TTL), refreshretryexpiry, and nx_ttl values, as in a SOA record. The zone is assigned DNS servers and appropriate NS records are automatically created, unless you create a secondary zone.

To create a linked zone, you must include a link property in the body of your request. It must be a string which references the target zone (domain name) to link to. The target zone must be owned by the same account that is creating the linked zone. If the linkproperty is specified, no other zone configuration properties (such as refresh, retry, etc) may be specified, since they are all pulled from the target zone. Linked zones, once created, cannot be configured at all and cannot have records added to them. They may only be deleted, which does not affect the target zone at all.

To create a secondary zone, you must include a secondary object in the body of your request including fields enabled (true/false, if true the zone is configured as a secondary zone); and primary_ip(an IPv4 address, not a hostname, for the primary DNS server for the zone). If your primary DNS server is running on a non-standard port, you may also include primary_port.

To enable slaving of your zone by third party DNS servers, you must include a primary object in the body of your request including fields enabled (true/false, if true then AXFR queries and optionally NOTIFY messages will be enabled for the zone); and secondaries, a list of objects each containing ip (IPv4 address of the secondary node), port (optional, port on host to send NOTIFYmessages, default 53), and notify (true/false, if true then we will send NOTIFY messages to the secondary host when the zone changes).

If your account has access to multiple DNS networks, you may pass in networks, a list of network ids for which the zone should be made available. If you do not provide a list of networks, the zone will be created in network 0, the primary NSONE Global Network. DNS servers will be selected and assigned from among all the networks you specify.

Copy CodeCreate a new DNS zone

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"newzone.com", "nx_ttl":60}' https://api.nsone.net/v1/zones/newzone.com

Copy CodeCreate a new secondary DNS zone

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"newzone.com", "secondary": {"enabled":true, "primary_ip":"1.2.3.4"}}' https://api.nsone.net/v1/zones/newzone.com

Copy CodeCreate a new zone allowing AXFR and sending NOTIFY to a slave

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"newzone.com", "primary": {"enabled":true, "secondaries":[ {"ip":"1.2.3.4", "port":53, "notify":true} ]}}' https://api.nsone.net/v1/zones/newzone.com

Request URL:

https://api.nsone.net/v1/zones/:zone

Example URL:

https://api.nsone.net/v1/zones/newzone.com

Example Request:

{
  "zone": "newzone.com",
  "ttl&tuot;: 3600,
  "nx_ttl": 60
}

Example Response:

{
  "id": "52051b2c9f782d58bb4df41b",
  "hostmaster": "[email protected]",
  "ttl": 3600,
  "nx_ttl": 60,
  "retry": 7200,
  "zone": "newzone.com",
  "refresh": 43200,
  "expiry": 1209600,
  "dns_servers": [
    "dns1.p06.nsone.net",
    "dns2.p06.nsone.net",
    "dns3.p06.nsone.net",
    "dns4.p06.nsone.net"
  ],
  "networks": [0],
  "network_pools": ["p06"],
  "primary": {
    "enabled": false,
    "secondaries": []
  },
  "records": [
    {
      "id": "52051b2c9f782d58bb4df420",
      "type": "NS",
      "tier": 1,
      "ttl": 3600,
      "short_answers": [
        "dns1.p06.nsone.net",
        "dns2.p06.nsone.net",
        "dns3.p06.nsone.net",
        "dns4.p06.nsone.net"
      ],
      "domain": "newzone.com"
    }
  ],
  "meta": {}
}

POST /zones/:zone

POST Modify a zone

Modifies basic details of a DNS zone. You must include a JSON body in the request, in which you may include ttl (SOA record TTL), refreshretryexpiry, or nx_ttl values, as in a SOA record. You may not change the zone name or other details.

If the zone is a secondary zone, you may change the primary_ip and primary_port for the zone. You may also change enabled in the secondary object to convert a zone between primary and secondary behavior. Note that when converting from a secondary to a primary zone, you will need to create a NS record for the zone with the zone's assigned NSONE nameservers.

You may enable/disable slaving from the zone and add/remove secondary (slave) hosts by manipulating the primary object.

You may modify the set of DNS networks for which the zone should be made available. Note that if you remove a network from a zone, and later re-add it, then new nameservers will be assigned within that network. You may remove all networks from a zone, in which case the zone will not be accessible from any DNS network.

Request URL:

https://api.nsone.net/v1/zones/:zone

Example URL:

https://api.nsone.net/v1/zones/newzone.com

Example Request:

{
  "refresh": 10800
}

Example Response:

{
  "id": "52051b2c9f782d58bb4df41b",
  "hostmaster": "[email protected]",
  "ttl": 3600,
  "nx_ttl": 60,
  "retry": 7200,
  "zone": "newzone.com",
  "refresh": 10800,
  "expiry": 1209600,
  "dns_servers": [
    "dns1.p06.nsone.net",
    "dns2.p06.nsone.net",
    "dns3.p06.nsone.net",
    "dns4.p06.nsone.net"
  ],
  "networks": [0],
  "network_pools": ["p06"],
  "records": [
    {
      "id": "52051b2c9f782d58bb4df420",
      "type": "NS",
      "tier": 1,
      "ttl": 3600,
      "short_answers": [
        "dns1.p06.nsone.net",
        "dns2.p06.nsone.net",
        "dns3.p06.nsone.net",
        "dns4.p06.nsone.net"
      ],
      "domain": "newzone.com"
    }
  ],
  "meta": {}
}

DELETE /zones/:zone

DELETE Delete a zone and all its records

Destroys an existing DNS zone and all records in the zone. Our servers won't respond to queries for the zone or any of the records after you do this, and you cannot recover the deleted zone, so be careful! There is no request body required, and there is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/zones/:zone

Example URL:

https://api.nsone.net/v1/zones/example.com

PUT /import/zonefile/:zone

PUT Import a zone from a zone file

Upload a zone file, using form encoding (multipart/form-data) with the zone file as the content of the zonefile form parameter. The zone must not already exist in your account. It will be created, as will all records in the zone file. Any round-robin records (e.g., multiple A records for the same domain) will be treated as answers for a single combined record in your account. Existing NS records will be replaced, as will some details of SOA records.

There are two modes: synchronous (default) and asynchronous. In asynchronous mode, you must check back with a GET request using the returned job id to get the results of your request. In synchronous mode, the connection remains open until the results can be returned to you directly. Full details of the new zone and all records are returned; a warnings field contains a list of strings with any warnings from the zone file import process.

Upon import, the zone will be made available only on the NSONE Global Network (network 0). If your account has access to other DNS networks and you wish to make the zone available via those networks, simply add them to the zone after importing the zone file.

Copy CodeImport a new zone from a zone file

curl -X PUT -F [email protected] -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' https://api.nsone.net/v1/import/zonefile/example.com

Request URL:

https://api.nsone.net/v1/import/zonefile/:zone[?async=true]

Example URL:

https://api.nsone.net/v1/import/zonefile/newzone.com?async=true

Example Request:

(Other headers)
Content-Type: multipart/form-data; boundary=----------------------------a5d22159c43c

------------------------------a5d22159c43c
Content-Disposition: form-data; name="zonefile"; filename="newzone.com.db"
Content-Type: application/octet-stream

$ORIGIN newzone.com.
$TTL 300
@	SOA	ns1.newzone.com. hostmaster.newzone.com. 201303202324 43200 7200 1209600 3600
@	NS	ns1
@	NS	ns2
@	A	1.2.3.4
www	A	1.2.3.4

------------------------------a5d22159c43c--

Example Response:

{
  "id": "52052aa99f782d5b1a10a831",
  "hostmaster": "[email protected]",
  "meta": {},
  "ttl": 3600,
  "nx_ttl": 300,
  "retry": 7200,
  "zone": "newzone.com",
  "warnings": [],
  "refresh": 43200,
  "expiry": 1209600,
  "dns_servers": [
    "dns1.p06.nsone.net",
    "dns2.p06.nsone.net",
    "dns3.p06.nsone.net",
    "dns4.p06.nsone.net"
  ],
  "networks": [0],
  "network_pools": ["p06"],
  "records": [
    {
      "id": "52052aa99f782d5b1a10a836",
      "type": "NS",
      "tier": 1,
      "short_answers": [
        "dns1.p06.nsone.net",
        "dns2.p06.nsone.net",
        "dns3.p06.nsone.net",
        "dns4.p06.nsone.net"
      ],
      "domain": "newzone.com"
    },
    {
      "id": "52052aa99f782d5bcc10a847",
      "type": "A",
      "tier": 1,
      "domain": "newzone.com",
      "zone": "newzone.com",
      "short_answers": [
        "1.2.3.4"
      ]
    },
    {
      "id": "52052aa99f78375bcc10a666",
      "type": "A",
      "tier": 1,
      "domain": "www.newzone.com",
      "zone": "newzone.com",
      "short_answers": [
        "1.2.3.4"
      ]
    }
  ]
}

Example Response:

{
  "sent": 1376070394,
  "id": "zIbC9VfrnVtubXfJbM6a",
  "type": "importzonefile",
  "percent": 20,
  "status": "Creating zone"
}

GET /import/zonefile/:jobid

GET Get status of a zone file import

Get the status, and if finished, results of, a zone file import job launched with a PUT request to /import/zonefile/:zone. The jobid is the value of the id field in the response of an asynchronous import request. If the zone file import is finished, the response includes the fields response (body containing import request results), and response_code (final HTTP status code for the import request).

Request URL:

https://api.nsone.net/v1/import/zonefile/:jobid

Example URL:

https://api.nsone.net/v1/import/zonefile/zIbC9VfrnVtubXfJbM6a

Example Response:

{
  "sent": 1376070394,
  "id": "zIbC9VfrnVtubXfJbM6a",
  "type": "importzonefile",
  "result": {
    "id": "52052afa9f782d5b1a10a83f",
    "hostmaster": "[email protected]",
    "meta": {},
    "ttl": 3600,
    "nx_ttl": 300,
    "retry": 7200,
    "zone": "newzone.com",
    "warnings": [],
    "refresh": 43200,
    "expiry": 1209600,
    "records": [
      {
        "id": "52052afa9f782d5b1a10a844",
        "type": "NS",
        "tier": 1,
        "short_answers": [
          "dns1.p01.nsone.net",
          "dns2.p01.nsone.net",
          "dns3.p01.nsone.net",
          "dns4.p01.nsone.net"
        ],
        "domain": "newzone.com"
      },
      {
        "type": "A",
        "feeds": [],
        "tier": 1,
        "domain": "newzone.com",
        "zone": "newzone.com",
        "answers": [
          {
            "id": "52052afa9f782d5b1a10a846",
            "answer": [
              "1.2.3.4"
            ]
          }
        ],
        "regions": {},
        "meta": {},
        "filters": [],
        "ttl": 300
      },
      {
        "type": "A",
        "feeds": [],
        "tier": 1,
        "domain": "www.newzone.com",
        "zone": "newzone.com",
        "answers": [
          {
            "id": "52052afa9f782d5b1a10a848",
            "answer": [
              "1.2.3.4"
            ]
          }
        ],
        "regions": {},
        "meta": {},
        "filters": [],
        "ttl": 300
      }
    ],
    "dns_servers": [
      "dns1.p01.nsone.net",
      "dns2.p01.nsone.net",
      "dns3.p01.nsone.net",
      "dns4.p01.nsone.net"
    ],
    "networks": [0],
    "network_pools": ["p01"]
  },
  "percent": 100,
  "status": "Created zone and 3 records",
}

GET /search

GET Search zones and records

Returns all zones and records that match a query string q. You can limit the max number of results and you can restrict the type of results to zonerecord, or all. Entries in the response without domain/type are zones, and those with domain/type are records.

Request URL:

https://api.nsone.net/v1/search?q=[querystring][&max=10][&type=all]

Example URL:

https://api.nsone.net/v1/search?q=example

Example Response:

[
  {
    "zone": "example.com"
  },
  {
    "zone": "example.com",
    "type": "NS",
    "domain": "example.com"
  },
  {
    "zone": "example.com",
    "type": "MX",
    "domain": "mail.example.com"
  },
  {
    "zone": "example.com",
    "type": "A",
    "domain": "www.example.com"
  }
]

GET /networks

GET List available networks

Some customers may have access to DNS networks other than the primary NSONE Global Network. This endpoint lists all networks for which you may create zones and records. You will generally always have access to the NSONE Global Network (network 0).

Request URL:

https://api.nsone.net/v1/networks

Example URL:

https://api.nsone.net/v1/networks

Example Response:

[
  {
    "network_id": 0,
    "label": "NSONE",
    "name": "NSONE Global Network"
  },
  {
    "network_id": 82,
    "label": "myprivate",
    "name": "My Private Network"
  }
]

Records

GET /zones/:zone/:domain/:type

GETGet record configuration details

Returns full configuration for a DNS record including basic config, answersregions, filter chain configuration, and all metadata tables and data feeds attached to entities in the record. (Note that regions might be any specified grouping, not necessarily a geo-related region. For this reason, the NS1 web portal at my.nsone.net uses the word "group" instead of "region".)

You must fully specify zonedomain, and record type, e.g., example.com/www.example.com/A returns the A record for www.example.com in the example.com zone.

Request URL:

https://api.nsone.net/v1/zones/:zone/:domain/:type

Example URL:

https://api.nsone.net/v1/zones/example.com/www.example.com/A

Example Response:

{
  "id": "520519509f782d58bb4df419",
  "networks": [0],
  "type": "A",
  "tier": 3,
  "domain": "www.example.com",
  "zone": "example.com",
  "answers": [
    {
      "id": "520519509f782d58bb4df418",
      "feeds": [
        {
          "source": "a53252f9e583c6708331a1daeb172e12",
          "feed": "520533b89f782d5b1a10a851"
        }
      ],
      "answer": [
        "1.1.1.1"
      ],
      "meta": {
        "up": { feed: "520533b89f782d5b1a10a851" },
        "priority": 1
      },
      "region": "us-east"
    },
    {
      "id": "5205338e9f782d5b1a10a84e",
      "feeds": [
        {
          "source": "a53252f9e583c6708331a1daeb172e12",
          "feed": "520533c09f782d5b1a10a852"
        }
      ],
      "answer": [
        "2.2.2.2"
      ],
      "meta": {
        "up": { feed: "520533b89f782d5b1a10a852" },
        "priority": 2
      },
      "region": "us-east"
    },
    {
      "id": "5205338e9f782d5b1a10a84f",
      "feeds": [
        {
          "source": "a53252f9e583c6708331a1daeb172e12",
          "feed": "520533dc9f782d5b1a10a854"
        }
      ],
      "answer": [
        "8.8.8.8"
      ],
      "meta": {
        "up": { feed: "520533b89f782d5b1a10a854" },
        "priority": 3
      },
      "region": "us-west"
    },
    {
      "id": "5205338e9f782d5b1a10a850",
      "feeds": [
        {
          "source": "a53252f9e583c6708331a1daeb172e12",
          "feed": "520533e49f782d5b1a10a855"
        }
      ],
      "answer": [
        "9.9.9.9"
      ],
      "meta": {
        "up": { feed: "520533b89f782d5b1a10a855" },
        "priority": 3
      },
      "region": "us-west"
    }
  ],
  "regions": {
    "us-east": {
      "meta": {
        "georegion": ["US-EAST"]
      }
    },
    "us-west": {
      "meta": {
        "georegion": ["US-WEST"]
      }
    }
  },
  "meta": {},
  "filters": [
    {
      "config": {},
      "filter": "up"
    },
    {
      "config": {},
      "filter": "geotarget_regional"
    },
    {
      "config": {},
      "filter": "select_first_region"
    },
    {
      "config": {},
      "filter": "weighted_shuffle"
    },
    {
      "config": {
        "N": 1
      },
      "filter": "select_first_n"
    }
  ],
  "ttl": 60,
  "use_client_subnet": true
}

PUT /zones/:zone/:domain/:type

PUTCreate a new DNS record

Creates a new DNS record in the specified zone, for the specified domain, of the given record type. Currently supported record types are: AAAAAALIASAFSDBCERTCNAMEDNAMEHINFOMXNAPTRNSPTRRPSPFSRVTXT. The answer field within each entry in the answers list must be a list of the RDATA fields for a DNS record of the specified type.

You may not create multiple records of the same type for the same domain name in a zone — instead, add new answers to the existing record. The default behavior if no filters are in the filter chain is to return all answers matching a query.

Metadata tables (meta) may be specified in answers, in regions or in the record as a whole. (Note that regions can be any kind of group, not just geo-related. For this reason, the NS1 web portal at my.nsone.net uses the word "group" instead of "region".) The metadata tables may contain key/value pairs where valid keys and values are as described in the output of /metatypes.

Anywhere metadata tables can go, data feeds can go as well. Connect a compatible feed to a metadata key by assigning its value to be a JSON object pointing to the data feed that should be consulted for the final value.

The new record will take on the same networks as the zone it's in.

Instead of specifying answers and other details, you may create a "linked" record. This allows you reuse the configuration (including answers and metadata) from an existing record in NSONE's systems. Linked records will respond in the exact same way as their targets at DNS resolution time, and can be used for maintaining complicated record configurations in a single record while pointing (linking) other lightweight records to it. Linked records must point to another record of the exact same record type and do not have to exist in the same zone.

To create a linked record, specify the link property as a string whose contents is the FQDN containing the config it should link to. If link is specified, no other record configuration (such as answersor meta) should be specified.

Copy CodeCreate a simple A record

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"arecord.example.com", "type":"A", "answers":[{"answer":["1.2.3.4"]}]}' https://api.nsone.net/v1/zones/example.com/arecord.example.com/A

Copy CodeCreate a linked A record

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"linked-record.example.com", "type":"A", "link":"arecord.example2.com", "answers": []}' https://api.nsone.net/v1/zones/example.com/linked-record.example.com/A

Copy CodeCreate an MX record with multiple answers

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"example.com", "type":"MX", "answers":[{"answer":[5, "mail1.example.com"]}, {"answer":[10, "mail2.example.com"]}]}' https://api.nsone.net/v1/zones/example.com/example.com/MX

Copy CodeCreate a record with GEOTARGET_REGIONAL

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"zone":"example.com", "domain":"georegion.example.com", "type":"A", "answers":[{"answer":["1.1.1.1"], "meta":{"georegion":["US-EAST"]}}, {"answer":["9.9.9.9"], "meta":{"georegion":["US-WEST"]}}], "filters":[{"filter":"geotarget_regional", "config":{}}, {"filter":"select_first_n", "config":{"N":1}}]}' https://api.nsone.net/v1/zones/example.com/georegion.example.com/A

This creates an A record with two answers: a server (1.1.1.1) in the US-EAST geotargeting region, and a server (9.9.9.9) in the US-WEST geotargeting region. We also add the GEOTARGET_REGIONALfilter first in the filter chain (it needs no configuration); and follow it with the SELECT_FIRST_N filter with N set to 1, which picks the closest answer.

Request URL:

https://api.nsone.net/v1/zones/:zone/:domain/:type

Example URL:

https://api.nsone.net/v1/zones/example.com/mail.example.com/MX

Example Request:

{
  "answers": [
    {
      "answer": [
        10,
        "1.2.3.4"
      ],
      "meta": {
        "up": { feed: "520533b89f782d5b1a10a854" }
      }
    }
  ],
  "type": "MX",
  "domain": "mail.example.com",
  "zone": "example.com"
}

Example Response:

{
  "id": "52053b569f782d5b1a10a85a",
  "networks": [0],
  "type": "MX",
  "feeds": [],
  "tier": 1,
  "customer": 1004,
  "domain": "mail.example.com",
  "zone": "example.com",
  "answers": [
    {
      "id": "52053b569f782d5b1a10a859",
      "feeds": [
        {
          "source": "a53252f9e583c6708331a1daeb172e12",
          "feed": "520533b89f782d5b1a10a854"
        }
      ],
      "answer": [
        10,
        "1.2.3.4"
      ],
      "meta": {
        "up": { feed: "520533b89f782d5b1a10a854" }
      }
    }
  ],
  "regions": {},
  "meta": {},
  "filters": [],
  "ttl": 3600,
  "use_client_subnet": true
}

POST /zones/:zone/:domain/:type

POSTUpdate record configuration

Modifies configuration details for an existing DNS record.

Copy CodeDisable use of edns-client-subnet data for a record

curl -X POST -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"use_client_subnet":false}' https://api.nsone.net/v1/zones/example.com/example.com/A

Request URL:

https://api.nsone.net/v1/zones/:zone/:domain/:type

Example URL:

https://api.nsone.net/v1/zones/example.com/mail.example.com/MX

Example Request:

{
  "answers": [
    {
      "answer": [
        10,
        "1.2.3.4"
      ]
    },
    {
      "answer": [
        20,
        "5.6.7.8"
      ]
    }
  ]
}

Example Response:

{
  "id": "52053b569f782d5b1a10a85a",
  "networks": [0],
  "type": "MX",
  "feeds": [],
  "tier": 1,
  "customer": 1004,
  "domain": "mail.example.com",
  "zone": "example.com",
  "answers": [
    {
      "id": "52053c239f782d5b1a10a85e",
      "answer": [
        10,
        "1.2.3.4"
      ]
    },
    {
      "id": "52053c239f782d5b1a10a85f",
      "answer": [
        20,
        "5.6.7.8"
      ]
    }
  ],
  "regions": {},
  "meta": {},
  "filters": [],
  "ttl": 3600,
  "use_client_subnet": true
}

DELETE /zones/:zone/:domain/:type

DELETEDelete a record

Removes an existing record and all associated answers and configuration details. We will no longer respond for this record once it is deleted, and it cannot be recovered, so use caution. Note: This operation deletes all answers associated with the domain and record type. If you want to delete individual answers, do a POSToperation to update the record's answers list. This method has no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/zones/:zone/:domain/:type

Example URL:

https://api.nsone.net/v1/zones/example.com/mail.example.com/MX

GET https://api.nsone.net/v1/metatypes

GETGet available metadata fields

Returns a list of available metadata fields for use in configuring records, including descriptions (in HTML).

Request URL:

https://api.nsone.net/v1/metatypes

Example Response:

{
  "georegion": {
    "desc": "Geographic region(s) associated with the answer or\n    region, e.g., the rough geographic location of the datacenter\n    where your server resides.  Each region must be a string, one of\n    'US-EAST', 'US-CENTRAL', 'US-WEST', 'EUROPE', 'ASIAPAC',\n    'SOUTH-AMERICA', 'AFRICA'.  The \"georegion\" value may be a single\n    region string, or a list of several such strings to associate an\n    answer/region with multiple geographic regions.",
    "category": "geographical",
    "shortdesc": "Geographic region"
  },
  "up": {
    "desc": "This boolean value indicates \"upness\" of answers or\n    regions.  If true (or 1), the answer/region is \"up\".  If false (or\n    0) it is \"down\".",
    "category": "status",
    "shortdesc": "Up/down"
  },
  ...
}

GET https://api.nsone.net/v1/filtertypes

GETGet available filters

Returns a list of available FILTERS for use in configuring dynamic records, including descriptions (in HTML), configuration options, and metadata inputs used by the filter, along with any restrictions on record types where the filter may be used.

Request URL:

https://api.nsone.net/v1/filtertypes

Example Response:

{
  "up": {
    "desc": "This filter eliminates all answers where the <code>up</code> metadata field is not <code>\"1\"</code>.",
    "config": {},
    "inputs": ["up"],
    "tier": 2,
    "shortdesc": "Removes \"down\" answers"
  },
  "sticky_region": {
    "desc": "This filter first sorts regions uniquely depending on\n        the IP address of the requester, and then groups all answers\n        together by region.  The same requester always gets the same\n        ordering of regions, but answers within each region may be in\n        any order.  You can use this filter with another one like\n        <span class=\"filtername-2\">SELECT_FIRST_REGION</span> to always\n        give a user answers from the same region.  Note that this\n        filter does <i>not</i> do any geotargeting or GSLB: it sorts\n        regions randomly but consistently for each user.  Answers with\n        no region defined are considered to be in the same (empty)\n        region.",
    "config": {},
    "inputs": [],
    "tier": 2,
    "shortdesc": "Make regions \"sticky\""
  },
  "select_first_n": {
    "desc": "This filter eliminates all but the first <code>N</code>\n        answers from the list.  Use this with filters like <span\n        class=\"filtername-2\">SHUFFLE</span> or <span\n        class=\"filtername-2\">SHUFFLE_WEIGHTED</span> to implement round\n        robin or weighted round robin.",
    "config": {
      "N": {
        "desc": "Number of answers to keep",
        "type": "number",
        "shortdesc": "Number of answers",
        "validator": "number",
        "required": false,
        "default": "1"
      }
    },
    "inputs": [],
    "tier": 2,
    "shortdesc": "Return the first \"N\" answers"
  },
  ...
}

Data Sources & Feeds

Data Sources

GET https://api.nsone.net/v1/data/sourcetypes

GET Get available data sources types

Returns a list of all available data source types. For any third party data sources, you must have an account with the provider. Frequently, there are additional steps you must take with the provider to connect your data source — these are explained in the desc field which is HTML. Response includes any config options for the data source, required or optional; and any feed_config options for data feeds connected to the source.

Request URL:

https://api.nsone.net/v1/data/sourcetypes

Example Response:

{
  "monitis": {
    "desc": "Monitis is a monitoring solution.  To use this data source,\n    first create a new \"URL\" contact in your Monitis account with the NSONE\n    Feed URL.  When creating data feeds, set the \"Test Name\" field to\n    the name of the test in Monitis.  Make sure you set the \"Notify when\n    back up\" rule in Monitis for all your connected tests.  Data feeds from\n    this source update the <code>up</code> metadata field.",
    "config": {
      "api_key": {
        "desc": "Your Monitis API Key (in your Monitis dashboard, click Account, API Key)",
        "type": "text",
        "shortdesc": "Monitis API Key",
        "validator": "text",
        "required": true,
        "default": null
      },
      "secret_key": {
        "desc": "Your Monitis Secret Key (in your Monitis dashboard, click Account, API Key)",
        "type": "text",
        "shortdesc": "Monitis Secret Key",
        "validator": "text",
        "required": true,
        "default": null
      }
    },
    "feed_config": {
      "test_name": {
        "desc": "The name of the test in Monitis that corresponds to this feed",
        "type": "text",
        "shortdesc": "Test Name",
        "validator": "text",
        "required": true,
        "default": null
      }
    },
    "shortdesc": "Monitis Alert Notification"
  },
  "cloudwatch": {
    "desc": "Amazon Cloudwatch is a monitoring solution for Amazon\n    Web Services.  You must configure your Cloudwatch alarms to\n    publish messages to a Simple Notification Service (SNS) topic for\n    your NSONE Feed.  First, in the SNS console, create a topic for\n    your alarms; then create an HTTPS subscription for the topic with\n    your NSONE Feed URL.  Do not associate your Data Source with more\n    than one topic in SNS (you can always create another Data Source).\n    Ensure your Cloudwatch alarms send notifications to this SNS topic\n    and specify the Alarm Name of a Cloudwatch alarm when creating a\n    new Data Feed.  Data feeds from this source update the\n    <code>up</code> metadata field.",
    "config": {},
    "feed_config": {
      "alarm_name": {
        "desc": "The name of the Cloudwatch Alarm that corresponds to this feed",
        "type": "text",
        "shortdesc": "Alarm Name",
        "validator": "text",
        "required": true,
        "default": null
      }
    },
    "shortdesc": "Cloudwatch Alarm Notification"
  },
  "nsone_v1": {
    "desc": "The native NSONE data source, our own API.  Requires\n    normal NSONE API authentication via the <code>X-NSONE-Key</code>\n    header when sending requests to the Feed URL.  The body of your\n    data feed request must be a JSON object containing <b>either</b>\n    simple key/value pairs as in any normal record/region/answer\n    metadata table, e.g. <code>{\"up\": true}</code>, in which case the\n    updated values will be applied to <b>all</b> data feeds associated\n    with this data source; <b>or</b>, an object where keys match the\n    <code>label</code> for data feeds from this source, and values are\n    metadata update tables.  Data feeds from this source may update\n    any metadata field.",
    "config": {},
    "feed_config": {
      "label": {
        "desc": "Short/simple label for the service this feed is\n              for, like a server name, facility name, etc.",
        "type": "text",
        "shortdesc": "Label",
        "validator": "text",
        "required": true,
        "default": null
      }
    },
    "shortdesc": "NSONE Data Feed API v1"
  },
  ...
}

GET https://api.nsone.net/v1/data/sources

GET Get active data sources

Returns a list of all connected data sources, and for each data source, all connected feeds including connected metadata table destinations.

Request URL:

https://api.nsone.net/v1/data/feeds/:sourceid/:feedid

Example URL:

https://api.nsone.net/v1/data/feeds/0e308ec0266d9127d166e0cbd7ceffda/520533c09f782d5b1a10a852

Example Request:

{
  "destinations": [
    {
      "destid": "5205338e9f782d5b1a10a84e",
      "desttype": "answer",
      "record": "520519509f782d58bb4df419"
    }
  ],
  "id": "520533c09f782d5b1a10a852",
  "data": {
    "up": "true"
  },
  "config": {
    "label": "server-2"
  },
  "name": "Server 2 Feed"
}

GET https://api.nsone.net/v1/data/sources/:sourceid

GET Get a single data source

Returns the details for a single data source, including configuration, all connected data feeds, and within data feeds, any connected metadata table (destinations).

Request URL:

https://api.nsone.net/v1/data/sources/:sourceid

Example URL:

https://api.nsone.net/v1/data/sources/f443e609c9a9182b3dab56b7abd74546

Example Response:

{
  "sourcetype": "rackspace",
  "id": "f443e609c9a9182b3dab56b7abd74546",
  "config": {
    "webhook_token": "none"
  },
  "feeds": [
    {
      "destinations": [],
      "id": "520849a99f782d5b1a10a86d",
      "data": {
        "up": "false"
      },
      "config": {
        "entity_id": "enAAAAA",
        "alarm_id": "alAAAA"
      },
      "name": "server.example.com alert"
    }
  ],
  "name": "My Rackspace Source",
  "status": "ok"
}

PUT https://api.nsone.net/v1/data/sources

PUT Connect a new data source

Creates a new data source. You may create multiple data sources of the same type, e.g., to correspond to different accounts with a data provider. The config for the source must contain fields corresponding to the config description in /data/sourcetypes for the sourcetype you specify. Some data sources are immediately connected; others enter a pending state awaiting activity from the data source, e.g., a verification request. See the documentation for the source from /data/sourcetypes.

Copy CodeConnect a Cloudwatch data source

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"sourcetype":"cloudwatch", "name":"My Cloudwatch Topic", "config":{}}' https://api.nsone.net/v1/data/sources

After creating the Cloudwatch data source in NSONE, create an SNS topic in your Amazon account, connect any alerts you want to feed to NSONE to that topic, and create an HTTPS subscription for the topic with the NSONE Feed URL (https://api.nsone.net/v1/feed/:feedid). New data feeds for this source should specify the Alarm Name of a Cloudwatch alarm.

Request URL:

https://api.nsone.net/v1/data/sources

Example Request:

{
  "config": {
    "secret_key": "47AOG8ATA1QNUC3H3UH2DRBXYZ",
    "api_key": "15PSVFCXA377TGUY0FJA7T9VZY"
  },
  "name": "Monitor.us Example",
  "sourcetype": "monitor_us"
}

Example Response:

{
  "sourcetype": "monitor_us",
  "id": "0e308ec0266d9127d166e0cbd7ceffda",
  "config": {
    "api_key": "15PSVFCXA377TGUY0FJA7T9VZY",
    "secret_key": "47AOG8ATA1QNUC3H3UH2DRBXYZ"
  },
  "feeds": [],
  "name": "Monitor.us Example",
  "status": "pending"
}

POST https://api.nsone.net/v1/data/sources/:sourceid

POST Modify a data source

Modifies basic details or configuration of a data source. You must include a JSON body in the request. You may update name and config details.



Request URL:

https://api.nsone.net/v1/data/sources/:sourceid

Example URL:

https://api.nsone.net/v1/data/sources/0e308ec0266d9127d166e0cbd7ceffda

Example Request:

{
  "name": "Monitor.us New Name"
}

Example Response:

{
  "sourcetype": "monitor_us",
  "id": "0e308ec0266d9127d166e0cbd7ceffda",
  "config": {
    "api_key": "15PSVFCXA377TGUY0FJA7T9VZY",
    "secret_key": "47AOG8ATA1QNUC3H3UH2DRBXYZ"
  },
  "feeds": [],
  "name": "Monitor.us New Name",
  "status": "ok"
}

DELETE https://api.nsone.net/v1/data/sources/:sourceid

DELETE Delete a data source

Removes an existing data source and all connected feeds from the source. By extension, all metadata tables connected to those feeds will no longer receive updates. We will no longer accept updates on the Feed URL for this data source. This method has no response other than the HTTP status code.


Request URL:

https://api.nsone.net/v1/data/sources/:sourceid

Example URL:

https://api.nsone.net/v1/data/sources/0e308ec0266d9127d166e0cbd7ceffda

Data Feeds

GET https://api.nsone.net/v1/data/feeds/:sourceid

GETGet active data feeds for a source

Returns all data feeds connected to a source. Includes config details for each feed which match the feed_config specification from /data/sourcetypes, and also includes a list of metadata tables that are destinations for each feed.

Request URL:

https://api.nsone.net/v1/data/feeds/:sourceid

Example URL:

https://api.nsone.net/v1/data/feeds/0e308ec0266d9127d166e0cbd7ceffda

Example Response:

[
  {
    "destinations": [
      {
        "destid": "520519509f782d58bb4df418",
        "desttype": "answer",
        "record": "520519509f782d58bb4df419"
      }
    ],
    "id": "520533b89f782d5b1a10a851",
    "data": {
      "up": "true"
    },
    "config": {
      "label": "server-1"
    },
    "name": "Server 1 Feed"
  },
  {
    "destinations": [
      {
        "destid": "5205338e9f782d5b1a10a84e",
        "desttype": "answer",
        "record": "520519509f782d58bb4df419"
      }
    ],
    "id": "520533c09f782d5b1a10a852",
    "data": {
      "up": "true"
    },
    "config": {
      "label": "server-2"
    },
    "name": "Server 2 Feed"
  },
  {
    "destinations": [
      {
        "destid": "5205338e9f782d5b1a10a84f",
        "desttype": "answer",
        "record": "520519509f782d58bb4df419"
      }
    ],
    "id": "520533dc9f782d5b1a10a854",
    "data": {
      "up": "false"
    },
    "config": {
      "label": "server-8"
    },
    "name": "Server 8 Feed"
  },
  {
    "destinations": [
      {
        "destid": "5205338e9f782d5b1a10a850",
        "desttype": "answer",
        "record": "520519509f782d58bb4df419"
      }
    ],
    "id": "520533e49f782d5b1a10a855",
    "data": {
      "up": "true"
    },
    "config": {
      "label": "server-9"
    },
    "name": "Server 9 Feed"
  }
]

GET https://api.nsone.net/v1/data/feeds/:sourceid/:feedid

GETGet data feed details

Returns the details of a single data feed, including config details and any recordregion, or answer metadata table destinations.

Request URL:

https://api.nsone.net/v1/data/feeds/:sourceid/:feedid

Example URL:

https://api.nsone.net/v1/data/feeds/0e308ec0266d9127d166e0cbd7ceffda/520533c09f782d5b1a10a852

Example Response:

{
  "destinations": [
    {
      "destid": "5205338e9f782d5b1a10a84e",
      "desttype": "answer",
      "record": "520519509f782d58bb4df419"
    }
  ],
  "id": "520533c09f782d5b1a10a852",
  "data": {
    "up": "true"
  },
  "config": {
    "label": "server-2"
  },
  "name": "Server 2 Feed"
}

PUT https://api.nsone.net/v1/data/feeds/:sourceid

PUTConnect a new data feed to a data source

Given an existing data source, connects a new data feed to the source with a given (freeform) name and config matching the specification in feed_config from /data/sourcetypes. In this example, we connect a Rackspace Cloud Monitoring Alarm (using the Rackspace Alarm id and Entity id for the Alarm). To subsequently connect the feed to destinations (such as record answers), you should modify the record to connect a specific metadata key (which the feed is compatible with) via a feed pointer object to this feed id. See the documention for /zones/:zone/:domain/:type.

Copy CodeConnect a feed from a Rackspace data source

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"server.example.com alert", "config":{"entity_id":"enAAAAA", "alarm_id":"alAAAAA"}}' https://api.nsone.net/v1/data/feeds/f443e609c9a9182b3dab56b7abd744342

You must have already connected a Rackspace Cloud Monitoring data source. In this example we specify Cloud Monitoring Entity and Alarm ids — we can also optionally specify a Check id.

Request URL:

https://api.nsone.net/v1/data/feeds/:sourceid

Example URL:

https://api.nsone.net/v1/data/feeds/0e308ec0266d9127d166e0cbd7ceffda

Example Request:

{
  "config": {
    "alarm_id": "a1AAAAA",
    "entity_id": "enAAAAA"
  },
  "name": "server.example.com alert"
}

Example Response:

{
  "destinations": [ ],
  "id": "5208fd909f782d3d253d62ae",
  "data": { },
  "config": {
    "entity_id": "enAAAAA",
    "alarm_id": "a1AAAAA"
  },
  "name": "server.example.com alert"
}

POST https://api.nsone.net/v1/data/feeds/:sourceid/:feedid

POSTModify a data feed

You may update name or config.

To connect the feed to destinations (such as record answers), you should instead modify the record to connect a specific metadata key (which the feed is compatible with) via a feed pointer object to this feed id. See the documention for /zones/:zone/:domain/:type.

Request URL:

https://api.nsone.net/v1/data/feeds/:sourceid/:feedid

Example URL:

https://api.nsone.net/v1/data/feeds/0e308ec0266d9127d166e0cbd7ceffda/5208fd909f782d3d253d62ae

Example Request:

{
  "name": "new name"
}

Example Response:

{
  "destinations": [
    {
      "destid": "us-east",
      "desttype": "region",
      "record": "520519509f782d58bb4df419"
    },
    {
      "destid": "520519509f782d58bb4df418",
      "desttype": "answer",
      "record": "520519509f782d58bb4df419"
    }
  ],
  "id": "5208fd909f782d3d253d62ae",
  "config": {
    "entity_id": "enAAAAA",
    "alarm_id": "a1AAAAA"
  },
  "name": "new name"
}

DELETE https://api.nsone.net/v1/data/feeds/:sourceid/:feedid

DELETEDisconnect a data feed

The feed will be disconnected from the data source and all attached destination metadata tables. The data source will not be removed and updates to remaining connected data feeds will still be processed.

Request URL:

https://api.nsone.net/v1/data/feeds/:sourceid/:feedid

Example URL:

https://api.nsone.net/v1/data/feeds/0e308ec0266d9127d166e0cbd7ceffda/5208fd909f782d3d253d62ae

POST https://api.nsone.net/v1/feed/:sourceid

POSTPublish data from a data source

This is the Feed URL for a data source. Many data sources connect directly to this URL to feed data to NSONE, and in general you must configure them to do so according to the instructions for the data source (see /data/sourcetypes). The request sent to this URL depends on the type of the data source — usually, each data source has its own request protocol. For convenience, this URL accepts GETPUT, and POST requests, but POST is preferred.

You can feed data to the Feed URL directly for your NSONE API data sources (sourcetype of nsone_v1), as shown in the example.

Updates sent to the Feed URL that match any data feeds connected to the data source are applied to all destinations in the feeds and pushed out to our DNS network instantly.



Copy CodePush an update to an NS1 API data feed

curl -X POST -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"server-1": {"up":false}, "server-2": {"up":true}}' https://api.nsone.net/v1/feed/a53252f9e583c6708331a1daeb172e12

In this case we assume two data feeds already exist for an NSONE API data source. The data feeds have labels server-1 and server-2 (we might connect them to answers representing those servers in some DNS records). This update tells NSONE that server-1 is down, and server-2 is up. Any records which have their up meta key connected to one of these feeds will be affected.

Request URL:

https://api.nsone.net/v1/feed/:sourceid

Example URL:

https://api.nsone.net/v1/feed/0e308ec0266d9127d166e0cbd7ceffda

Example Request:

{
  "server-1": {
    "up": false
  },
  "server-2": {
    "up": true
  }
}

Monitoring & Notifications

Monitoring Jobs

GET https://api.nsone.net/v1/monitoring/jobs

GET List monitoring jobs

Returns the list of all monitoring jobs for the account, including configuration and current status details. Job status is shown per region, including the "global" region indicating the overal status of the monitoring job computed based on the status policy from the regional statuses. Status values both globally and per region include updown, and pending.

Request URL:

https://api.nsone.net/v1/monitoring/jobs

Example Response:

[
  {
    "id": "52a27d4397d5f07003fdbe7b",
    "config": {
      "host": "1.2.3.4"
    },
    "status": {
      "lga": {
        "since": 1389407609,
        "status": "up"
      },
      "global": {
        "since": 1389407609,
        "status": "up"
      },
      "sjc": {
        "since": 1389404014,
        "status": "up"
      }
    },
    "rules": [
      {
        "key": "rtt",
        "value": 100,
        "comparison": "<"
      }
    ],
    "job_type": "ping",
    "regions": [
      "lga",
      "sjc"
    ],
    "active": true,
    "frequency": 60,
    "policy": "quorum",
    "region_scope": "fixed"
  },
  ...
]

GET https://api.nsone.net/v1/monitoring/jobs/:jobid

GET Get a monitoring job's details

Returns details for a specific monitoring jobs based on its id, including configuration and current status details. Job status is shown per region, including the "global" region indicating the overal status of the monitoring job computed based on the status policyfrom the regional statuses. Status values both globally and per region include updown, and pending.

Request URL:

https://api.nsone.net/v1/monitoring/jobs/:jobid

Example URL:

https://api.nsone.net/v1/monitoring/jobs/52cae678830f7809ec5c9f6b

Example Response:

{
  "notes": null,
  "name": "example.com:80",
  "notify_repeat": 0,
  "id": "52cae678830f7809ec5c9f6b",
  "region_scope": "fixed",
  "rapid_recheck": false,
  "frequency": 30,
  "job_type": "tcp",
  "notify_delay": 0,
  "notify_list": null,
  "notify_regional": false,
  "regions": [
    "ams"
  ],
  "policy": "quorum",
  "config": {
    "send": "HEAD / HTTP/1.0\r\n\r\n",
    "port": 80,
    "host": "1.2.3.4",
    "ssl": "0",
    "ipv6": false
  },
  "status": {
    "ams": {
      "since": 1389052665,
      "status": "down"
    },
    "global": {
      "since": 1389052665,
      "status": "down"
    }
  },
  "notify_failback": true,
  "rules": [
    {
      "value": "200 OK",
      "key": "output",
      "comparison": "contains"
    }
  ],
  "active": true
}

PUT https://api.nsone.net/v1/monitoring/jobs

PUT Create a new monitoring job

Initiate a new monitoring job. A variety of configuration details can be set in the monitoring job request body, including:

  • name: A free-form display name for the monitoring job.

  • active: A boolean indicating if the job is active or temporarily disabled.

  • region_scope: Controls behavior of how the job is assigned to monitoring regions. Currently this must be fixed — indicating monitoring regions are explicitly chosen.

  • regions: A list of region codes in which to run the monitoring job. Available monitoring regions are provided by /monitoring/regions. The number of regions you may specify depends on your account type and billing plan.

  • job_type: The type of monitoring job to be run. A list of available types is given by /monitoring/jobtypes.

  • frequency: The frequency, in seconds, at which to run the monitoring job in each region. The minimum frequency depends on your account type and billing plan.

  • rapid_recheck: A boolean, default false. If true, on any apparent state change, the job is quickly re-run after one second to confirm the state change before notification.

  • policy: The policy for determining the monitor's global status based on the status of the job in all regions. May be quorum(majority status); all (status change only when all regions are in agreement); or one (down if any region is down).

  • notes: Freeform notes to be included in any notifications about this job, e.g., instructions for operators who will receive the notifications.

  • config: A configuration dictionary with keys and values depending on the job_type. Configuration details for each job_type are indicated by /monitoring/jobtypes.

  • rules: A list of rules for determining failure conditions. Each rule acts on one of the outputs from the monitoring job. You must specify key (the output key); comparison (a comparison to perform on the the output); and value (the value to compare to). For example, {"key":"rtt", "comparison":"<", "value":100} is a rule requiring the rtt from a job to be under 100ms, or the job will be marked failed. Available output keys, comparators, and value types are indicated by /monitoring/jobtypes.

  • notify_delay: time in seconds after a failure to wait before sending a notification. If the job is marked "up" before this time expires, no notification is sent. Set to 0 to send a notification immediately upon failure.

  • notify_repeat: time in seconds between repeat notifications of a failed job. Set to 0 to disable repeating notifications. Otherwise the value must be greater than or equal to 60.

  • notify_failback: boolean. If true, a notification is sent when a job returns to an "up" state.

  • notify_regional: boolean. If true, notifications are sent for any regional failure (and failback if desired), in addition to global state notifications.

  • notify_list: The id of the notification list to send notifications to. If no list is specified, no notifications will be sent for this job.

Copy CodeCreate a new ping monitor

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"1.2.3.4 Ping Check", "job_type":"ping", "region_scope":"fixed", "regions":["lga","sin","ams"], "frequency":60, "config":{"host":"1.2.3.4"}, "rules":[{"key":"loss", "comparison":"<", "value":75.0}], "notify_list":"52cc775a2db2861b55176727"}' https://api.nsone.net/v1/monitoring/jobs

This creates a simple ping job that runs in three monitoring regions: lga (New York), sin (Singapore), and ams (Amsterdam). The host is pinged from all regions each 60 seconds and a rule is configured to fail the monitor if packet loss exceeds 75%. When the job's status changes, notifications are sent to the specified notification list immediately.

Copy CodeCreate a new TCP/HTTPS monitor

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"1.2.3.4:443 HTTPS check", "job_type":"tcp", "region_scope":"fixed", "regions":["lga"], "frequency":60, "config":{"host":"1.2.3.4", "port":443, "send":"HEAD / HTTP/1.0\r\n\r\n", "ssl":"1"}, "rules":[{"key":"output", "comparison":"contains", "value":"200 OK"}], "notify_delay":300, "notify_list":"52cc775a2db2861b55176727"}' https://api.nsone.net/v1/monitoring/jobs

This creates a simple tcp job that runs in the lga (New York) monitoring region. Every 60 seconds a TCP connection is opened to port 443 on the host; an SSL session is negotiated; and a simple HEAD request is sent. String escapes are interpreted in the send parameter. Then, if a response is returned it is tested to see if it contains "200 OK". If not or if no response is returned, the monitor fails, but a notification is only sent if the monitor remains down for 300 seconds.

Request URL:

https://api.nsone.net/v1/monitoring/jobs

Example Request:

{
  "notify_list": "52cc775a2db1561b55135327",
  "notify_regional": false,
  "notify_failback": true,
  "notify_repeat": 0,
  "notify_delay": 65,
  "rules": [
    {
      "value": "200 OK",
      "comparison": "contains",
      "key": "output"
    },
    {
      "value": 200,
      "comparison": "<=",
      "key": "connect"
    }
  ],
  "config": {
    "ssl": "1",
    "send": "HEAD / HTTP/1.0\r\n\r\n",
    "port": 443,
    "host": "1.2.3.4"
  },
  "job_type": "tcp",
  "name": "myhost.com:443 monitor",
  "active": true,
  "rapid_recheck": true,
  "region_scope": "fixed",
  "regions": [
    "lga",
    "sjc"
  ],
  "frequency": 30,
  "policy": "quorum",
  "notes": "If this monitor is down then the webserver on myhost.com:443 is down or too slow!"
}

Example Response:

{
  "status": {
    "global": {
      "since": 1389458558,
      "status": "pending"
    }
  },
  "notes": "If this monitor is down then the webserver on myhost.com:443 is down or too slow!",
  "policy": "quorum",
  "frequency": 30,
  "regions": [
    "lga",
    "sjc"
  ],
  "region_scope": "fixed",
  "active": true,
  "rapid_recheck": true,
  "name": "myhost.com:443 monitor",
  "job_type": "tcp",
  "config": {
    "ssl": "1",
    "send": "HEAD / HTTP/1.0\r\n\r\n",
    "port": 443,
    "host": "1.2.3.4"
  },
  "rules": [
    {
      "value": "200 OK",
      "comparison": "contains",
      "key": "output"
    },
    {
      "value": 200,
      "comparison": "<=",
      "key": "connect"
    }
  ],
  "notify_delay": 65,
  "notify_repeat": 0,
  "notify_failback": true,
  "notify_regional": false,
  "notify_list": "52cc775a2db1561b55135327",
  "id": "52cc79123db8711b6713554a"
}

POST https://api.nsone.net/v1/monitoring/jobs/:jobid

POST Update details of a monitoring job

Change the configuration details of an existing monitoring job. See the documentation for PUT /monitoring/jobs for a detailed explanation of the input.

Request URL:

https://api.nsone.net/v1/monitoring/jobs/:jobid

Example URL:

https://api.nsone.net/v1/monitoring/jobs/52cc79123db8711b6713554a

Example Request:

{
  "notes": "Some new notes for this job",
  "policy": "all",
  "frequency": 40
}

Example Response:

{
  "status": {
    "global": {
      "since": 1389458558,
      "status": "pending"
    }
  },
  "notes": "Some new notes for this job",
  "policy": "all",
  "frequency": 40,
  "regions": [
    "lga",
    "sjc"
  ],
  "region_scope": "fixed",
  "active": true,
  "rapid_recheck": false,
  "name": "myhost.com:443 monitor",
  "job_type": "tcp",
  "config": {
    "ssl": "1",
    "send": "HEAD / HTTP/1.0\r\n\r\n",
    "port": 443,
    "host": "1.2.3.4"
  },
  "rules": [
    {
      "value": "200 OK",
      "comparison": "contains",
      "key": "output"
    },
    {
      "value": 200,
      "comparison": "<=",
      "key": "connect"
    }
  ],
  "notify_delay": 65,
  "notify_repeat": 0,
  "notify_failback": true,
  "notify_regional": false,
  "notify_list": "52cc775a2db1561b55135327",
  "id": "52cc79123db8711b6713554a"
}

DELETE https://api.nsone.net/v1/monitoring/jobs/:jobid

DELETE Remove a monitoring job

Immediately terminates and deletes an existing monitoring job. There is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/monitoring/jobs/:jobid

Example URL:

https://api.nsone.net/v1/monitoring/jobs/52cc79123db8711b6713554a

GET https://api.nsone.net/v1/monitoring/history/jobid?start=&end=&period=24h&limit=&region=global&exact=

GET Get historical status of monitoring job

Returns historical status details of a monitoring job (if jobid is included in the URL) or of all monitoring jobs under the account (if no jobid is specified). You may restrict the time period to show with start and end (Unix timestamps) or by specifying a period (one of 1h24h, or 30d); limit the number of results with limit; and restrict to results from a specific region code. You may also specify exact (a boolean, if true you must also specify start): then, the status as of the exact start and end times is computed and returned as part of the status history.

ParameterTypeDescriptionRequired?
jobidStringYes
startNumberAbsolute start time in UNIX timestampNo
endNumberAbsolute end time in UNIX timestamp (defaults to current time)No
periodStringPossible values: '1h', '24h', '30d'No
limitNumberMaximum number of resultsNo
regionStringRegion Code, Example: 'global'No
exactBooleanNo


GET https://api.nsone.net/v1/monitoring/metric/jobid?region=global&metric=rtt&period=30d

GET Get historical metrics for monitoring job

Returns historical metrics generated by monitoring jobs, such as response time, packet loss, TCP connect time, etc. The metrics in the response depend on the job — metrics available for each job type are returned by /monitoring/jobtypes. If you include a jobid in the URL, only metrics for that job are returned; otherwise, metrics for all jobs are returned subject to the other filtering parameters, which include:

  • region: a region code; may be either global or a specific region as listed in /monitoring/regionsYou may only specify this parameter if you also specify a specific jobid. Only metrics from the specific region are returned. If global, the average value of the metric across all active regions is returned.

  • metric: a metric name, e.g. rtt or connect. Valid metric names are described by /monitoring/jobtypes and depend on the type of monitoring job. Only metrics for jobs providing a matching metric name will be returned.

  • period: one of 1h24h, or 30d depending on the length of history you wish to retrieve. The number and interval of the data po s returned depends on the period. The response is a list of "metrics" objects, each containing jobidregion, and metrics fields. The metric field is a mapping of metric names to statistics objects including the average value of the metric over the period (excluding times when no data was collected), and a graph for the metric over the period.

Request URL:

https://api.nsone.net/v1/monitoring/metrics/:jobid[?metric=null][&period=24h][&region=null]

Example URL:

https://api.nsone.net/v1/monitoring/metrics/52a27d4397d5f07003fdbe7b?period=30d&metric=rtt

Example Response:

[
  {
    "jobid": "52a27d4397d5f07003fdbe7b",
    "region": "global",
    "metrics": {
      "rtt": {
        "avg": 36.49545722537571,
        "graph": [
          [
            1390852209,
            36.93605295817057
          ],
          [
            1390852420,
            34.418270111083984
          ],
          [
            1390852631,
            36.07466252644857
          ],
          ...
        ]
      }
    }
  },
  {
    "jobid": "52a27d4397d5f07003fdbe7b",
    "region": "lga",
    "metrics": {
      "rtt": {
        "avg": 36.338624795277916,
        "graph": [
          [
            1390852209,
            36.93605295817057
          ],
          [
            1390852420,
            34.418270111083984
          ],
          [
            1390852631,
            36.07466252644857
          ],
          ...
        ]
      }
    }
  },
  {
    "jobid": "52a27d4397d5f07003fdbe7b",
    "region": "dal",
    "metrics": {
      "rtt": {
        "avg": 37.40758143530952,
        "graph": [
          [
            1390852209,
            36.93605295817057
          ],
          [
            1390852420,
            36.93605295817057
          ],
          [
            1390852631,
            36.93605295817057
          ],
          ...
        ]
      }
    }
  }
]

GET https://api.nsone.net/v1/monitoring/jobtypes

GET List available monitoring job types

Returns the list of all available monitoring jobs types, and details of configuration options for each job type.

Request URL:

https://api.nsone.net/v1/monitoring/jobtypes

Example Response:

{
  "tcp": {
    "desc": "Connect to a TCP port on a host.",
    "results": {
      "connect": {
        "desc": "Time (in ms) for the connection to open.",
        "type": "number",
        "shortdesc": "Time to connect",
        "validator": "number",
        "metric": true,
        "comparators": [
          "<",
          ">",
          "<=",
          ">=",
          "==",
          "!="
        ]
      },
      "output": {
        "desc": "Output received from the connection, if any.",
        "type": "string",
        "shortdesc": "Output (if any)",
        "validator": "string",
        "metric": false,
        "comparators": [
          "contains"
        ]
      }
    },
    "config": {
      "port": {
        "validator": "number",
        "type": "number",
        "required": true,
        "desc": "TCP port to connect to on host.",
        "shortdesc": "TCP port"
      },
      "host": {
        "validator": "text",
        "type": "string",
        "required": true,
        "desc": "IP address or hostname to connect to.",
        "shortdesc": "IP address or hostname"
      },
      "ssl": {
        "desc": "Attempt to negotiate an SSL connection before sending/receiving protocol data.",
        "type": "checkbox",
        "shortdesc": "Connect with SSL",
        "validator": "checkbox",
        "required": false,
        "default": false
      },
      "connect_timeout": {
        "desc": "Timeout (in ms) before we give up trying to connect.",
        "type": "number",
        "shortdesc": "Connect timeout",
        "validator": "number",
        "required": false,
        "default": 2000
      },
      "send": {
        "desc": "A string to send to the host upon connecting.",
        "type": "string",
        "shortdesc": "String to send",
        "validator": "string",
        "required": false,
        "default": null
      },
      "response_timeout": {
        "desc": "Timeout (in ms) after connecting to wait for output.",
        "type": "number",
        "shortdesc": "Response timeout",
        "validator": "number",
        "required": false,
        "default": 1000
      }
    },
    "shortdesc": "TCP"
  },
  "ping": {
    "desc": "Ping a host using ICMP packets.",
    "results": {
      "loss": {
        "desc": "Percentage of ICMP echo packets with no response (timed out).",
        "type": "number",
        "shortdesc": "Percent packet loss",
        "validator": "number",
        "metric": true,
        "comparators": [
          "<",
          ">",
          "<=",
          ">=",
          "==",
          "!="
        ]
      },
      "rtt": {
        "desc": "Average round trip time (in ms) of returned pings.",
        "type": "number",
        "shortdesc": "Round trip time",
        "validator": "number",
        "metric": true,
        "comparators": [
          "<",
          ">",
          "<=",
          ">=",
          "==",
          "!="
        ]
      }
    },
    "config": {
      "timeout": {
        "desc": "Timeout (in ms) before we mark host failed.",
        "type": "number",
        "shortdesc": "Ping timeout",
        "validator": "number",
        "required": false,
        "default": 2000
      },
      "interval": {
        "desc": "Minimum time (in ms) to wait between sending each ICMP packet.  If less than the response time for an echo request, we will send the next packet immediately upon receiving a response.",
        "type": "number",
        "shortdesc": "Time between packets",
        "validator": "number",
        "required": false,
        "default": 0
      },
      "host": {
        "validator": "text",
        "type": "string",
        "required": true,
        "desc": "IP address or hostname to test using ICMP echo packets.",
        "shortdesc": "IP address or hostname to ping"
      },
      "count": {
        "desc": "Number of ICMP echo packets to send.  More take longer, but provide better RTT and packet loss statistics.",
        "type": "number",
        "shortdesc": "Number of packets to send",
        "validator": "number",
        "required": false,
        "default": 4
      }
    },
    "shortdesc": "Ping (ICMP)"
  }
}

GET https://api.nsone.net/v1/monitoring/regions

GET List available monitoring regions

Returns the list of all available monitoring regions, including display name for the region, the region code to use when provisioning, and the list of all subnets from which monitoring traffic is generated in each region. The response below is using subnets from the documentation address blocks (RFC 5737 and RFC 3849) do not use them in your access lists.

Request URL:

https://api.nsone.net/v1/monitoring/regions

Example Response:

[
  {
    "name": "Dallas",
    "code": "dal",
    "subnets": [
      "192.0.2.40/29",
      "2001:db8:4009:3::/64"
    ]
  },
  {
    "name": "Singapore",
    "code": "sin",
    "subnets": [
      "198.51.100.224/29",
      "2001:db8:1000:3::/64"
    ]
  },
  {
    "name": "San Jose",
    "code": "sjc",
    "subnets": [
      "192.0.2.152/29",
      "2001:db8:400c:3::/64"
    ]
  },
  {
    "name": "New York",
    "code": "lga",
    "subnets": [
      "203.0.113.16/29",
      "2001:db8:4004:3::/64"
    ]
  },
  {
    "name": "Amsterdam",
    "code": "ams",
    "subnets": [
      "203.0.113.48/29",
      "2001:db8:e:3::/64"
    ]
  }
]

Notification lists

GET https://api.nsone.net/v1/lists

GETList all notification lists

Returns all configured notification lists. Each list consists of a name, an id for use in connecting notification lists in monitoring jobs, and a notify_list of configured notifiers.

Request URL:

https://api.nsone.net/v1/lists

Example Response:

[
  {
    "id": "52b49af12f21574b0e0bffe7",
    "name": "Awesome List",
    "notify_list": [
      {
        "type": "email",
        "config": {
          "email": "[email protected]"
        }
      },
      {
        "type": "datafeed",
        "config": {
          "sourceid": "5872814cc08b23c697e88c054d032780"
        }
      },
      {
        "type": "user",
        "config": {
          "user": "myuser"
        }
      }
    ]
  },
  ...
]

GET https://api.nsone.net/v1/lists/:listid

GETGet details of a notification list

Gets the details and notifiers associated with a specific notification list.

Request URL:

https://api.nsone.net/v1/lists/:listid

Example URL:

https://api.nsone.net/v1/lists/52b49af12f21574b0e0bffe7

Example Response:

{
  "id": "52b49af12f21574b0e0bffe7",
  "name": "Awesome List",
  "notify_list": [
    {
      "type": "email",
      "config": {
        "email": "[email protected]"
      }
    },
    {
      "type": "datafeed",
      "config": {
        "sourceid": "5872814cc08b23c697e88c054d032780"
      }
    },
    {
      "type": "user",
      "config": {
        "user": "myuser"
      }
    }
  ]
}

PUT https://api.nsone.net/v1/lists

PUTCreate a new notification list

Creates a new list for notifications. You may specify a freeform display name for the list. The notify_list itself is a list of notifier objects including notifier type and a config dictionary with configuration details for the given notifier type. Available notifiers are indicated in /notifytypes. All notifiers in a notification list will receive notifications whenever an event is send to the list (e.g., when a monitoring job fails).

Copy CodeCreate a new notification list that pushes to Data Feeds

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"Critical Notifications", "notify_list":[ {"type":"email", "config":{"email":"[email protected]"}}, {"type":"datafeed", "config":{"sourceid":"b85579edee904f0f204a6eb07b3f8a1f"}} ]}' https://api.nsone.net/v1/lists

We create a new list to receive monitoring notifications. Notifications will be sent to both an email address ([email protected]) and to an NSONE Data Source for use with NSONE's DNS metadata. To connect a datafeed notifier, the sourceid must be a nsone_monitoring Data Source. Status changes for monitors connected to this notification list will be delivered to the Data Source, and if a Data Feed is configured under the source for the monitor, then the changes will be pushed to all metadata tables connected to the Data Feed.

Request URL:

https://api.nsone.net/v1/lists

Example Request:

{
  "name": "My Notification List",
  "notify_list": [
    {
      "config": {
        "email": "[email protected]"
      },
      "type": "email"
    },
    {
      "config": {
        "user": "myuser"
      },
      "type": "user"
    },
    {
      "config": {
        "sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
      },
      "type": "datafeed"
    }
  ]
}

Example Response:

{
  "id": "52b49af12f21574b0e0bffe8",
  "name": "My Notification List",
  "notify_list": [
    {
      "config": {
        "email": "[email protected]"
      },
      "type": "email"
    },
    {
      "config": {
        "user": "myuser"
      },
      "type": "user"
    },
    {
      "config": {
        "sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
      },
      "type": "datafeed"
    }
  ]
}

POST https://api.nsone.net/v1/lists/:listid

POSTUpdate a notification list

Add or remove entries or otherwise update a notification list.

Request URL:

https://api.nsone.net/v1/lists/:listid

Example URL:

https://api.nsone.net/v1/lists/52b49af12f21574b0e0bffe8

Example Request:

{
  "id": "52b49af12f21574b0e0bffe8",
  "name": "My Notification List",
  "notify_list": [
    {
      "config": {
        "email": "[email protected]"
      },
      "type": "email"
    },
    {
      "config": {
        "user": "myuser"
      },
      "type": "user"
    },
    {
      "config": {
        "sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
      },
      "type": "datafeed"
    },
    {
      "config": {
        "email": "[email protected]"
      },
      "type": "email"
    }
  ]
}

Example Response:

{
  "id": "52b49af12f21574b0e0bffe8",
  "name": "My Notification List",
  "notify_list": [
    {
      "config": {
        "email": "[email protected]"
      },
      "type": "email"
    },
    {
      "config": {
        "user": "myuser"
      },
      "type": "user"
    },
    {
      "config": {
        "sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
      },
      "type": "datafeed"
    },
    {
      "config": {
        "email": "[email protected]"
      },
      "type": "email"
    }
  ]
}

DELETE https://api.nsone.net/v1/lists/:listid

DELETERemove a notification list

Immediately deletes an existing notification list. Any monitoring jobs configured to notify this list will stop sending notifications until reconfigured to notify a different list. There is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/lists/:listid

Example URL:

https://api.nsone.net/v1/lists/52b49af12f21574b0e0bffe8

GET https://api.nsone.net/v1/notifytypes

GETList available notification types

Returns the list of all available notifiers for delivery of monitoring status notifications, and details of configuration options for each notification type.

Request URL:

https://api.nsone.net/v1/notifytypes

Example Response:

{
  "user": {
    "desc": "Send notification to a user according to their notification preferences.",
    "config": {
      "user": {
        "validator": "username",
        "type": "string",
        "required": true,
        "desc": "User to notify",
        "shortdesc": "Username"
      }
    },
    "shortdesc": "User"
  },
  "email": {
    "desc": "Send notification to an email address.",
    "config": {
      "email": {
        "validator": "email",
        "type": "string",
        "required": true,
        "desc": "Email address to send notification",
        "shortdesc": "Email address"
      }
    },
    "shortdesc": "Email"
  },
  "datafeed": {
    "desc": "Push notification to an NSONE Data Source to update all\n    Data Feeds connected to the Source.  This notifier only pushes\n    \"up/down\" status to the Data Feeds.  Unless you have configured\n    a Feed to act on updates from specific monitoring regions,\n    only \"global\" status will be pushed to your Feeds.",
    "config": {
      "sourceid": {
        "validator": "datasource",
        "type": "datasource",
        "required": true,
        "desc": "NSONE Data Source to receive notifications",
        "shortdesc": "NSONE Data Source"
      }
    },
    "shortdesc": "NSONE Data Feed"
  },
  ...
}

Account Management

General

GET https://api.nsone.net/v1/account/settings

GET Get account contact details and settings

Returns the basic contact details associated with your account.

Request URL:

https://api.nsone.net/v1/account/settings

Example Response:

{
  "email": "[email protected]",
  "address": {
    "country": "US",
    "street": "Some Address Suite 2100",
    "state": "NY",
    "city": "New York",
    "postalcode": "10005"
  },
  "phone": "",
  "customerid": 5309,
  "company": "NSONE API Example Account",
  "lastname": "Example",
  "firstname": "API"
}

POST https://api.nsone.net/v1/account/settings

POST Modify contact details and settings

You may change most of your basic contact details, except customerid.

Request URL:

https://api.nsone.net/v1/account/settings

Example Request:

{
  "lastname": "Smith",
  "firstname": "John"
}

Example Response:

{
  "email": "[email protected]",
  "address": {
    "country": "US",
    "street": "Some Address Suite 2100",
    "state": "NY",
    "city": "New York",
    "postalcode": "10005"
  },
  "phone": "",
  "customerid": 5309,
  "company": "NSONE API Example Account",
  "lastname": "Smith",
  "firstname": "John"
}

GET https://api.nsone.net/v1/account/usagewarnings

GET Get overage alerting settings

Returns toggles and thresholds used when sending overage warning alert messages to users with billing notifications enabled.

Request URL:

https://api.nsone.net/v1/account/usagewarnings

Example Response:

{
  "queries": {
    "send_warnings": true,
    "warning_2": 90,
    "warning_1": 80
  },
  "records": {
    "send_warnings": false,
    "warning_2": 80,
    "warning_1": 50
  }
}

POST https://api.nsone.net/v1/account/usagewarnings

POST Modify overage alerting settings

Changes alerting toggles and thresholds for overage warning alert messages. First thresholds (warning_1) must be smaller than second ones (warning_2) and all thresholds must be percentages between 0 and 100.

Request URL:

https://api.nsone.net/v1/account/usagewarnings

Example Request:

{
  "queries": {
    "warning_2": 90
  }
}

Example Response:

{
  "queries": {
    "send_warnings": true,
    "warning_2": 90,
    "warning_1": 60
  },
  "records": {
    "send_warnings": false,
    "warning_2": 80,
    "warning_1": 50
  }
}

User

GET https://api.nsone.net/v1/account/users

GETGet all account users

Returns a list of all users with access to the account. Notification settings (notify) and access restrictions (permissions) are included. If any specific access right is omitted from permissionsthen it defaults to true (allowed). In the example below, "New User" is only allowed to manage the example.com zone and can do nothing else in the account; "API Example" has full permissions.

Users may belong to "Teams" in which case they inherit the permissions of the Teams. If a user belongs to multiple Teams, then they inherit the union of permissions of the Teams they belong to. For example, if a user belongs to two Teams, and one Team has the dns.manage_zones permission and the other does not, then the user will have that permission.

If a user does not belong to any Teams, then their permissions may be modified directly and are just for them. If a user does belong to one or more Teams, then the permissions returned with the user are the computed permissions from all the Teams to which they belong and may not be modified directly (instead, modify the relevant Team permissions).

Request URL:

https://api.nsone.net/v1/account/users

Example Response:

[
  {
    "permissions": {},
    "teams": [],
    "email": "[email protected]",
    "last_access": 1376325771,
    "notify": {
      "billing": true
    },
    "name": "API Example",
    "username": "apiexample",
    "ip_whitelist_strict": false,
    "ip_whitelist": []
  },
  {
    "permissions": {
      "dns": {
        "view_zones": true,
        "manage_zones": true,
        "zones_allow_by_default": false,
        "zones_deny": [],
        "zones_allow": ["example.com"]
      },
      "data": {
        "push_to_datafeeds": false,
        "manage_datasources": false,
        "manage_datafeeds": false
      },
      "account": {
        "manage_payment_methods": false,
        "manage_plan": false,
        "manage_teams": false,
        "manage_apikeys": false,
        "manage_account_settings": false,
        "view_activity_log": false,
        "view_invoices": false,
        "manage_users": false
      },
      "teams": ["520422919f782d37dffb588a"],
      "monitoring": {
        "manage_lists": false,
        "manage_jobs": false,
        "view_jobs": false
      }
    },
    "email": "[email protected]",
    "last_access": null,
    "notify": {
      "billing": true
    },
    "name": "New User",
    "username": "newuser",
    "ip_whitelist_strict": false,
    "ip_whitelist": []
  }
]

GET https://api.nsone.net/v1/account/users/:username

GETGet a user's details

Returns the details for a single user.

Request URL:

https://api.nsone.net/v1/account/users/:username

Example URL:

https://api.nsone.net/v1/account/users/newuser

Example Response:

{
  "permissions": {
    "dns": {
      "view_zones": true,
      "manage_zones": true,
      "zones_allow_by_default": false,
      "zones_deny": [],
      "zones_allow": ["example.com"]
    },
    "data": {
      "push_to_datafeeds": false,
      "manage_datasources": false,
      "manage_datafeeds": false
    },
    "account": {
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_account_settings": false,
      "view_activity_log": false,
      "view_invoices": false,
      "manage_users": false
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "teams": ["520422919f782d37dffb588a"],
  "email": "[email protected]",
  "last_access": null,
  "notify": {
    "billing": true
  },
  "name": "New User",
  "username": "newuser",
  "ip_whitelist_strict": false,
  "ip_whitelist": []
}

PUT https://api.nsone.net/v1/account/users/:username

PUTAdd a user to account

Creates a new user. An invitation email will be sent to the user's email address, which they can click to set a password and log into my.nsone.net. The user cannot log in until they accept the invitation and set a password.

If you add the user to one or more Teams, they will inherit the permissions of those teams and any permissions you include in the request body will be ignored. If the user is not added to any Teams, then you may explicitly set permissions for the user. You can restrict access to this user by adding IP addresses or CIDR blocks in the ip_whitelist array property. i.e. ip_whitelist: ['104.20.48.182', '104.20.49.0/24'].

Request URL:

https://api.nsone.net/v1/account/users/:username

Example URL:

https://api.nsone.net/v1/account/users/newuser

Example Request:

{
  "username": "newuser",
  "email": "[email protected]",
  "name": "New User",
  "teams": [],
  "permissions": {
    "data": {
      "push_to_datafeeds": false,
      "manage_datafeeds": false,
      "manage_datasources": false
    },
    "account": {
      "view_invoices": false,
      "view_activity_log": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_users": false,
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_account_settings": false
    },
    "dns": {
      "zones_allow": [
        "example.com"
      ],
      "zones_allow_by_default": false,
      "manage_zones": false,
      "view_zones": true
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  }
}

Example Response:

{
  "permissions": {
    "dns": {
      "view_zones": true,
      "manage_zones": true,
      "zones_allow_by_default": false,
      "zones_deny": [],
      "zones_allow": ["example.com"]
    },
    "data": {
      "push_to_datafeeds": false,
      "manage_datasources": false,
      "manage_datafeeds": false
    },
    "account": {
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_account_settings": false,
      "view_activity_log": false,
      "view_invoices": false,
      "manage_users": false
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "teams": [],
  "email": "[email protected]",
  "last_access": null,
  "notify": {
    "billing": true
  },
  "name": "New User",
  "username": "newuser",
  "ip_whitelist_strict": false,
  "ip_whitelist": []
}

POST https://api.nsone.net/v1/account/users/:username

POSTUpdate a user's details

Change contact details, notification settings, or access rights for a user.

If the user belongs to any Teams or you are adding the user to their first Team, you may not directly set permissions for the user. If you are removing the user from all Teams to which they belong, and you do not explicitly set permissions, their permissions will be set equivalently to what they were as a member of the Teams. You can restrict access to this user by adding IP addresses or CIDR blocks in the ip_whitelist array property. i.e. ip_whitelist: ['104.20.48.182', '104.20.49.0/24'].

Request URL:

https://api.nsone.net/v1/account/users/:username

Example URL:

https://api.nsone.net/v1/account/users/newuser

Example Request:

{
  "name": "Jane Smith"
}

Example Response:

{
  "permissions": {
    "dns": {
      "view_zones": true,
      "manage_zones": true,
      "zones_allow_by_default": false,
      "zones_deny": [],
      "zones_allow": ["example.com"]
    },
    "data": {
      "push_to_datafeeds": false,
      "manage_datasources": false,
      "manage_datafeeds": false
    },
    "account": {
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_account_settings": false,
      "view_activity_log": false,
      "view_invoices": false,
      "manage_users": false
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "teams": [],
  "email": "[email protected]",
  "last_access": null,
  "notify": {
    "billing": true
  },
  "name": "Jane Smith",
  "username": "newuser",
  "ip_whitelist_strict": false,
  "ip_whitelist": []
}

DELETE https://api.nsone.net/v1/account/users/username

DELETERemove a user

Deletes a user from the account. They will no longer be able to log into my.nsone.net. There is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/account/users/:username

Example URL:

https://api.nsone.net/v1/account/users/newuser

POST https://api.nsone.net/v1/account/reinvite/username

POSTResend invitation to a user

In case a new user did not receive their invitation email, or in case the invitation has expired, you may re-send the invitation. However, if the user has already logged in, you may not re-send the invitation — they should click the "Forgot Password" link to verify their email address and reset their password. There is no response other than the HTTP status code.

Copy CodeInvite a new user with full access to your account

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"username":"newuser", "name":"New User", "email":"[email protected]"}' https://api.nsone.net/v1/account/users/newuser

An invitation email will be sent to [email protected] allowing them to set a password and log in to my.nsone.net.

Request URL:

https://api.nsone.net/v1/account/reinvite/:username

Example URL:

https://api.nsone.net/v1/account/reinvite/newuser

API Key

GET https://api.nsone.net/v1/account/apikeys

GETGet all API Keys

Returns a list of all API Keys under the account, including access rights (permissions) and the actual key to be used when contacting the NSONE API. API Keys may belong to Teams with the same semantics as Users.

Request URL:

https://api.nsone.net/v1/account/apikeys

Example Response:

[
  {
    "permissions": {
      "dns": {
        "zones_allow_by_default": true,
        "view_zones": true,
        "zones_deny": [],
        "manage_zones": true,
        "zones_allow": []
      },
      "data": {
        "push_to_datafeeds": true,
        "manage_datasources": true,
        "manage_datafeeds": true
      },
      "account": {
        "manage_payment_methods": true,
        "manage_plan": true,
        "manage_teams": true,
        "manage_apikeys": true,
        "manage_account_settings": true,
        "view_activity_log": true,
        "view_invoices": true,
        "manage_users": true
      },
      "monitoring": {
        "manage_lists": false,
        "manage_jobs": false,
        "view_jobs": false
      }
    },
    "teams": [],
    "id": "520422919f782d37dffb588a",
    "last_access": null,
    "key": "rifGeRNMshCOKwlaYBcu",
    "name": "API Example App",
    "ip_whitelist_strict": false,
    "ip_whitelist": []
  },
  {
    "permissions": {
      "dns": {
        "zones_allow_by_default": false,
        "view_zones": true,
        "manage_zones": false,
        "zones_allow": [
          "example.com"
        ]
      },
      "data": {
        "push_to_datafeeds": false,
        "manage_datasources": false,
        "manage_datafeeds": false
      },
      "account": {
        "manage_payment_methods": false,
        "manage_plan": false,
        "manage_teams": false,
        "manage_apikeys": false,
        "manage_account_settings": false,
        "view_activity_log": false,
        "view_invoices": false,
        "manage_users": false
      },
      "monitoring": {
        "manage_lists": false,
        "manage_jobs": false,
        "view_jobs": false
      }
    },
    "teams": ["52276047830f787e2ff88d4c"],
    "id": "520845159f782d5b1a10a86a",
    "last_access": null,
    "key": "MoEN3FJdcGelNSHHvKeO",
    "name": "My Application",
    "ip_whitelist_strict": false,
    "ip_whitelist": []
  }
]

GET https://api.nsone.net/v1/account/apikeys/:keyid

GETGet an API Key's details

Returns details, including permissions, for a single API Key. Note: do not use the API Key itself as the keyid in the URL — use the id of the key. Keep the API Key string secret — it grants access to your account!

Request URL:

https://api.nsone.net/v1/account/apikeys/:keyid

Example URL:

https://api.nsone.net/v1/account/apikeys/520422919f782d37dffb588a

Example Response:

{
  "permissions": {
    "dns": {
      "zones_allow_by_default": true,
      "view_zones": true,
      "zones_deny": [],
      "manage_zones": true,
      "zones_allow": []
    },
    "data": {
      "push_to_datafeeds": true,
      "manage_datasources": true,
      "manage_datafeeds": true
    },
    "account": {
      "manage_payment_methods": true,
      "manage_plan": true,
      "manage_teams": true,
      "manage_apikeys": true,
      "manage_account_settings": true,
      "view_activity_log": true,
      "view_invoices": true,
      "manage_users": true
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "teams": ["52276047830f787e2ff88d4c"],
  "id": "520422919f782d37dffb588a",
  "last_access": null,
  "key": "rifGeRNMshCOKwlaYBcu",
  "name": "API Example App",
  "ip_whitelist_strict": false,
  "ip_whitelist": []
}

PUT https://api.nsone.net/v1/account/apikeys

PUTCreate a new API Key

Creates a new API Key. You should explicitly restrict access rights for the API Key to include only what the application requires. If you add the API Key to one or more Teams, you may not directly set its permissions and the API Key will inherit access rights from its Teams. The new API Key string is returned in the key field in the response — keep it secret, keep it safe. If it is compromised, delete the API Key immediately. You can restrict access to this key by adding IP addresses or CIDR blocks in the ip_whitelist array property. i.e. ip_whitelist: ['104.20.48.182', '104.20.49.0/24'].

Copy CodeCreate an API Key that can only view one zone

curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"name":"My Application", "permissions":{"dns":{"view_zones":true, "manage_zones":false, "zones_allow_by_default":false, "zones_allow":["example.com"]}, "account":{"manage_account_settings":false, "manage_payment_methods":false, "manage_plan":false, "manage_teams":false, "manage_users":false, "manage_apikeys":false, "view_activity_log":false, "view_invoices":false}, "data":{"manage_datasources":false, "manage_datafeeds":false, "push_to_datafeeds":false}, "monitoring":{"manage_lists":false, "manage_jobs":false, "view_jobs":false} }}' https://api.nsone.net/v1/account/apikeys

You must explicitly deny permissions you do not want a new API Key (or User) to have. Since zones_allow_by_default is false, the user will have access only to zones in zones_allow. We grant this user access to example.com only — and since they only have view_zones access, they can only look at the zone's configuration and stats, and can make no changes.

Request URL:

https://api.nsone.net/v1/account/apikeys

Example Request:

{
  "permissions": {
    "data": {
      "push_to_datafeeds": false,
      "manage_datafeeds": false,
      "manage_datasources": false
    },
    "account": {
      "view_invoices": false,
      "view_activity_log": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_users": false,
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_account_settings": false
    },
    "dns": {
      "zones_allow": [
        "example.com"
      ],
      "zones_allow_by_default": false,
      "manage_zones": false,
      "view_zones": true
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "teams": [],
  "name": "My Application"
}

Example Response:

{
  "permissions": {
    "dns": {
      "zones_allow_by_default": false,
      "view_zones": true,
      "manage_zones": false,
      "zones_allow": [
        "example.com"
      ]
    },
    "data": {
      "push_to_datafeeds": false,
      "manage_datasources": false,
      "manage_datafeeds": false
    },
    "account": {
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_account_settings": false,
      "view_activity_log": false,
      "view_invoices": false,
      "manage_users": false
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "teams": [],
  "id": "520845159f782d5b1a10a86a",
  "last_access": null,
  "key": "MoEN3FJdcGelNSHHvKeO",
  "name": "My Application",
  "ip_whitelist_strict": false,
  "ip_whitelist": []
}

POST https://api.nsone.net/v1/account/apikeys/:keyid

POSTModify details of an API Key

Change name or access rights for an API Key. You can restrict access to this user by adding IP addresses or CIDR blocks in the ip_whitelist array property. i.e. ip_whitelist: ['104.20.48.182', '104.20.49.0/24'].


Request URL:

https://api.nsone.net/v1/account/apikeys/:keyid

Example URL:

https://api.nsone.net/v1/account/apikeys/520845159f782d5b1a10a86a

Example Request:

{
  "name": "Another application"
}

Example Response:

{
  "permissions": {
    "dns": {
      "zones_allow_by_default": false,
      "view_zones": true,
      "manage_zones": false,
      "zones_allow": [
        "example.com"
      ]
    },
    "data": {
      "push_to_datafeeds": false,
      "manage_datasources": false,
      "manage_datafeeds": false
    },
    "account": {
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_account_settings": false,
      "view_activity_log": false,
      "view_invoices": false,
      "manage_users": false
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "teams": [],
  "id": "520845159f782d5b1a10a86a",
  "last_access": null,
  "key": "MoEN3FJdcGelNSHHvKeO",
  "name": "Another application",
  "ip_whitelist_strict": false,
  "ip_whitelist": []
}

DELETE https://api.nsone.net/v1/account/apikeys/:keyid

DELETEDelete an API Key

Deletes an API Key. Any applications, scripts, or tools you have that are using this API Key will no longer be able to access your account. There is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/account/apikeys/:keyid

Example URL:

https://api.nsone.net/v1/account/apikeys/520845159f782d5b1a10a86a

Team

GET https://api.nsone.net/v1/account/teams

GETGet all Teams

Returns a list of all Teams under the account, including access rights (permissions) associated with Users and API Keys in the team.

Request URL:

https://api.nsone.net/v1/account/teams

Example Response:

[
  {
    "permissions": {
      "dns": {
        "zones_allow_by_default": true,
        "view_zones": true,
        "zones_deny": [],
        "manage_zones": true,
        "zones_allow": []
      },
      "data": {
        "push_to_datafeeds": true,
        "manage_datasources": true,
        "manage_datafeeds": true
      },
      "account": {
        "manage_payment_methods": true,
        "manage_plan": true,
        "manage_teams": true,
        "manage_apikeys": true,
        "manage_account_settings": true,
        "view_activity_log": true,
        "view_invoices": true,
        "manage_users": true
      },
      "monitoring": {
        "manage_lists": false,
        "manage_jobs": false,
        "view_jobs": false
      }
    },
    "id": "520422919f782d37dffb588a",
    "name": "API Example Team",
    "ip_whitelist": []
  },
  {
    "permissions": {
      "dns": {
        "zones_allow_by_default": false,
        "view_zones": true,
        "manage_zones": false,
        "zones_allow": [
          "example.com"
        ]
      },
      "data": {
        "push_to_datafeeds": false,
        "manage_datasources": false,
        "manage_datafeeds": false
      },
      "account": {
        "manage_payment_methods": false,
        "manage_plan": false,
        "manage_teams": false,
        "manage_apikeys": false,
        "manage_account_settings": false,
        "view_activity_log": false,
        "view_invoices": false,
        "manage_users": false
      },
      "monitoring": {
        "manage_lists": false,
        "manage_jobs": false,
        "view_jobs": false
      }
    },
    "id": "520845159f782d5b1a10a86a",
    "name": "My Other Team",
    "ip_whitelist": []
  }
]

GET https://api.nsone.net/v1/account/teams/:teamid

GETGet a Team's details

Returns details, including permissions, for a single Team.

Request URL:

https://api.nsone.net/v1/account/teams/:teamid

Example URL:

https://api.nsone.net/v1/account/teams/520845159f782d5b1a10a86a

Example Response:

{
  "permissions": {
    "dns": {
      "zones_allow_by_default": true,
      "view_zones": true,
      "zones_deny": [],
      "manage_zones": true,
      "zones_allow": []
    },
    "data": {
      "push_to_datafeeds": true,
      "manage_datasources": true,
      "manage_datafeeds": true
    },
    "account": {
      "manage_payment_methods": true,
      "manage_plan": true,
      "manage_teams": true,
      "manage_apikeys": true,
      "manage_account_settings": true,
      "view_activity_log": true,
      "view_invoices": true,
      "manage_users": true
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "id": "520845159f782d5b1a10a86a",
  "name": "API Example Team",
  "ip_whitelist": []
}

PUT https://api.nsone.net/v1/account/teams

PUTCreate a new Team

Creates a new Team. You should explicitly restrict access rights for the Team to include only what team members will require. Once you have created a Team, you may add Users and API Keys to the team by adding the Team to the team field in the User and API Key objects. You can restrict access to this team by adding IP whitelist records in the ip_whitelist array property. Compared to users and apikeys, teams support names on whitelist records. i.e. ip_whitelist: [ {'name': 'Home Whitelist', 'values': ['104.20.48.182'], {'name': 'Multi Whitelist', 'values': ['104.20.49.0/24', '104.20.50.1']} ].

Request URL:

https://api.nsone.net/v1/account/teams

Example Request:

{
  "permissions": {
    "data": {
      "push_to_datafeeds": false,
      "manage_datafeeds": false,
      "manage_datasources": false
    },
    "account": {
      "view_invoices": false,
      "view_activity_log": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_users": false,
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_account_settings": false
    },
    "dns": {
      "zones_allow": [
        "example.com"
      ],
      "zones_allow_by_default": false,
      "manage_zones": false,
      "view_zones": true
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "ip_whitelist": [],
  "name": "My New Team"
}

Example Response:

{
  "permissions": {
    "dns": {
      "zones_allow_by_default": false,
      "view_zones": true,
      "manage_zones": false,
      "zones_allow": [
        "example.com"
      ]
    },
    "data": {
      "push_to_datafeeds": false,
      "manage_datasources": false,
      "manage_datafeeds": false
    },
    "account": {
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_account_settings": false,
      "view_activity_log": false,
      "view_invoices": false,
      "manage_users": false
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "id": "520845159f782d5b1a10a86a",
  "name": "My New Team",
  "ip_whitelist": []
}

POST https://api.nsone.net/v1/account/teams/teamid

POSTModify details of a Team

Change name or access rights for a Team. You can restrict access to this team by adding IP whitelist records in the ip_whitelist array property. Compared to users and apikeys, teams support names on whitelist records. i.e. ip_whitelist: [ {'name': 'Home Whitelist', 'values': ['104.20.48.182'], {'name': 'Multi Whitelist', 'values': ['104.20.49.0/24', '104.20.50.1']} ].

Request URL:

https://api.nsone.net/v1/account/teams/:teamid

Example URL:

https://api.nsone.net/v1/account/teams/520845159f782d5b1a10a86a

Example Response:

{
  "permissions": {
    "dns": {
      "zones_allow_by_default": false,
      "view_zones": true,
      "manage_zones": false,
      "zones_allow": [
        "example.com"
      ]
    },
    "data": {
      "push_to_datafeeds": false,
      "manage_datasources": false,
      "manage_datafeeds": false
    },
    "account": {
      "manage_payment_methods": false,
      "manage_plan": false,
      "manage_teams": false,
      "manage_apikeys": false,
      "manage_account_settings": false,
      "view_activity_log": false,
      "view_invoices": false,
      "manage_users": false
    },
    "monitoring": {
      "manage_lists": false,
      "manage_jobs": false,
      "view_jobs": false
    }
  },
  "id": "520845159f782d5b1a10a86a",
  "name": "New Team Name",
  "ip_whitelist": []
}

DELETE https://api.nsone.net/v1/account/teams/teamid

DELETEDelete a Team

Deletes a Team. Any Users or API Keys that belong to the Team will be removed from the Team. If they belong to other Teams, they will take on the permissions from the remaining Teams. If they only belong to the Team being deleted, they will be explicitly given permissions equivalent to those of the Team. There is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/account/teams/:teamid

Example URL:

https://api.nsone.net/v1/account/teams/520845159f782d5b1a10a86a

IP Whitelist

GET https://api.nsone.net/v1/account/whitelist

GETGet all IP Whitelists

Returns all the (global) IP Whitelist records for the account.

Example URL:

https://api.nsone.net/v1/account/whitelist

Example Response:

[
  {
    "id":  "7c65ca27-23f0-4c00-8906-ae24f9fe0ae5",
    "name": "New York Office",
    "values": ["192.0.2.0/24"]
  },
  {
    "id":  "ead8e0fb-cd99-4ae2-8643-1c9ab9eca4bc",
    "name": "San Francisco Office",
    "values": ["198.51.100.0/24"]
  },
]

GET https://api.nsone.net/v1/account/whitelist/id

GETGet an IP Whitelist Records details

Get an specific IP Whitelist Record by its unique ID.

Request URL:

https://api.nsone.net/v1/account/whitelist/:id

Example URL:

https://api.nsone.net/v1/account/whitelist/7c65ca27-23f0-4c00-8906-ae24f9fe0ae5

Example Response:

{
  "id":  "7c65ca27-23f0-4c00-8906-ae24f9fe0ae5",
  "name": "New York Office",
  "values": ["192.0.2.0/24"]
}

PUT https://api.nsone.net/v1/account/whitelist

PUTCreate a new IP Whitelist Record

Creates a new IP Whitelist Record.

Example URL:

https://api.nsone.net/v1/account/whitelist

Example Request:

{
  "name": "San Diego Office",
  "values": ["203.0.113.1", "203.0.113.2"]
}

Example Response:

{
  "id":  "873de209-16ca-4bfb-b53a-e495525cc298",
  "name": "San Diego Office",
  "values": ["203.0.113.1", "203.0.113.2"]
}

POST https://api.nsone.net/v1/account/whitelist/:id

POSTModify details of an IP Whitelist Record

Updates the properties of an existing IP Whitelist Record.

Request URL:

https://api.nsone.net/v1/account/whitelist/:id

Example URL:

https://api.nsone.net/v1/account/whitelist/873de209-16ca-4bfb-b53a-e495525cc298

Example Request:

{
  "name": "New IP Whitelist Record Name",
  "values": ["203.0.113.1", "203.0.113.2"]
}

Example Response:

{
  "id": "873de209-16ca-4bfb-b53a-e495525cc298",
  "name": "New IP Whitelist Record Name",
  "values": ["203.0.113.1", "203.0.113.2"]
}

DELETE https://api.nsone.net/v1/account/whitelist/:id

DELETEDelete an IP Whitelist Record

Request URL:

https://api.nsone.net/v1/account/whitelist/:id

Example URL:

https://api.nsone.net/v1/account/whitelist/873de209-16ca-4bfb-b53a-e495525cc298

Plan and Billing

GET https://api.nsone.net/v1/account/plantypes

GETGet self service subscription plans

Returns details of all currently available self service subscription plans and associated pricing. Each subscription plan is uniquely identified by the plan type and periodNote: details are returned regardless of your current plan, but at this time only users on the startupstarter, or basic plan types may change their subscription automatically. Users currently on other plans should contact [email protected].

Request URL:

https://api.nsone.net/v1/account/plantypes

Example Response:

[
  {
    "overage_order": "ascending",
    "overages": {
      "static": {
        "queries": "2",
        "records": "1"
      },
      "intelligent": {
        "queries": "6",
        "records": "1"
      },
      "dynamic": {
        "queries": "4",
        "records": "1"
      }
    },
    "monthly_price": "0.00",
    "discount": "0.00",
    "discount_type": "percentage",
    "included": {
      "any": {
        "queries": 1e+07,
        "records": 50
      },
      "static": {
        "queries": 0,
        "records": 0
      },
      "intelligent": {
        "queries": 0,
        "records": 0
      },
      "dynamic": {
        "queries": 0,
        "records": 0
      }
    },
    "recurring_cost": "0.00",
    "access_charges": {
      "static": "0.00",
      "intelligent": "0.00",
      "dynamic": "0.00"
    },
    "monitoring": {
      "jobs": 2,
      "frequency": 60,
      "regions": 1
    },
    "type": "startup",
    "period": "monthly"
  },
  {
    "overage_order": "ascending",
    "overages": {
      "static": {
        "queries": "0.75",
        "records": "0.25"
      },
      "intelligent": {
        "queries": "2",
        "records": "0.25"
      },
      "dynamic": {
        "queries": "1.25",
        "records": "0.25"
      }
    },
    "monthly_price": "50.00",
    "discount": "0.00",
    "discount_type": "percentage",
    "included": {
      "any": {
        "queries": 2.5e+07,
        "records": 250
      },
      "static": {
        "queries": 0,
        "records": 0
      },
      "intelligent": {
        "queries": 0,
        "records": 0
      },
      "dynamic": {
        "queries": 0,
        "records": 0
      }
    },
    "recurring_cost": "50.00",
    "access_charges": {
      "static": "0.00",
      "intelligent": "0.00",
      "dynamic": "0.00"
    },
    "monitoring": {
      "jobs": 25,
      "frequency": 20,
      "regions": 3
    },
    "type": "business",
    "period": "monthly"
  },
  {
    "overage_order": "ascending",
    "overages": {
      "static": {
        "queries": "0.75",
        "records": "0.25"
      },
      "intelligent": {
        "queries": "2",
        "records": "0.25"
      },
      "dynamic": {
        "queries": "1.25",
        "records": "0.25"
      }
    },
    "monthly_price": "47.50",
    "discount": "0.00",
    "discount_type": "percentage",
    "included": {
      "any": {
        "queries": 2.5e+07,
        "records": 250
      },
      "static": {
        "queries": 0,
        "records": 0
      },
      "intelligent": {
        "queries": 0,
        "records": 0
      },
      "dynamic": {
        "queries": 0,
        "records": 0
      }
    },
    "recurring_cost": "47.50",
    "access_charges": {
      "static": "0.00",
      "intelligent": "0.00",
      "dynamic": "0.00"
    },
    "monitoring": {
      "jobs": 25,
      "frequency": 20,
      "regions": 3
    },
    "type": "business",
    "period": "quarterly"
  },
  ...
]

GET https://api.nsone.net/v1/account/plan

GETGet current subscription plan details

Returns details of the current subscription for the account, including all applicable fees, charges, discounts, etc. The current balance, if any, is also returned.

Request URL:

https://api.nsone.net/v1/account/plan

Example Response:

{
  "type": "pro",
  "period": "annual"
  "monthly_price": "200.00",
  "discount": "0.00",
  "discount_type": "percentage",
  "recurring_cost": "2400.00",
  "locked": false,
  "included": {
    "any": {
      "queries": 2.5e+08,
      "records": 1500
    },
    "static": {
      "queries": 0,
      "records": 0
    },
    "intelligent": {
      "queries": 0,
      "records": 0
    },
    "dynamic": {
      "queries": 0,
      "records": 0
    }
  },
  "overage_order": "ascending",
  "overages": {
    "static": {
      "queries": "0.50",
      "records": "0.10"
    },
    "intelligent": {
      "queries": "1",
      "records": "0.10"
    },
    "dynamic": {
      "queries": "0.75",
      "records": "0.10"
    }
  },
  "access_charges": {
    "static": "0.00",
    "intelligent": "0.00",
    "dynamic": "0.00"
  },
  "monitoring": {
    "jobs": 250,
    "frequency": 5,
    "regions": 5
  },
  "balance": "0.00"
}

POST https://api.nsone.net/v1/account/plan

POSTChange your subscription plan

If you are on the startupstarter, or basic plan, and you have a valid credit card on file, you may call this method to instantly pay for and upgrade to a new subscription plan. You may change to a basic or advanced plan with a monthlyquarterlysemiannual, or annual term. Note: In this case, you will be charged the full price of the new plan as indicated in the recurring_cost field in the plan description. If you are currently on any other plan, you do not have a payment method on file, or you are requesting a change to the professionalenterpriseenterprise premiumplan, calling this method will submit a request to change your subscription plan, which we will review and respond to. In that case, you may also pass us notes about your request. If we submit a change request but cannot process it immediately, the response will not include a body.

Request URL:

https://api.nsone.net/v1/account/plan

Example Request:

{
  "type": "pro",
  "period": "annual"
}

Example Response:

{
  "overage_order": "ascending",
  "type": "pro",
  "balance": "2,400.00",
  "discount_type": "percentage",
  "monthly_price": "200.00",
  "access_charges": {
    "static": "0.00",
    "intelligent": "0.00",
    "dynamic": "0.00"
  },
  "period": "annual",
  "discount": "0.00",
  "included": {
    "any": {
      "queries": 2.5e+08,
      "records": 1500
    },
    "static": {
      "queries": 0,
      "records": 0
    },
    "intelligent": {
      "queries": 0,
      "records": 0
    },
    "dynamic": {
      "queries": 0,
      "records": 0
    }
  },
  "recurring_cost": "2400.00",
  "overages": {
    "static": {
      "queries": "0.50",
      "records": "0.10"
    },
    "intelligent": {
      "queries": "1",
      "records": "0.10"
    },
    "dynamic": {
      "queries": "0.75",
      "records": "0.10"
    }
  },
  "monitoring": {
    "jobs": 250,
    "frequency": 5,
    "regions": 5
  },
  "locked": true
}

GET https://api.nsone.net/v1/account/invoices

GETList invoices

Lists basic details of all historical and current invoices for the account.

Request URL:

https://api.nsone.net/v1/account/invoices

Example Response:

[
  {
    "due": 1377129600,
    "sent": 1375756229,
    "id": 11,
    "amount": "82.02",
    "status": "due"
  },
  {
    "due": 1375315200,
    "sent": 1373985364,
    "id": 10,
    "amount": "29.00",
    "status": "paid"
  },
  {
    "due": 1366588800,
    "sent": 1365215402,
    "id": 2,
    "amount": "0.00",
    "status": "paid"
  },
  {
    "due": 1369180800,
    "sent": 1367807401,
    "id": 4,
    "amount": "0.00",
    "status": "paid"
  }
]

GET https://api.nsone.net/v1/account/invoices/invoiceid?authtoken=d4a2080c926b85c9936908852454cb181249622a

GETDownload an invoice

The invoice is returned in PDF format. This method will directly return a PDF. The Content-Type and Content-Dispositionheaders will be set accordingly. However, if there is an error, the usual JSON error will be returned.

There are certain cases, such as in some browsers, where you will be unable to send the X-NSONE-Key authentication header to download a file intended to be saved to the user's filesystem, due to restrictions on some kinds of AJAX/XHR requests. In this case, you may use an alternative authentication mechanism for this method: add an authtoken parameter to the URL, consisting of a SHA1 hash of the concatenation of the API Key, the invoice id, and the sent field from /account/invoices for the invoice (as a string). For example: sha1('qACMD09OJXBxT7XOuRs8101373985364').

Request URL:

https://api.nsone.net/v1/account/invoices/:invoiceid[?authtoken=21900a196f...]

Example URL:

https://api.nsone.net/v1/account/invoices/727?authtoken=d4a2080c926b85c9936908852454cb181249622a

GET https://api.nsone.net/v1/account/billataglance

GETGet bill at a glance

Returns usage and charges that will appear on the next invoice.

Request URL:

https://api.nsone.net/v1/account/billataglance

Example Response:

{
  "plan": "startup",
  "period": "monthly",
  "last_invoice": 1377561600,
  "next_invoice": 1379721600,
  "next_base_invoice": 1379721600,
  "recurring_cost": "0.00"
  "recurring_cost_next_invoice": "0.00",
  "any": {
    "overage_order": "ascending",
    "query_credit": 1e+07,
    "record_credit": 50
  },
  "static": {
    "record_rate": "1",
    "access_charge": "0.00",
    "records": 14,
    "query_credit": 0,
    "query_cost": "0.00",
    "query_rate_per_million": "2",
    "queries": 5,
    "record_credit": 0,
    "record_cost": "0.00"
  },
  "dynamic": {
    "record_rate": "1",
    "access_charge": "0.00",
    "records": 2,
    "query_credit": 0,
    "query_cost": "0.00",
    "query_rate_per_million": "4",
    "queries": 10,
    "record_credit": 0,
    "record_cost": "0.00"
  },
  "intelligent": {
    "record_rate": "1",
    "access_charge": "0.00",
    "records": 0,
    "query_credit": 0,
    "query_cost": "0.00",
    "query_rate_per_million": "6",
    "queries": 0,
    "record_credit": 0,
    "record_cost": "0.00"
  },
  "totals": {
    "record_cost": "0.00",
    "record_credit": 16,
    "queries": 15,
    "query_credit": 15,
    "records": 16,
    "access_charge": "0.00",
    "query_cost": "0.00"
  },
  "balance": "0.00",
  "bill": "0.00"
}

Payment method

GET https://api.nsone.net/v1/account/paymentmethods

GETGet list of active payment methods

This method returns the list of all payment methods (credit cards) attached to the account.

Request URL:

https://api.nsone.net/v1/account/paymentmethods

Example Response:

[
  {
    "type": "creditcard",
    "default": true,
    "cc_expire_year": 2014,
    "cc_expire_month": 3,
    "firstname": "John",
    "lastname": "Smith",
    "company": "Joe Company",
    "cc_type": "mastercard",
    "phone": "222-555-5555",
    "address": {
      "country": "US",
      "street": "20 Awesome Street Suite 1234",
      "state": "NY",
      "city": "New York",
      "postalcode": "10005"
    },
    "cc_number_last4": "4444",
    "id": 8273
  },
  {
    "type": "creditcard",
    "cc_expire_year": 2016,
    "cc_expire_month": 4,
    "firstname": "Bob",
    "lastname": "Boberton",
    "company": "Joe Company",
    "cc_type": "amex",
    "phone": "212-867-5309",
    "address": {
      "country": "US",
      "street": "20 Awesome Street Suite 1234",
      "state": "NY",
      "city": "New York",
      "postalcode": "10005"
    },
    "cc_number_last4": "1000",
    "id": 6159
  }
]

GET https://api.nsone.net/v1/account/paymentmethods/:id

GETGet a payment method's details

This method returns just the details for a single payment method given its id.

Request URL:

https://api.nsone.net/v1/account/paymentmethods/:id

Example URL:

https://api.nsone.net/v1/account/paymentmethods/8273

Example Response:

{
  "type": "creditcard",
  "default": true,
  "cc_expire_year": 2014,
  "cc_expire_month": 3,
  "firstname": "John",
  "lastname": "Smith",
  "company": "Joe Company",
  "cc_type": "mastercard",
  "phone": "222-555-5555",
  "address": {
    "country": "US",
    "street": "20 Awesome Street Suite 1234",
    "state": "NY",
    "city": "New York",
    "postalcode": "10005"
  },
  "cc_number_last4": "4444",
  "id": 8273
}

PUT https://api.nsone.net/v1/account/paymentmethods

PUTAdd a new payment method

Adds a new credit card to the account. If you set default to true it will become the new default card we charge for new invoices. We will do a small pre-authorization charge to the credit card, which will be refunded.

Request URL:

https://api.nsone.net/v1/account/paymentmethods

Example Request:

{
  "address": {
    "country": "US",
    "postalcode": "10005",
    "state": "NY",
    "city": "New York",
    "street": "20 Awesome Street Suite 1234"
  },
  "phone": "222-555-5555",
  "company": "Joe Company",
  "type": "creditcard",
  "default": true,
  "cc_number": "5215888899994444",
  "cc_expire_year": 2014,
  "cc_expire_month": 3,
  "cc_cvv2": "1234",
  "firstname": "John",
  "lastname": "Smith"
}

Example Response:

{
  "type": "creditcard",
  "default": true,
  "cc_expire_year": 2014,
  "cc_expire_month": 3,
  "firstname": "John",
  "lastname": "Smith",
  "company": "Joe Company",
  "cc_type": "mastercard",
  "phone": "222-555-5555",
  "address": {
    "country": "US",
    "street": "20 Awesome Street Suite 1234",
    "state": "NY",
    "city": "New York",
    "postalcode": "10005"
  },
  "cc_number_last4": "4444",
  "id": 8273
}

POST https://api.nsone.net/v1/account/paymentmethods/id

POSTMake a payment method the default

Calling this method — with no request body — sets the requested payment method as the default one, and it will be charged for future invoices. You may not modify other details associated with an existing payment method — add a new one instead. There is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/account/paymentmethods/:id

Example URL:

https://api.nsone.net/v1/account/paymentmethods/8273

DELETE https://api.nsone.net/v1/account/paymentmethods/id

DELETEDelete a payment method

Deletes a credit card. You may not delete the last credit card from the account — add another one first. There is no response other than the HTTP status code.

Request URL:

https://api.nsone.net/v1/account/paymentmethods/:id

Example URL:

https://api.nsone.net/v1/account/paymentmethods/8273

Activity Log

GET https://api.nsone.net/v1/account/activity?limit=&start=&end=&resource_type=&user=&resource_id=

GETGet account activity log

Returns entries from the account activity log. By default, the most recent 20 entries are returned — get more by setting limit. You can also restrict the results to entries later than some start (Unix timestamp) or earlier than some end. If you specify a resource_type, only entries for resources of that type are returned. You may also restrict by user and resource_id. Activity log entries include a user_type which is one of "user", "apikey", or "system" depending on where the activity came from, and for "user" and "apikey" activity, the user_id is the username or API Key id, respectively. For "create" and "update" actions, any resource details are for the resource after the action is taken; for "delete" actions, any such details show the resource as it was prior to deletion.

Request URL:

https://api.nsone.net/v1/account/activity

Example Response:

[
  {
    "resource_type": "zonefile",
    "user_id": "myuser",
    "resource_id": "52276047830f787e2ff88d4c",
    "timestamp": 1378312263,
    "user_type": "user",
    "action": "create",
    "resource": {
      "id": "52276047830f787e2ff88d4c",
      "hostmaster": "[email protected]",
      "meta": {},
      "nx_ttl": 60,
      "retry": 3600,
      "zone": "myzone.net",
      "warnings": [],
      "refresh": 21600,
      "expiry": 1209600,
      "records": [
        {
          "id": "52276047830f787e2ff88d4f",
          "type": "NS",
          "tier": 1,
          "short_answers": [
            "dns1.p03.nsone.net",
            "dns2.p03.nsone.net",
            "dns3.p03.nsone.net",
            "dns4.p03.nsone.net"
          ],
          "domain": "myzone.net"
        },
        {
          "id": "52276047830f787e2ff88d53",
          "type": "A",
          "tier": 1,
          "short_answers": [
            "1.1.1.1",
            "2.2.2.2"
          ],
          "domain": "*.myzone.net"
        }
      ],
      "dns_servers": [
        "dns1.p03.nsone.net",
        "dns2.p03.nsone.net",
        "dns3.p03.nsone.net",
        "dns4.p03.nsone.net"
      ],
      "networks": [0],
      "network_pools": ["p03"]
    },
    "user_name": "My User",
    "id": "52276047830f787e2ff88d59"
  },
  {
    "resource_type": "user",
    "user_id": "myuser",
    "resource_id": "olduser",
    "timestamp": 1378312122,
    "user_type": "user",
    "action": "delete",
    "resource": {
      "permissions": {
        "dns": {
          "zones_allow_by_default": true,
          "view_zones": true,
          "zones_deny": [],
          "manage_zones": true,
          "zones_allow": []
        },
        "data": {
          "manage_datafeeds": true,
          "manage_datasources": true,
          "push_to_datafeeds": true
        },
        "account": {
          "manage_payment_methods": true,
          "manage_teams": true,
          "manage_apikeys": true,
          "manage_account_settings": true,
          "view_activity_log": true,
          "view_invoices": true,
          "manage_users": true,
          "manage_plan": true
        },
        "monitoring": {
          "manage_lists": false,
          "manage_jobs": false,
          "view_jobs": false
        }
      },
      "email": "[email protected]",
      "last_access": null,
      "notify": {
        "billing": true
      },
      "name": "Old User",
      "username": "olduser"
    },
    "user_name": "My User",
    "id": "52275fba830f787e2ff88d42"
  },
  ...
]

Statistics

QPS

GET https://api.nsone.net/v1/stats/qps

GET Account-wide DNS queries/second

Returns current queries per second (QPS) for the account. The QPS number is lagged by approximately 30 seconds for statistics collection; and the rate is computed over the preceding minute.

Request URL:

https://api.nsone.net/v1/stats/qps

Example Response:

{
  "qps": 8.2
}

GET https://api.nsone.net/v1/stats/qps/:zone

GET Queries/sec in a zone

Returns current queries per second (QPS) for a specific zone. The QPS number is lagged by approximately 30 seconds for statistics collection; and the rate is computed over the preceding minute.

Request URL:

https://api.nsone.net/v1/stats/qps/:zone

Example URL:

https://api.nsone.net/v1/stats/qps/example.com

Example Response:

{
  "qps": 6.7
}

GET https://api.nsone.net/v1/stats/qps/zone/domain/type

GET Queries/sec for a record

Returns current queries per second (QPS) for a specific record. The QPS number is lagged by approximately 30 seconds for statistics collection; and the rate is computed over the preceding minute.

Request URL:

https://api.nsone.net/v1/stats/qps/:zone/:domain/:type

Example URL:

https://api.nsone.net/v1/stats/qps/example.com/www.example.com/A

Example Response:

{
  "qps": 2.3
}

Usage

GET https://api.nsone.net/v1/stats/usage?period=24h&expand=false&aggregate=true&by_tier=false

GETAccount-wide usage statistics

Returns statistics and graphs for the entire account over a given period. Stats are returned as a list of stats "objects" containing various stats fields that correspond to the given entity. If domainrectype and zone fields are present in the object, the stats are for the given record; if only the zone field is present, the stats are aggregate stats for the zone; and if none of the fields is present, the stats are aggregate stats for the entire account.

You may specify the following query parameters:

  • period: one of 1h24h, or 30d; default 24h.

  • expandtrue or false; default false — if set, breaks down stats by zone, and if unset, shows aggregate stats for the entire account.

  • aggregatetrue or false; default true — if set, returns aggregated stats across all zones and billing tiers (even if expand and by_tier are true).

  • by_tiertrue or false; default false — if set, returns stats and graphs for each billing tier (in records_by_tier and queries_by_tier in each stats object). The first element corresponds to STATIC records/queries; the second to DYNAMICones; and the third to INTELLIGENT ones.

Copy CodeGet account-wide usage by billing tier for last 30 days

curl -X GET -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' "https://api.nsone.net/v1/stats/usage?period=30d&aggregate=false&by_tier=true"

Usage is returned broken down by billing tier with arrays like [<static>, <dynamic>, <intelligent>].

Request URL:

https://api.nsone.net/v1/stats/usage[?period=24h][&expand=false][&aggregate=true][&by_tier=false]

Example URL:

https://api.nsone.net/v1/stats/usage?period=24h&by_tier=true

Example Response:

[
  {
    "period": "24h",
    "zone": "example.com",
    "records": 3,
    "records_by_tier": [
      3,
      0,
      0
    ],
    "queries": 1756,
    "queries_by_tier": [
      1756,
      0,
      0
    ],
    "graph": [
      [
        1376236061,
        33
      ],
      [
        1376237808,
        60
      ],
      ...
    ],
    "graph_by_tier": [
      [
        [
          1376236061,
          33
        ],
        [
          1376237808,
          60
        ],
        ...
      ],
      [],
      []
    ]
  },
  ...
]

GET https://api.nsone.net/v1/stats/usage/:zone?period=24h&expand=false&aggregate=true&by_tier=false

GETUsage in a zone

See /stats/usage for a detailed explanation of the output and query parameters. If expand=true, stats will be returned for all records in the zone.

Copy CodeGet usage by zone with graphs for last 24 hours

curl -X GET -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' "https://api.nsone.net/v1/stats/usage?expand=true&period=24h"

Request URL:

https://api.nsone.net/v1/stats/usage/:zone[?period=24h][&expand=false][&aggregate=true][&by_tier=false]

Example URL:

https://api.nsone.net/v1/stats/usage/example.com?period=24h

Example Response:

[
  {
    "period": "24h",
    "zone": "example.com",
    "domain": "example.com",
    "rectype": "NS",
    "queries": 1,
    "graph": [
      [
        1376237335,
        0
      ],
      [
        1376239368,
        0
      ],
      ...
    ]
  },
  {
    "period": "24h",
    "zone": "example.com",
    "domain": "example.com",
    "rectype": "NXDOMAIN",
    "queries": 1,
    "graph": [
      [
        1376237335,
        0
      ],
      [
        1376239184,
        0
      ],
      ...
    ]
  },
  ...
]

GET https://api.nsone.net/v1/stats/usage/:zone/:domain/:type?period=24h

GETUsage for a record

See /stats/usage for a detailed explanation of the output and query parameters. The expandby_tier, and aggregate flags are ignored for record usage.

Request URL:

https://api.nsone.net/v1/stats/usage/:zone/:domain/:record[?period=24h]

Example URL:

https://api.nsone.net/v1/stats/usage/example.com/www.example.com/A?period=24h

Example Response:

[
  {
    "queries": 4,
    "zone": "example.com",
    "domain": "www.example.com"
    "rectype": "A",
    "period": "24h",
    "graph": [
      [
        1376279703,
        0
      ],
      [
        1376281516,
        0
      ],
      ...
    ]
  }
]

Pulsar

App

A Pulsar App is a container of pulsar jobs, permissions and config defaults.

GET https://api.nsone.net/v1/pulsar/apps

GET Get list of pulsar apps

Returns all pulsar apps in your account.

GET https://api.nsone.net/v1/pulsar/apps/:appID

GET Get an app's details

Returns a single Pulsar app

Job

GET https://api.nsone.net/v1/pulsar/apps/:appID/jobs

GETList all Jobs for an App

Get pulsar jobs in an app.

GET https://api.nsone.net/v1/pulsar/apps/:appID/jobs/:jobID

GETGet a job's details

Live Job Data

View live, aggregated Pulsar GEO data for a job. Responses are returned where each top-level key is a geo (or geo:region) code.

At present, only geo granularity data is available, GEO and ASN will be added in the future.

GET https://api.nsone.net/v1/pulsar/apps/:appID/jobs/:jobID/live

GETGet Live Aggregated Data

Custom Job Data

Query for historical and "live" data.

GET https://api.nsone.net/v1/pulsar/apps/:appID/jobs/:jobID/data?start=&end=&period=1h&geo=*&asn=&agg=p50

GETGet Aggregated Data