Introduction
This is the NS1 API (v1) documentation which provides you with the
necessary tools for managing zone, records, data sources and feeds,
account settings, and any other aspects of your NS1 account. The NS1 API
is a standard REST API with JSON responses. The HTTP method you use — GET, PUT, POST, or DELETE — determines the type of action to be taken by the API. Generally, in the case of PUT and POST requests, you will send a JSON body in the request with details about 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 the Managed DNS portal (my.nsone.net) or within your Private DNS/DDI portal. You should treat your API Keys as secrets. You should also give them only the minimal access needed for your application.
If you have any questions or experience any issues while using the API, please submit a support ticket or send an email to support@ns1.com.
Client Libraries
Python | Go | PHP | Javascript
Zones & Records
To learn more about managing NS1 zones and records, refer to the NS1 Help Center.
Zones
GET /v1/zones
GET List zones
Returns a list of all active zones and basic zone configuration details for each.
Note about pagination: If you have more than 5,000 zones, the response header will include a link that you can use in a cURL command to get usage statistics for the next 5,000 zones (and so on). This follows the Web Linking standard (RFC 5988).
Copy CodeList active zones
curl -X GET -H 'X-NSONE-Key: $API_KEY' 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": "hostmaster@nsone.net"
},
{
"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": "hostmaster@nsone.net"
}
]
GET /v1/zones/:zone
GET View zone details
Returns a single active zone and its basic configuration details, as well as a list of records in the zone and basic details for each record.
Request URL:
https://api.nsone.net/v1/zones/:zone
Example URL:
https://api.nsone.net/v1/zones/example.com
Example Response:
{
"id": "520422af9f782d37dffb588b",
"hostmaster": "hostmaster@nsone.net",
"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": {}
}
| Parameter | Type | Description | Required? |
| zone | String | The FQDN of the zone | Yes |
PUT /v1/zones/:zone
PUT Create a new zone
You must include a JSON body in the request with basic zone details. The only required element in the body is zone, the zone fully-qualified domain name (FQDN). You can create a standard zone (which has its own configuration and records), a linked zone (pointing to an existing standard zone, reusing its configuration and records), or a secondary zone
(which replicates DNS records from an external primary DNS server). For
non-linked zones, you may specify optional zone configuration by
including ttl (SOA record TTL), refresh, retry, expiry, and nx_ttl values, as in a SOA record. Refer to the Help Center article, "Best practices: TTL configuration" for more information. 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 referencing the target zone (domain name) to which the current zone should link. The linked zone and target zone must be owned by the same account. If the link property is specified, no other zone configuration properties (including refresh, retry, etc.) may be specified as they are inherited from the target zone. After creating a linked zone, it cannot be modified and you cannot add records to it. You can delete the linked zone with no impact to the target zone.
To create a secondary zone, you must include a secondary object in the body of your request including the following fields:
- enabled - [true/false] If true, the zone is configured as a secondary zone
- primary_ip - An IPv4 address (not a hostname) of the zone's primary DNS server. If your primary DNS server is running on a non-standard port, you may also include primary_port.
To enable zone replication by third-party DNS servers, you must include a primary object in the body of your request including the following fields:
- enabled - [true/false] If true,
AXFRqueries (and optionallyNOTIFYmessages) will be enabled for the zone. - secondaries - a list of objects each containing:
- ip - IPv4 address of the secondary node
- port - (Optional) The port on host to send
NOTIFYmessages (default = 53) - notify - [true/false] If true, NS1 will send
NOTIFYmessages to the secondary host upon 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: $API_KEY' -d '{"zone":"{ZONE_NAME}", "nx_ttl":60}' https://api.nsone.net/v1/zones/{ZONE_NAME}
where {ZONE_NAME} is the zone's FQDN
Copy CodeCreate a new secondary DNS zone
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{"zone":"{ZONE_NAME}", "secondary": {"enabled":true, "primary_ip":"{PRIMARY_IP_ADDRESS}"}}' https://api.nsone.net/v1/zones/{ZONE_NAME}
where {ZONE_NAME} is the zone's FQDN and {PRIMARY_IP_ADDRESS} is the IP address of the primary zone.
Copy CodeCreates a secondary zone with TSIG enabled
curl -X PUT -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/zones/{ZONE_NAME} -d "{\"secondary\": {\"enabled\": true,\"tsig\":{\"enabled\": true, \"hash\": \"{HASH_TYPE}\", \"key\":\"{TSIG_KEY}\",\"name\": \"{TSIG_KEY_NAME}\"}, \"primary_ip\": \"{IP_ADDRESS}\", \"primary_port\": 53},\"zone\": \"{ZONE_NAME}\"}"
Copy CodeCreate a new zone allowing AXFR and sending NOTIFY to a secondary zone
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{"zone":"{ZONE_NAME}", "primary": {"enabled":true, "secondaries":[ {"ip":"{SECONDARY_IP}", "port":{SECONDARY_PORT}, "notify":true} ]}}' https://api.nsone.net/v1/zones/{ZONE_NAME}
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": "hostmaster@nsone.net",
"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 /v1/zones/:zone
POST Modify a zone
Modifies the basic details of a DNS zone. You must include a JSON body in the request, in which you may include ttl (SOA record TTL), refresh, retry, expiry, or nx_ttl values, as in a SOA record. You may not change the zone name or other details.
If you are modifying a secondary zone, you can change the primary_ip and primary_port. You can also change enabled in the secondary object to convert a zone between primary and secondary behavior. Note that when converting a secondary to a primary zone, you must create a NS record for the zone with the assigned NSONE nameservers.
You can enable or disable replication from the primary zone, as well as add or remove secondary (replica) 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": "hostmaster@nsone.net",
"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": {}
}
| Parameter | Type | Description | Required? |
| zone | String | >td >Yes |
DELETE /v1/zones/:zone
DELETE Delete a zone
Deletes an existing DNS zone and all of its associated records.
Note: NS1 servers will not respond to queries for the zone or any of the records after it is deleted, and you cannot recover the deleted zone. 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
| Parameter | Type | Description | Required? |
| zone | String | Yes |
PUT /v1/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. Upon
upload, the zone and all records within the zone file are created. Any
"round-robin" records (e.g., multiple A records for the same domain) are treated as answers for a single record in your account. Existing NS records are replaced, as are some details of SOA records.
There are two modes: synchronous (default) and asynchronous.
- In asynchronous mode, you must check back with a
GETrequest 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 is 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 zonefile=@example.com.db -H 'X-NSONE-Key: $API_KEY' https://api.nsone.net/v1/import/zonefile/{ZONE_NAME}
where {ZONE_NAME} is the zone FQDN
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": "hostmaster@nsone.net",
"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"
}
| Parameter | Type | Description | Required? |
| zone | string | zone FQDN | yes |
| async | boolean | (see description above); default is "false" | no |
GET /v1/import/zonefile/:jobid
GET View status of 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": "hostmaster@nsone.net",
"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",
}
| Parameter | Type | Description | Required? |
| jobid | string | value of the id field in the response of an asynchronous zone file import request | yes |
GET /v1/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 zone, record, 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"
}
]
| Parameter | Type | Description | Required |
| q | string | query string | yes |
| max | number | specify the maximum number of results (ex. 10) | no |
| type | string | filter results by type; possible values include 'zone', 'record', 'all' | no |
GET /v1/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"
}
]
POST /v1/zones/:zone
POST Enable DNSSEC for a zone
Enables DNSSEC for a zone. For more information, refer to the following Help Center articles:
Note: Your account must have DNSSEC enabled to use this feature. Submit a support ticket or email support@ns1.com to request DNSSEC for your account.
Request URL:
https://api.nsone.net/v1/zones/:zone
Example URL:
https://api.nsone.net/v1/zones/mydnssec.test
Example Request:
{"dnssec":true}
Example Response:
{
"nx_ttl": 3600,
"retry": 7200,
"dnssec": true,
"zone": "mydnssec.test",
"network_pools": [
"p05"
],
"primary": {
"enabled": false,
"secondaries": []
},
"refresh": 43200,
"expiry": 1209600,
"dns_servers": [
"dns1.p05.nsone.net",
"dns2.p05.nsone.net",
"dns3.p05.nsone.net",
"dns4.p05.nsone.net"
],
"records": [
{
"domain": "mydnssec.test",
"short_answers": [
"dns1.p05.nsone.net",
"dns2.p05.nsone.net",
"dns3.p05.nsone.net",
"dns4.p05.nsone.net"
],
"ttl": 3600,
"tier": 1,
"type": "NS",
"id": "5d4994bec94a900001134b77"
}
],
"meta": {},
"link": null,
"serial": 1565103372,
"ttl": 3600,
"id": "5d4994bec94a900001134b72",
"hostmaster": "hostmaster@nsone.net",
"networks": [
0
],
"pool": "p05"
}
GET /v1/zones/:zone/dnssec
GET View DNSSEC details for a zone
Returns public key information including DNSKEY and DS record information.
Request URL:
https://api.nsone.net/v1/zones/:zone/dnssec
Example URL:
https://api.nsone.net/v1/zones/mydnssec.test/dnssec
Example Response:
{
"keys": {
"dnskey": [
[
"257",
"3",
"13",
"t+4DPP+MFZ0Cr7gasdghasdhasdfhasdfhsdfa5xBXKIsjsj5baV1HzhBNo2F7mbsevsEo0/6UEL8+JBmA=="
],
[
"256",
"3",
"13",
"pxEUulkf8UZtE9fy2+4wJwasdghashasdfhhasdfhadsfahd/QL9AmwFCgyFeC4uRNxoqxK0xOg=="
]
],
"ttl": 3600
},
"delegation": {
"dnskey": [
[
"257",
"3",
"13",
"t+4DPP+MFZ0Cr7gAXiDYv6HTasdghashasdhasdfhahshasdfjsj5baV1HzhBNo2F7mbsevsEo0/6UEL8+JBmA=="
]
],
"ds": [
[
"48553",
"13",
"2",
"02f7cf1f6c24ccasdfasdgasdgasghd91e702287d74453b1aa3f495"
]
],
"ttl": 3600
},
"zone": "mydnssec.test."
}
POST /v1/zones/:zone
POST Enable TSIG on a secondary zone
NS1 offers authentication using TSIG (transaction signature) for instances where NS1 is configured as the secondary DNS provider. Note: Currently, NS1 does not support enabling TSIG authentication on a primary DNS network hosted within NS1.
Copy CodeEnables TSIG on an existing secondary zone
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/zones/{ZONE_NAME} -d "{\"secondary\": {\"enabled\": true,\"tsig\":{\"enabled\": true, \"hash\": \"{HASH_TYPE}\", \"key\":\"$TSIG_KEY\",\"name\": \"{TSIG_KEY_NAME}\"}, \"primary_ip\": \"{IP_ADDRESS}\", \"primary_port\": 53},\"zone\": \"{ZONE_NAME}\"}"
Request URL:
https://api.nsone.net/v1/zones/:zone
Example URL:
https://api.nsone.net/v1/zones/example_secondary_zone
Example Request:
curl -X PUT -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d'{"zone":"newzone.com","secondary":{"enabled":true,"primary_ip":"1.2.3.4","tsig":{"enabled":true,"hash":"hmac-md5","name":"ns1-transfer-key","key":"mwmF7XOq/cB0TSF6kJX+sNW2jkZU/s0V/KPfXtOa6tTk3wU3RuZBFjM9 H0ATD+qbCdC7n64L9QqkAvk3sh89xw=="}}}'
Example Response:
{"dns_servers":["dns1.p06.nsone.net","dns2.p06.nsone.net","dns3.p06.nsone.net","dns4.p06.nsone.net"],"dnssec":false,"network_pools":["p06"],"primary":{"enabled":false,"secondaries":[]},"disabled":false,"meta":{},"ttl":3600,"serial":1578928419,"id":"5e1c8923bbccf90001c16162","retry":7200,"zone":"newzone.com","networks":[0],"hostmaster":"hostmaster@nsone.net","nx_ttl":3600,"expiry":1209600,"records":[],"link":null,"pool":"p06","secondary":{"status":"pending","last_xfr":0,"other_ips":[],"primary_port":53,"enabled":true,"tsig":{"enabled":true,"hash":"hmac-md5","name":"tsigname","key":"+Cdjlkef9ZTSeixERZ433Q=="},"error":null,"other_ports":[],"primary_ip":"1.2.3.4","expired":false},"refresh":43200,"primary_master":"dns1.p06.nsone.net"}
GET /v1/search/zone/:zoneID
GET Search records by zone ID
Search this zone by q string (a record name) or by a feature such as geo=1 (for records with geo targeting). 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 zone, record, 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"
}
]
| Parameter | Type | Description | Required |
| q | string | query string | yes |
| max | number | specify the maximum number of results (ex. 10) | no |
| type | string | filter results by type; possible values include 'zone', 'record', 'all' | no |
| geo | number | filter by records with geo-targeting (ex. geo=1) | no |
Records
GET /v1/zones/:zone/:domain/:type
GETView record configuration details
Returns full configuration for a DNS record including basic config, answers, regions, 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 zone, domain, 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
}
| Parameter | Type | Description | Required? |
| zone | String | The zone name | Yes |
| domain | String | The domain name | Yes |
| type | String | The record type | Yes |
PUT /v1/zones/:zone/:domain/:type
PUTCreate a 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: A, AAAA, ALIAS, AFSDB, CERT, CNAME, DNAME, HINFO, MX, NAPTR, NS, PTR, RP, SPF, SRV, TXT, URLFWD. 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 answers or meta) should be specified.
Copy CodeCreate a simple A record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -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: $API_KEY" -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: $API_KEY" -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: $API_KEY" -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.
Copy CodeCreate an A record with the DHCP filter
curl -L -X PUT https://api.mycompany.net/v1/zones/docker.local/*.docker.local/A -H "X-NSONE-Key: $APIKEY" -d '{ "zone": "docker.local", "domain": "*.docker.local", "type": "A", "answers": [ { "answer": [ "127.0.0.1" ] } ], "filters": [ { "filter": "dhcp", "config": { "scope_group_id": 1 } } ] }'
For the purposes of implementing first-party DDNS, this creates a wildcard A record in the forward zone. In this example, the forward zone is docker.local.
Copy CodeCreate a PTR record with the DHCP filter
curl -L -X PUT https://api.mycompany.net/v1/zones/11.18.172.in-addr.arpa/*.11.18.172.in-addr.arpa/PTR -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "11.18.172.in-addr.arpa", "domain": "*.11.18.172.in-addr.arpa", "type": "PTR", "answers": [ { "answer": [ "*.hosts.docker.local" ] } ], "filters": [ { "filter": "dhcp", "config": { "scope_group_id": 1 } } ] }'
For the purposes of implementing first-party DDNS, this creates a
wildcard PTR record in the reverse zone. In this example, the reverse
zone is 11.18.172.in-addr.arpa.
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
}
| Parameter | Type | Description | Required? |
| zone | String | The zone name | Yes |
| domain | String | The domain name | Yes |
| type | String | The record type | Yes |
POST /v1/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
}
| Parameter | Type | Description | Required? |
| zone | String | The zone name | Yes |
| domain | String | The domain name | Yes |
| type | String | The record type | Yes |
DELETE /v1/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
| Parameter | Type | Description | Required? |
| zone | String | The zone name | Yes |
| domain | String | The domain name | Yes |
| type | String | The record type | Yes |
GET /v1/metatypes
GETView available metadata
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 /v1/filtertypes
GETView 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"
},
...
}
GET /v1/metatypes/geo
GETView available geographic metadata
Returns a list of available geographic metadata used by the “Geo-target Country” and “Geo-fence Country” filters . Note that the response will be long. The example response below is truncated for readability.
Request URL:
https://api.nsone.net/v1/metatypes/geo
Example Response:
{
"subdivisions": {
...
"CA": [
"MB",
"NB",
"NL",
...
"YT",
"ON",
"BC"
],
"RU": [
"KOS",
"SE",
"IN",
...
"LEN",
"NGR",
"SA"
],
...
"US": [
"NM",
"ND",
"LA",
...
"GU",
"NY",
"NV"
],
...
},
"countries": [
"AD",
"AE",
"AF",
...
"ZA",
"ZM",
"ZW"
]
}
Data Sources & Feeds
Data Sources
GET /v1/data/sourcetypes
GET View 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. Often, 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 View 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 View 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"
}
| Parameter | Type | Description | Required? |
| sourceid | String | Yes |
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"
}
| Parameter | Type | Description | Required? |
| sourceid | String | Yes |
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
| Parameter | Type | Description | Required? |
| sourceid | String | Yes |
Data Feeds
GET https://api.nsone.net/v1/data/feeds/:sourceid
GETView 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"
}
]
| Parameter | Type | Description | Required? |
| sourceid | String | Yes |
GET https://api.nsone.net/v1/data/feeds/:sourceid/:feedid
GETView data feed details
Returns the details of a single data feed, including config details and any record, region, 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"
}
| Parameter | Type | Description | Required? |
| sourceid | String | Yes | |
| feedid | String | Yes |
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"
}
| Parameter | Type | Description | Required? |
| sourceid | String | Yes | |
| feedid | String | Yes |
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
| Parameter | Type | Description | Required? |
| sourceid | String | Yes | |
| feedid | String | Yes |
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 GET, PUT, 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
}
}
| Parameter | Type | Description | Required? |
| sourceid | String | Yes |
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 up, down, 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 View monitoring job 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 up, down, 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
}
| Parameter | Type | Description | Required? |
| jobid | String | Yes |
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"
}
| Parameter | Type | Description | Required? |
| jobid | String | Yes |
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
| Parameter | Type | Description | Required? |
| jobid | String | Yes |
GET https://api.nsone.net/v1/monitoring/history/jobid?start=&end=&period=24h&limit=®ion=global&exact=
GET View 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 1h, 24h, 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.
| Parameter | Type | Description | Required? |
| jobid | String | Yes | |
| start | Number | Absolute start time in UNIX timestamp | No |
| end | Number | Absolute end time in UNIX timestamp (defaults to current time) | No |
| period | String | Possible values: '1h', '24h', '30d' | No |
| limit | Number | Maximum number of results | No |
| region | String | Region Code, Example: 'global' | No |
| exact | Boolean | No |
GET https://api.nsone.net/v1/monitoring/metric/jobid?region=global&metric=rtt&period=30d
GET View 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/regions. You 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 1h, 24h, 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 jobid, region, 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][®ion=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
],
...
]
}
}
}
]
| Parameter | Type | Description | Required? |
| jobid | String | Yes | |
| region | String | Region code, Example: 'global' | No |
| metric | String | Example: 'rtt' | No |
| period | String | Possible Values: '1h', '24h', '30d' | No |
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"
]
}
]
GET https://api.nsone.net/v1/monitoring/history/jobid?start=&end=&period=24h&limit=®ion=global&exact=
GET View 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 1h, 24h, 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.
| Parameter | Type | Notes/Description | Required? |
| jobid | string | Yes | |
| start | number | absolute start time in UNIX timestamp | No |
| end | number | absolute end time in UNIX timestamp (defaults to current time) | No |
| period | string | possible values: '1h', '24h', '30d' | No |
| limit | number | maximum number of results | No |
| region | string | region code (ex. 'global') | No |
| exact | boolean | No |
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+notify@gmail.com"
}
},
{
"type": "datafeed",
"config": {
"sourceid": "5872814cc08b23c697e88c054d032780"
}
},
{
"type": "user",
"config": {
"user": "myuser"
}
}
]
},
...
]
GET https://api.nsone.net/v1/lists/:listid
GETView notification list details
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+notify@gmail.com"
}
},
{
"type": "datafeed",
"config": {
"sourceid": "5872814cc08b23c697e88c054d032780"
}
},
{
"type": "user",
"config": {
"user": "myuser"
}
}
]
}
| Parameter | Type | Description | Required? |
| listid | String | Notification List ID | Yes |
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":"mystaff@mycompany.com"}}, {"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 (mystaff@mycompany.com) 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+notify@gmail.com"
},
"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+notify@gmail.com"
},
"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+notify@gmail.com"
},
"type": "email"
},
{
"config": {
"user": "myuser"
},
"type": "user"
},
{
"config": {
"sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
},
"type": "datafeed"
},
{
"config": {
"email": "another.email@gmail.com"
},
"type": "email"
}
]
}
Example Response:
{
"id": "52b49af12f21574b0e0bffe8",
"name": "My Notification List",
"notify_list": [
{
"config": {
"email": "email+notify@gmail.com"
},
"type": "email"
},
{
"config": {
"user": "myuser"
},
"type": "user"
},
{
"config": {
"sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
},
"type": "datafeed"
},
{
"config": {
"email": "another.email@gmail.com"
},
"type": "email"
}
]
}
| Parameter | Type | Description | Required? |
| listid | String | Notification List ID | Yes |
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
| Parameter | Type | Description | Required? |
| listid | String | Notification List ID | Yes |
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 View 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": "support@ns1.com",
"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": "support@nsone.net",
"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 View overage alert 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
GETView 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": "support@nsone.net",
"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": "newuser@example.com",
"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
GETView user 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": "newuser@example.com",
"last_access": null,
"notify": {
"billing": true
},
"name": "New User",
"username": "newuser",
"ip_whitelist_strict": false,
"ip_whitelist": []
}
| Parameter | Type | Description | Required? |
| username | String | Yes |
PUT https://api.nsone.net/v1/account/users/:username
PUTAdd 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": "newuser@example.com",
"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": {
"manage_zones": false,
"records_deny": [
{
"domain": "prod.example.com",
"include_subdomains": true,
"zone": "example.com"
},
{
"include_subdomains": true,
"domain": "test.example.com",
"type": "A",
"zone": "example.com"
}
],
"zones_deny": [],
"view_zones": true,
"records_allow": [],
"zones_allow": [],
"zones_allow_by_default": true
},
"monitoring": {
"manage_lists": false,
"manage_jobs": false,
"view_jobs": false
}
}
}
Example Response:
{
"permissions": {
"dns": {
"manage_zones": false,
"records_deny": [
{
"domain": "prod.example.com",
"include_subdomains": true,
"zone": "example.com"
},
{
"include_subdomains": true,
"domain": "test.example.com",
"type": "A",
"zone": "example.com"
}
],
"zones_deny": [],
"view_zones": true,
"records_allow": [],
"zones_allow": [],
"zones_allow_by_default": true
},
"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": "newuser@example.com",
"last_access": null,
"notify": {
"billing": true
},
"name": "New User",
"username": "newuser",
"ip_whitelist_strict": false,
"ip_whitelist": []
}
| Parameter | Type | Description | Required? |
| username | String | Yes |
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": "newuser@example.com",
"last_access": null,
"notify": {
"billing": true
},
"name": "Jane Smith",
"username": "newuser",
"ip_whitelist_strict": false,
"ip_whitelist": []
}
| Parameter | Type | Description | Required? |
| username | String | Yes |
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
| Parameter | Type | Description | Required? |
| username | String | Yes |
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":"newuser@example.com"}' https://api.nsone.net/v1/account/users/newuser
An invitation email will be sent to newuser@example.com 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
| Parameter | Type | Description | Required? |
| username | String | Yes |
API Key
GET https://api.nsone.net/v1/account/apikeys
GETView 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
GETView API key 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": []
}
| Parameter | Type | Description | Required? |
| keyid | String | Yes |
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": []
}
| Parameter | Type | Description | Required? |
| keyid | String | Yes |
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
| Parameter | Type | Description | Required? |
| keyid | String | Yes |
Team
GET https://api.nsone.net/v1/account/teams
GETView all teams
Returns a list of all teams associated with 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
GETView team 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": []
}
| Parameter | Type | Description | Required? |
| teamid | String | Yes |
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": []
}
| Parameter | Type | Description | Required? |
| teamid | String | Yes |
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
| Parameter | Type | Description | Required? |
| teamid | String | Yes |
IP Whitelist
GET https://api.nsone.net/v1/account/whitelist
GETView 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
GETView IP whitelist record details
Get a 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"]
}
| Parameter | Type | Description | Required? |
| id | String | Yes |
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"]
}
| Parameter | Type | Description | Required? |
| id | String | Yes |
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
| Parameter | Type | Description | Required? |
| id | String | Yes |
Plan and Billing
GET https://api.nsone.net/v1/account/plantypes
GETView 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 period.
Note: details are returned regardless of your current plan, but at this time only users on the startup, starter, or basic plan types may change their subscription automatically. Users currently on other plans should contact support@ns1.com.
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
GETView 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 startup, starter, 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 monthly, quarterly, semiannual, 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 professional, enterprise, enterprise 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
| Parameter | Type | Description | Required? |
| invoiceid | String | Example: '727' | Yes |
| authtoken | String | Example: d4a2080c926b85c9936908852454cb181249622a | No |
GET https://api.nsone.net/v1/account/billataglance
GETView bill at a glance
Returns current 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
GETView 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
GETView payment method 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
}
| Parameter | Type | Description | Required? |
| id | String | Payment method id | Yes |
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
| Parameter | Type | Description | Required? |
| id | String | Payment method id | Yes |
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
| Parameter | Type | Description | Required? |
| id | String | Payment method id | Yes |
Activity Log
GET https://api.nsone.net/v1/account/activity?limit=&start=&end=&resource_type=&user=&resource_id=
GETView 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": "hostmaster@nsone.net",
"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": "olduser@example.com",
"last_access": null,
"notify": {
"billing": true
},
"name": "Old User",
"username": "olduser"
},
"user_name": "My User",
"id": "52275fba830f787e2ff88d42"
},
...
]
| Parameter | Type | Description | Required? |
| limit | Number | Maximum number of results | No |
| start | Number | Absolute start time in UNIX timestamp | No |
| end | Number | Absolute end time in UNIX timestamp (defaults to current time) | No |
| resource_type | String | No | |
| user | String | No | |
| resource_id | String | No |
Statistics
QPS
GET https://api.nsone.net/v1/stats/qps
GET Account-wide DNS queries per second
Returns current queries per second (QPS) for the account. Queries per second (QPS) are reported by the NS1 API for Managed DNS networks using the same method for calculating account, zone, and record-level stats: Once per minute on the minute, a new QPS value is calculated using the query count in a two minute period ending five minutes ago. This query count is divided by 120 seconds to return an average QPS for that time period. For example, an API call at 10:07:37 UTC will receive a QPS value using the query count between 10:00:00 and 10:02:00.
Request URL:
https://api.nsone.net/v1/stats/qps
Example Response:
{
"qps": 8.2
}
GET https://api.nsone.net/v1/stats/qps/:zone
GET Zone-level queries per second
Returns current queries per second (QPS) for a specific zone. Queries per second (QPS) are reported by the NS1 API for Managed DNS networks using the same method for calculating account, zone, and record-level stats: Once a minute on the minute, a new QPS value is calculated using the query count in a two minute period ending five minutes ago. This query count is divided by 120 seconds to return an average QPS for that time period. For example, an API call at 10:07:37 UTC will receive a QPS value using the query count between 10:00:00 and 10:02:00.
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
}
| Parameter | Type | Description | Required? |
| zone | String | Yes |
GET https://api.nsone.net/v1/stats/qps/zone/domain/type
GET Record-level queries per second
Returns current queries per second (QPS) for a specific record. Queries per second (QPS) are reported by the NS1 API for Managed DNS networks using the same method for calculating account, zone, and record-level stats: Once a minute on the minute, a new QPS value is calculated using the query count in a two minute period ending five minutes ago. This query count is divided by 120 seconds to return an average QPS for that time period. For example, an API call at 10:07:37 UTC will receive a QPS value using the query count between 10:00:00 and 10:02:00.
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
}
| Parameter | Type | Description | Required? |
| zone | String | Yes |
Usage
GET https://api.nsone.net/v1/stats/usage
GETView account-wide usage statistics
Returns statistics and graphs for the entire account over a given period. Stats are returned as a list of "objects" containing various stats fields that correspond to the given entity.
When querying usage stats, note the following:
- If none of the fields are present, the response includes aggregate stats for the entire account.
- If only the zone field is present, the response includes aggregate stats for the specified zone.
- If domain, rectype, and zone fields are present in the object, the response includes stats for the specified record.
Querying the 1-hr usage statistics endpoint returns three data points
(including a partial one) containing the number of total queries. For example, if you query the usage stats for the “testdomain.com” endpoint at 5:10 pm (ex.
['https://my.nsone.net/v1/stats/usage/testdomain.com?period=1h’]), you
may see the following response:
[{"graph":[[1584993600,4514354],[1584995400,4193351],[1584997200,1683636]],"records":3994,"period":"1h","zone":"testdomain.com","queries":10391341}]
The graph is an array of UNIX timestamps and counts:
- 1584993600 = 4:00 pm (DST) , Total Queries 4514354
- 1584995400 = 4:30 pm (DST) , Total Queries 4193351
- 1584997200 = 5:00pm (DST) , Total Queries 1683636 (a partially-filled bucket)
To calculate the total number of queries from 4 pm to 5 pm, add the first two data points together (totaling 8,707,705 queries from 4 - 5 pm). Ignore the third (partial) bucket as this is reflects only the number of queries from 5:00 pm to 5:10 pm.
Note: NS1 recommends that you only query 1hr stats at 30 minute intervals.
Note: The option to view usage statistics by billing tier (i.e. by_tier=true/false) is no longer supported.
Copy CodeGet account-wide zone usage for last 24 hours
curl -X GET -H 'X-NSONE-Key: $API_KEY' "https://api.nsone.net/v1/stats/usage?period=24h"
Request URL:
https://api.nsone.net/v1/stats/usage?period=24h&expand=true&networks=*
Example URL:
https://api.nsone.net/v1/stats/usage?period=24h&expand=true&networks=*
| Parameter | Type | Description | Required? |
| period | enum(string) | Relative time. Possible values: ‘1h’, ‘24h’, ‘30d’ (default: ‘24h’) | no |
| expand | boolean | Default value is “true.” If set to true, the response includes aggregated statistics across all zones. Note about pagination: If you have more than 1,000 zones expanded, the response header will include a link that you can use in a cURL command to get usage statistics for the next 1,000 zones (and so on). | no |
| networks | string | Used to specify the DNS network. The networks parameter only applies when doing zone expansion via expand = true. Possible values include ‘*’ to return usage stats for all networks combined, or ‘0 , 8’ use a comma to add multiple networks and receive the sum usage across networks specified. (Default is 0. This is NS1’s Managed DNS network) | no |
GET https://api.nsone.net/v1/stats/usage/:zone
GETView zone-level usage statistics
Please refer to /stats/usage for a detailed explanation of the output and query parameters. Note that by_tier (true/false) parameters are no longer supported.
When querying usage stats, note the following:
- If none of the fields are present, the response includes aggregate stats for the entire account.
- If only the zone field is present, the response includes aggregate stats for the specified zone.
- If domain, rectype, and zone fields are present in the object, the response includes stats for the specified record.
Copy CodeGet usage by zone with graphs for last 24 hours
curl -X GET -H 'X-NSONE-Key: $API_KEY' "https://api.nsone.net/v1/stats/usage/:zone?period=24h&networks=*"
Request URL:
https://api.nsone.net/v1/stats/usage/:zone?period=24h&networks=*
Parameter | Type | Description | Required? |
zone | string | Name of the zone | yes |
period | enum(string) | Relative time. Possible values: '1h', '24h', '30d' (Default: '24h') | no |
networks | string | Used to specify the DNS network. The networks parameter only applies when doing zone expansion via expand = true. Possible values: ‘*’ to return usage stats for all networks combined, or use a comma to add multiple networks (‘0 , 8’) and receive the sum usage across networks specified. (Default: 0 is NS1’s Managed DNS network) | no |
GET https://api.nsone.net/v1/stats/usage/:zone/:domain/:type[?period=24h]
GETView record-level usage statistics
Please refer to /stats/usage for a detailed explanation of the output and query parameters. Note that the parameters expand (true/false) and by_tier (true/false) parameters are no longer supported.
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
],
...
]
}
]
Parameter | Type | Description | Required? |
zone | String | The zone name | Yes |
domain | String | The domain name | Yes |
type | String | The record type | Yes |
period | Enum(string) | Relative time, possible values: '1h', '24h', '30d' (Default: '24h') | No |
Pulsar
App
A Pulsar App is a container of pulsar jobs, permissions and config defaults.
GET /v1/pulsar/apps
GET List Pulsar apps
Returns all Pulsar applications in your account.
GET /v1/pulsar/apps/:appID
GET View application details
Returns details for a single Pulsar application.
PUT /v1/pulsar/apps
PUT Create a Pulsar app
A Pulsar app is a collection of Pulsar jobs. Pulsar references the app ID to view all available jobs before making routing decisions. Use this command to create a new Pulsar application—auto-generating an app ID.
Note: Record the appID generated in the response. You will need this when creating Pulsar jobs associated with this app.
Copy CodeCreate an active Pulsar application
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{"name": "{APP_NAME}", "active": true}' https://api.nsone.net/v1/pulsar/apps
Example Response:
{
"customer": 0,
"appid": "x4f12h0",
"name": "ACME Pulsar Tag",
"active": true,
"token": 0,
"browser_wait_millis": 0,
"jobs_per_transaction": 0,
"default_config": {
"http": true,
"https": true,
"request_timeout_millis": 0,
"job_timeout_millis": 0,
"use_xhr": true,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
},
"community": true
}
| Parameter | Description |
|---|---|
| name | name of the Pulsar application (ex. ACME Pulsar tag) |
Modify Pulsar configuration
The Pulsar configuration for an answer is just a part of that answer’s metadata, and thus can be configured like any other metadata through the `/zones/:zone` endpoint (see https://ns1.com/api#zones-records):
Copy CodeZone details
curl -X GET -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' https://api.nsone.net/v1/zones/zone.test/domain.zone.test/A
Parameter | Type | Description | Example | Required |
job_id | String | The string ID of the Pulsar job to be associated with this record. | ‘abc123’ | Yes |
granularities | List of strings | Specifies whether to use “geo”, “geo_asn” or both. We recommend using both “geo” and “geo_asn”. | Only 4 possible values: [‘geo’], [‘geo_asn’], or [‘geo’, ‘geo_asn’] | Yes |
bias | String | The bias to be associated with this answer - when Pulsar is comparing different latencies, it will apply this modifier to this answer to prioritize or de-prioritize it. Must take the form of a mathematical operator (one of ‘+’, ‘-’, or ‘*’) followed by a number which must be a positive float. The ‘+’ and ‘-’ operators add or subtract the specified number of milliseconds to the answer’s latency, and the ‘*’ operator scales the answer’s latency by the specified amount. | ‘+10’, ‘-55’, ‘*0.5’, ‘*2’ | No |
a5m_cutoff | Float | The 5 minute availability cutoff to be associated with this answer. If availability of the Pulsar job associated with this answer over the last 5 minutes is lower than this value, this answer will be excluded from consideration. Must be a float between 0 and 1 (inclusive). | 0.9 | No |
Example Response:
{
"domain": "domain.zone.test",
"zone": "zone.test",
"use_client_subnet": true,
"answers": [
{
"answer": [
"1.2.3.4"
],
"meta": {
"pulsar": [
{
"a5m_cutoff": 0.95,
"bias": "+20",
"job_id": "abc123",
"granularities": [
"geo"
]
}
]
},
"id": "5b06ff0116b23f0001957808"
}
],
"id": "5adfa1d0c24d2400012e2151",
"regions": {},
"meta": {},
"link": null,
"filters": [],
"ttl": 3600,
"tier": 1,
"type": "A",
"networks": [
0
]
}
The Pulsar configuration data is nested within the “meta” field under the “pulsar” key, and is structured as a dictionary wrapped within a list. (This is important - if you try to send just a dictionary without wrapping it in a list it will be rejected. This is required because having a metadata value that is a dictionary gets parsed as a feed pointer, which is a completely separate object.) The different values inside the dictionary can all be modified with a POST request just like any other metadata, or any other zone/record data. (See https://ns1.com/api#modify-a-zone)
"pulsar": [
{
"a5m_cutoff": 0.95,
"bias": "+20",
"job_id": "abc123",
"granularities": [
"geo"
]
}
]
Parameter | Type | Description | Example | Required |
job_id | String | The string ID of the Pulsar job to be associated with this record. | ‘abc123’ | Yes |
granularities | List of strings | Specifies whether to use “geo”, “geo_asn” or both. We recommend using both “geo” and “geo_asn”. | Only 4 possible values: [‘geo’], [‘geo_asn’], or [‘geo’, ‘geo_asn’] | Yes |
bias | String | The bias to be associated with this answer - when Pulsar is comparing different latencies, it will apply this modifier to this answer to prioritize or de-prioritize it. Must take the form of a mathematical operator (one of ‘+’, ‘-’, or ‘*’) followed by a number which must be a positive float. The ‘+’ and ‘-’ operators add or subtract the specified number of milliseconds to the answer’s latency, and the ‘*’ operator scales the answer’s latency by the specified amount. | ‘+10’, ‘-55’, ‘*0.5’, ‘*2’ | No |
a5m_cutoff | Float | The 5 minute availability cutoff to be associated with this answer. If availability of the Pulsar job associated with this answer over the last 5 minutes is lower than this value, this answer will be excluded from consideration. Must be a float between 0 and 1 (inclusive). | 0.9 | No |
Job
A pulsar Job measures a specific metric (e.g. latency) from a particular resource (e.g. a CDN or cloud endpoint).
GET /v1/pulsar/apps/:appID/jobs
GETList all Pulsar jobs (within an app)
Returns a list of all Pulsar jobs in an app.
GET /v1/pulsar/apps/:appID/jobs/:jobID
GETView job details
Returns details for a single Pulsar job.
PUT /v1/pulsar/apps/{appId}/jobs
PUTCreate a Pulsar job
A job is an object corresponding to a resource (CDN, data center, cloud, etc.). The resource hosts an asset used to measure availability and latency. The jobID is applied to an endpoint via the answer metadata. Use this command to create a Puslar job within your app—auto-generating a jobID.
Note: Record the jobID value (ex. d45ma0) in the response. You will need to apply the jobID to the answer metadata.
Copy CodeCreate a Pulsar job associated with a Pulsar application
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{"name": "{JOB_NAME}", "typeid": "latency", "active": true}' https://api.nsone.net/v1/pulsar/apps/{appId}/jobs
Example Response:
{
"customer": 0,
"appid": "x4f12h0",
"jobid": "d45ma0",
"name": "CDN A",
"typeid": "latency",
"active": true,
"community": true,
"shared": true,
"config": {
"host": "string",
"url_path": "string",
"http": true,
"https": true,
"request_timeout_millis": 0,
"job_timeout_millis": 0,
"use_xhr": true,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
}
}
| Parameter | Description |
|---|---|
| name | Name of the Pulsar job. Typically, this is the name of the CDN or endpoint. |
| typeid | Type of Pulsar job — either latency or custom. |
| {appID} | Unique application ID with which this job is associated. The appID is generated in the response when creating a Pulsar application. |
Performance Data
The various performance data endpoints use a common set of parameters to filter & group query results. These parameters can be directly specified to tightly filter results (e.x., setting “geo=US” will restrict the query to only return results from the US). Alternatively, some parameters can be set to a wildcard to group answers based on that parameter (e.x., setting “geo=*” will return a separate set of results for every geo value that exists).
Parameter | Type | Description | Example | Wildcard enabled |
start | Number | Absolute start time in UNIX timestamp. Any data from before this time will be excluded. Defaults to 1 hour before current time | 1527163200 (corresponds to 5/24/2018 12:00:00 GMT) | No |
end | Number | Absolute end time in UNIX timestamp. Any data from after this time will be excluded. Defaults to current time. | 1527163200 (corresponds to 5/24/2018 12:00:00 GMT) | No |
period | String | Can be used instead of start & end time. If set, will set end time to current time and start time to whatever time is specified by this period. If start time is set, period is ignored | ‘30m’, ‘1h’, ‘30d’ | No |
geo | String | Geographic region. Will filter data to only include results from the specified region. Must be either a 2 letter ISO country code, or US states can also be specified with the format ‘US_NY’ | ‘US’, ‘FR’, ‘GR’, ‘JP’, ‘US_NY’ | Yes |
asn | Number | Specifies an Autonomous System Number to filter for | 1234 | Yes |
agg | String | Specifies a method to use to aggregate data. When there are multiple categories of data being grouped into one (e.x., you query for all geo rather than individual geo regions), this determines how the different data series are combined. (‘p50’ means “estimated 50th percentile”, ‘p75’ is estimated 75th percentile, etc) | ‘avg’, ‘max’, ‘min’, ‘p50’, ‘p75’, ‘p90’, ‘p95’, ‘p99’, ‘p999’ | No |
GET /v1/pulsar/apps/:appID/jobs/:jobID/data
GETView aggregated performance data
Request URL:
https://api.nsone.net/v1/pulsar/apps/:appID/jobs/:jobID/data?start=&end=&period=1h&geo=*&asn=&agg=p50
Request URL:
https://api.nsone.net/v1/pulsar/apps/testapp/jobs/testjob123/data?start=1526385600&end=1526558400&geo=US-NY&asn=1234&agg=p50
| Parameter | Type | Description | Required? |
| appID | String | ID of the Pulsar app | Yes |
| jobID | String | ID of the Pulsar job | Yes |
| start | Number | Absolute start time in UNIX timestamp | No |
| end | Number | Absolute start time in UNIX timestamp (defaults to current time) | No |
| period | Number | Relative time (default 1h), If both period and start/end time are given period takes precedence. Example: 1h | No |
| geo | String | Geocode to filter on (default '*'), Example: '*' | No |
| asn | String | ASN to filter on | No |
| agg | String | Aggregation type (default 'p50'), Possible values: 'avg', 'max', 'min', 'p50', 'p75', 'p90', 'p95', 'p99', 'p999' | No |
Availability
Allowed parameters: start, end, period, geo, asn
GET /v1/pulsar/apps/:appID/jobs/:jobID/availability
GETView availability data
Returns availability score per resource over time.
Request URL:
https://api.nsone.net/v1/pulsar/apps/testapp/jobs/testjob123/availability?start=&end=&geo=US&asn=1234
Example URL:
https://api.nsone.net/v1/pulsar/apps/testapp/jobs/testjob123/availability?period=1h&geo=US&asn=1234
Decisions
Allowed parameters: start, end, period, geo, asn
GET https://api.nsone.net/v1/pulsar/query/decision/customer
GETView decisions for account
Returns total count of Pulsar decisions per resource.
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/customer[?start=1523000000][&end=1523500000][&geo=US][&asn=1234]
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/customer[?period=1h][&geo=US][&asn=1234]
GET https://api.nsone.net/v1/pulsar/query/decision/customer/undetermined
GETView insufficient decision data for account
Returns total count of insufficient data where Pulsar could not make a decision.
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/customer/undetermined[?start=1523000000][&end=1523500000][&geo=US][&asn=1234]
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/customer/undetermined/[?period=1h][&geo=US][&asn=1234]
GET https://api.nsone.net/v1/pulsar/query/decision/record/:domain/:rectype
GETView decisions for record
Returns count of Pulsar decisions per resource for a specific record.
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/record/www.example.com/A[?start=1523000000][&end=1523500000][&geo=US][&asn=1234]
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/record/www.example.com/A[?period=1h][&geo=US][&asn=1234]
GET https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/:domain/:rectype
GETView insufficient decision data for record
Returns count of insufficient data where Pulsar could not make a decision for a specific record.
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/www.example.com/A[?start=1523000000][&end=1523500000][&geo=US][&asn=1234]
Request URL:
https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/www.example.com/A[?period=1h][&geo=US][&asn=1234]
Filters
Cost
The cost filter examines the “cost” metadata field, and sorts all the answers in the record based on that value from lowest to highest. By default it does not eliminate any answers.
Input Metadata | Type |
cost | Positive float |
Config Option | Type | Required? | Default | Explanation |
eliminate | boolean | no | false | If enabled, rather than sorting and returning all answers, the cost filter will find the answer with the lowest cost value and return only that, eliminating all others. (If there are multiple answers tied for lowest cost, it will return all of them.) |
Note: any answers that do not have any associated cost metadata will always be considered last. The filter will always put them at the end of the sort order, and they will always be eliminated by the “eliminate” option (unless there are no answers with cost metadata, in which case the filter will do nothing)
Geofence Country
The geofence_country filter eliminates answers which are not in the same country (and, if applicable, US state or Canadian province) as the requester.
Input Metadata | Type |
country | 2 character ISO code (“US”, “GB”, “JP”, etc), or list of several countries |
us_state | 2 character state code (“NY”, “CA”, “IL”, “CT”, etc), or list of several states |
ca_province | 2 character province code (“QC”, “ON”, “MB”, etc), or list of several provinces |
| subdivision | ISO-3166-2 code for a country and subdivisions |
Config Option | Type | Required? | Default | Explanation |
remove_no_location | boolean | no | true | If any answers have a location matching the requester, then eliminate all answers without any location. If set to false, then answers without location are kept instead. |
Example Request:
GET https://api.nsone.net/v1/zones/:zone/:domain/:type
Example Response:
{
"domain": "legacy.geo1.testing",
"use_client_subnet": true,
"answers": [
{
"answer": [
"3.3.3.3"
],
"meta": {
"ca_province": [
"ON",
"QC"
],
"us_state": [
"NY",
"NJ",
"PA",
"CT"
]
},
"id": "5e81fd228fdbc30af7d9a332"
},
{
"answer": [
"4.4.4.4"
],
"meta": {
"ca_province": [
"AB",
"BC"
],
"us_state": [
"CA",
"OR",
"WA"
]
},
"id": "5e81fd228fdbc30af7d9a333"
}
],
"meta": {},
"link": null,
"filters": [
{
"filter": "geofence_country",
"config": {
"remove_no_location": "1"
}
}
],
"ttl": 3600,
"tier": 3,
"override_ttl": false,
"zone": "geo1.testing",
"id": "5e81fd228fdbc30af7d9a334",
"networks": [
0
],
"regions": {},
"type": "A"
}
Example Response:
{
"domain": "new.geo1.testing",
"use_client_subnet": true,
"answers": [
{
"answer": [
"1.1.1.1"
],
"meta": {
"subdivisions": {
"RU": [
"MOS"
]
}
},
"id": "5e81fd108fdbc30d0806422e"
},
{
"answer": [
"2.2.2.2"
],
"meta": {
"subdivisions": {
"US": [
"NY"
]
}
},
"id": "5e81fd108fdbc30d0806422f"
}
],
"meta": {},
"link": null,
"filters": [
{
"filter": "geofence_country",
"config": {
"remove_no_location": "1"
}
}
],
"ttl": 3600,
"tier": 3,
"override_ttl": false,
"zone": "geo1.testing",
"id": "5e81fd108fdbc30d08064230",
"networks": [
0
],
"regions": {},
"type": "A"
}
Geofence Regional
The geofence_regional filter eliminates answers which are not in the same geographical region (e.g., Europe, Asiapac, or US-East) as the requester.
Input Metadata | Type |
georegion | One of “US-EAST”, “US-WEST”, “US-CENTRAL”, “EUROPE”, “SOUTH-AMERICA”, “AFRICA”, “ASIAPAC”; or a list of several of these |
Config Option | Type | Required? | Default | Explanation |
remove_no_georegion | boolean | no | true | If any answers have a georegion matching the requester, then eliminate all answers without any georegion. If set to false, then answers without georegion are kept instead. |
Geotarget Country
The geotarget_country filter sorts answers by distance to the country (and, if applicable, US state or Canadian province) of the requester.
Input Metadata | Type |
country | 2 character ISO code (“US”, “GB”, “JP”, etc), or list of several countries |
us_state | 2 character state code (“NY”, “CA”, “IL”, “CT”, etc), or list of several states |
ca_province | 2 character province code (“QC”, “ON”, “MB”, etc), or list of several provinces |
| subdivision | ISO-3166-2 code for a country and subdivisions |
Example Request:
GET https://api.nsone.net/v1/zones/:zone/:domain/:type
Example Response:
{
"domain": "legacy.geo1.testing",
"use_client_subnet": true,
"answers": [
{
"answer": [
"3.3.3.3"
],
"meta": {
"ca_province": [
"ON",
"QC"
],
"us_state": [
"NY",
"NJ",
"PA",
"CT"
]
},
"id": "5e81fd228fdbc30af7d9a332"
},
{
"answer": [
"4.4.4.4"
],
"meta": {
"ca_province": [
"AB",
"BC"
],
"us_state": [
"CA",
"OR",
"WA"
]
},
"id": "5e81fd228fdbc30af7d9a333"
}
],
"meta": {},
"link": null,
"filters": [
{
"filter": "geotarget_country",
"config": {
}
}
],
"ttl": 3600,
"tier": 3,
"override_ttl": false,
"zone": "geo1.testing",
"id": "5e81fd228fdbc30af7d9a334",
"networks": [
0
],
"regions": {},
"type": "A"
}
Example Response:
{
"domain": "new.geo1.testing",
"use_client_subnet": true,
"answers": [
{
"answer": [
"1.1.1.1"
],
"meta": {
"subdivisions": {
"RU": [
"MOS"
]
}
},
"id": "5e81fd108fdbc30d0806422e"
},
{
"answer": [
"2.2.2.2"
],
"meta": {
"subdivisions": {
"US": [
"NY"
]
}
},
"id": "5e81fd108fdbc30d0806422f"
}
],
"meta": {},
"link": null,
"filters": [
{
"filter": "geotarget_country",
"config": {
}
}
],
"ttl": 3600,
"tier": 3,
"override_ttl": false,
"zone": "geo1.testing",
"id": "5e81fd108fdbc30d08064230",
"networks": [
0
],
"regions": {},
"type": "A"
}
Geotarget Latlong
The geotarget_latlong filter sorts answers by distance to the requester based on latitude and longitude.
Input Metadata | Type |
latitude | Float between -90 and 90 |
longitude | Float between -180 and 180 |
Geotarget Regional
The geotarget_regional filter sorts answers by distance to the geographical region (e.g., Europe, Asiapac, or US-East) of the requester.
Input Metadata | Type |
georegion | One of “US-EAST”, “US-WEST”, “US-CENTRAL”, “EUROPE”, “SOUTH-AMERICA”, “AFRICA”, “ASIAPAC”; or a list of several of these |
Netfence ASN
The netfence_asn filter eliminates answers whose ASN does not match the ASN of the requester’s IP.
Input Metadata | Type |
asn | List of integers |
Config Option | Type | Required? | Default | Explanation |
remove_no_asn | boolean | no | true | If any answers have an ASN matching the requester, then eliminate all answers without any ASN. If set to false, then answers without ASN are kept instead. |
Netfence Prefix
The netfence_prefix filter eliminates answers whose list of ip prefixes does not match the requester’s IP.
Input Metadata | Type |
ip_prefixes | List of strings |
Config Option | Type | Required? | Default | Explanation |
remove_no_ip_prefixes | boolean | no | true | If any answers have an ip prefix matching the requester, then eliminate all answers without any ip prefix. If set to false, then answers without ip prefix are kept instead. |
Priority
The priority filter examines the “priority” metadata field, and finds the lowest priority value from among all answers. It then returns all the answers that have exactly that priority value.
Input Metadata | Type |
priority | Unsigned (non-negative) int - should be between 0 and 5. By default, lower numbers correspond to a higher “priority” - an answer with a priority of 0 will be picked over one with a priority of 1. |
Config Option | Type | Required? | Default | Explanation |
eliminate | boolean | no | true | If enabled, rather than sorting and returning all answers, the priority filter will just find the answer with the lowest priority value and return only that, eliminating all others. (If there are multiple answers tied for highest priority, it will return all of them.) If this is set to “false”, then the filter sorts the answers rather than eliminating them, just like the Cost filter does. |
Note: any answers that do not have any associated priority metadata will always be considered last. They will always be eliminated (unless no answers have priority metadata, in which case the filter will do nothing), and the “sort” option will always put them at the end of the sort order.
Pulsar
The Pulsar filter sorts answers based on real-time routing data. Each answer is associated with a specific jobid, which is tied to a job that gathers statistics and telemetry that is used to rate the answer.
The Pulsar filter requires the “pulsar” input metadata field, which is a custom data structure. It always must be a dictionary, nested inside a list. The fields of the dictionary are as follows:
Parameter | Type | Description | Example | Required? |
job_id | string | The string ID of the pulsar job to be associated with this record. | ‘abc123’ | Yes |
granularities | List of strings | Specifies whether to use “geo”, “geo_asn” or both. We recommend using both. | Only 3 possible values: [‘geo’], [‘asn’], or [‘geo_asn’] | Yes |
bias | string | The bias to be associated with this answer - when Pulsar is comparing different latencies, it will apply this modifier to this answer to prioritize or de-prioritize it. Must take the form of a mathematical operator (one of ‘+’, ‘-’, or ‘*’) followed by a number which must be a positive float. The ‘+’ and ‘-’ operators add or subtract the specified number of milliseconds to the answer’s latency, and the ‘*’ operator scales the answer’s latency by the specified amount. | ‘+10’, ‘-55’, ‘*0.5’, ‘*2’ | No |
a5m_cutoff | float | The 5 minute availability cutoff to be associated with this answer. If availability of the Pulsar job associated with this answer over the last 5 minutes is lower than this value, this answer will be excluded from consideration. Must be a float between 0 and 1 (inclusive). | 0.9 | No |
Config Option | Type | Required? | Default | Explanation |
sort_descending | boolean | no | false | If enabled, the Pulsar filter sorts answers in descending order, from highest to lowest (instead of from lowest to highest). This is useful if the Pulsar metric you are routing with is best when maximized. |
Example Request:
Example:
“meta”: {
“pulsar”: [
{
“jobid”: “abc123”,
“granularities”: [“geo”, “geo_asn”],
“bias”: “+30”,
“a5m_cutoff”: 0.85
}
]
}
Pulsar Stabilize
The pulsar_stabilize filter analyzes real-time routing data, just like the Pulsar filter, but instead of sorting answers, it eliminates all answers that are a certain amount worse than the best answer. Therefore, all answers that perform “reasonably close” to best are kept, and what exactly constitutes “reasonably” can be configured by the user. All answers that aren’t eliminated are kept in the same order as before, so the results of any previous filters are maintained.
The pulsar_stabilize filter requires the “pulsar” input metadata field, which is a custom data structure. It always must be a dictionary, nested inside a list. The fields of the dictionary are as follows:
Parameter | Type | Description | Example | Required? |
job_id | string | The string ID of the Pulsar job to be associated with this record. | ‘abc123’ | Yes |
granularities | List of strings | Specifies whether to use “geo”, “geo_asn” or both. We recommend using both. | Only 3 possible values: [‘geo’], [‘asn’], or [‘geo_asn’] | Yes |
bias | string | The bias to be associated with this answer - when Pulsar is comparing different latencies, it will apply this modifier to this answer to prioritize or de-prioritize it. Must take the form of a mathematical operator (one of ‘+’, ‘-’, or ‘*’) followed by a number which must be a positive float. The ‘+’ and ‘-’ operators add or subtract the specified number of milliseconds to the answer’s latency, and the ‘*’ operator scales the answer’s latency by the specified amount. | ‘+10’, ‘-55’, ‘*0.5’, ‘*2’ | No |
a5m_cutoff | float | The 5 minute availability cutoff to be associated with this answer. If availability of the Pulsar job associated with this answer over the last 5 minutes is lower than this value, this answer will be excluded from consideration. Must be a float between 0 and 1 (inclusive). | 0.9 | No |
Config Option | Type | Required? | Default | Explanation |
stabilization_threshold | string | yes | Defines the threshold to use to decide which answers are kept. This is a string, which must contain a positive int, optionally followed with a ‘%’ sign. (E.x.: ‘100’, ‘30%’) If the value is just an int, then the cutoff value is calculated as the value (e.g., latency) of the best performing answer, plus this number of milliseconds. If the value is a percentage, then the cutoff will be the value of the best performing answer, plus that percentage of itself. (So if the stabilization_threshold is ‘30%’, the cutoff will be 130% of the best answer’s latency.) | |
sort_descending | boolean | no | false | If enabled, the pulsar_stabilize filter bases the cutoff on the highest answer instead of the lowest, and removes all answers below that cutoff instead of above. The cutoff will be the pulsar value of the highest answer, minus whatever amount is specified by the stabilization_threshold, instead of plus like normal. |
Example Request:
Example:
“meta”: {
“pulsar”: [
{
“jobid”: “abc123”,
“granularities”: [“geo”, “geo_asn”],
“bias”: “+30”,
“a5m_cutoff”: 0.85
}
]
}
Config Option | Type | Required? | Default | Explanation |
stabilization_threshold | string | yes | Defines the threshold to use to decide which answers are kept. This is a string, which must contain a positive int, optionally followed with a ‘%’ sign. (E.x.: ‘100’, ‘30%’) If the value is just an int, then the cutoff value is calculated as the value (e.g., latency) of the best performing answer, plus this number of milliseconds. If the value is a percentage, then the cutoff will be the value of the best performing answer, plus that percentage of itself. (So if the stabilization_threshold is ‘30%’, the cutoff will be 130% of the best answer’s latency.) | |
sort_descending | boolean | no | false | If enabled, the pulsar_stabilize filter bases the cutoff on the highest answer instead of the lowest, and removes all answers below that cutoff instead of above. The cutoff will be the pulsar value of the highest answer, minus whatever amount is specified by the stabilization_threshold, instead of plus like normal. |
Select First N
The select_first_n filter eliminates all answers except for the first N, where N is specified in the filter config.
Config Option | Type | Required? | Default | Explanation |
N | int | no | 1 | The number of answers to keep. All answers after the first N answers will be eliminated. |
Select First Region
The select_first_region filter simply returns all answers in the same region as the first answer. There is no metadata input or filter config. In the portal this is called “select first group”.
Shed Load
The shed_load filter proportionally eliminates or keeps answers based on how the load (or another selected metric) compares to the answer’s configured low and high watermarks. If the metric is lower than the low water mark, the answer will ALWAYS be kept. If the metric is higher than the high water mark, the answer will ALWAYS be removed. If the metric is between the low and high watermarks, it will be randomly kept or discarded with a probability based on where it is relative to the watermarks. (e.g., exactly halfway between the watermarks means a 50% chance of being discarded, a low watermark of 10 with a high watermark of 20 and a metric of 12 means a 20% chance of being discarded, etc)
Config Option | Type | Required? | Default | Explanation |
metric | String - one of ‘loadavg’, ‘connections’, or ‘requests’ | yes | ‘loadavg’ | The metadata field to use with the low/high watermark to determine load to shed. Allows logic to be based on average load, number of connections, or number of requests. |
Input Metadata | Type |
low_watermark | float |
high_watermark | float |
loadavg | float |
connections | int |
requests | int |
Shuffle
The shuffle filter randomly sorts the answers. There is no metadata input or filter config.
Sticky Shuffle
The sticky filter sorts answers uniquely based on the IP address of the requester. This means that while different requesters get random orderings of answers, the same requester always gets the same results.
Sticky Region
The sticky filter sorts regions uniquely based on the IP address of the requester. This ensures that the same requester always gets an answer from the same region.
Config Option | Type | Required? | Default | Explanation |
sticky_by_network | bool | no | false | Apply stickiness by subnet rather than individual IP (/24 for IPv4 or /56 for IPv6). Useful to help ensure users load balanced across multiple recursors get the same answer. |
Up
The up filter eliminates all answers where the “up” metadata field is false or missing
Input Metadata | Type |
up | ‘true’, ‘false’, ‘1’, ‘0’, or int or boolean |
Weighted Shuffle
The weighted_shuffle filter shuffles answers randomly based on their “weight”. Answers with higher weight will be first more often.
Input Metadata | Type |
weight | float |
Weighted Sticky Shuffle
The weighted_sticky filter shuffles answers randomly based on their “weight”, AND maintains consistency per requester like the sticky shuffle filter. Answers with higher weight will be first more often, and the same requester will consistently get the same results.
Config Option | Type | Required? | Default | Explanation |
sticky_by_network | bool | no | false | Apply stickiness by subnet rather than individual IP (/24 for IPv4 or /56 for IPv6). Useful to help ensure users load balanced across multiple recursors get the same answer. |
Input Metadata | Type |
weight | float |
Enterprise DDI
Note: When using the API documentation to manage your Enterprise DDI configuration, you must replace the domain in the example URLs with your own domain (ex. http://api.mycompany.net).
Download Resources
NS1 Customer Success enables customers to download Docker container images for Private DNS and Enterprise DDI. Container images are available via download using an API key created in my.nsone.net.
Operations
Operations endpoints are performed by operator users. Operator users perform special system administrative tasks such as bootstrapping, managing services, and managing tenant organizations.
POST ops/bootstrap
POSTBootstrap the first operator user
When no operator users exist in the main database, the bootstrap endpoint is enabled. This is the only endpoint which does not require authentication. Note: Bootstrap can only be performed once. If the returned API key is lost, the system must be deployed again.
Request URL:
https://:apidomain/v1/ops/bootstrap
Example URL:
https://api.mycompany.net/v1/ops/bootstrap
Example Request:
{
"user": "root",
"name": "root user",
"email": "root@mycompany.net",
"password": "rootpassword"
}
Example Response:
{
"two_factor_auth": { "secret": "2FASECRET", "type": "totp" },
"name": "root user",
"id": "5b11aABCDEFG1373d",
"user": "root",
"key": "APIKEY",
"last_access": "2018-06-01T19:56:56.604228",
"password": "L0R3M1PSUm",
"email": "root@mycompany.net"
}
GET ops/operators
GETView all operator users
Returns a list of all operator users in the system.
GET ops/operator/:operator-id
GETView operator details
Returns information about the operator user.
Request URL:
https://api.mycompany.net/v1/ops/operators/:operator-id
Example Response:
{
"two_factor_auth": {
"secret": "ENCRYPTED2FASECRET==",
"type": "totp"
},
"password": "ENCRYPTEDpassword",
"name": "Operator User",
"id": "5d4OPERATORID3df",
"user": "operator",
"key": "ENCRYPEDapikey",
"last_access": "2019-08-05T18:23:53.278277",
"email": "operator@mycompany.net"
}
PUT ops/operators
PUTCreate a new operator user
Create a new operator user for the system. In addition to creating other operators, organizations, and services; operators can act as administrators on behalf of any organization in the system where users within a tenant organization only have access to that organization’s resources (e.g. zones, records, API keys, etc.).
Example Request:
{
"user": "operator",
"name": "Operator Name",
"email": "operator@mycompany.net",
"password": "operatorpassword"
}
Example Response:
{
"two_factor_auth": { "secret": "2FASECRET", "type": "totp" },
"name": "Operator User",
"id": "5b11aABCDEFG1373d",
"user": "operator",
"key": "APIKEY",
"last_access": "2018-06-01T19:56:56.604228",
"password": "L0R3M1PSUm",
"email": "operator@mycompany.net"
}
POST ops/operators/:operator-id
POSTModify details of an operator
Updates an operator's information.
Example Request:
{
"name": "New Operator Name"
}
Example Response:
{
"two_factor_auth": {
"secret": "ENCRYPTEDsecret==",
"type": "totp"
},
"name": "New Operator Name",
"id": "5d487439ef788400538533df",
"user": "operator",
"last_access": "2019-08-05T18:23:53.278277",
"email": "operator@mycompany.net"
}
DELETE ops/operators/:operator-id
DELETEDelete an operator
Removes another operator from the system. An operator cannot remove themselves.
GET /ops/orgs
GETView a list of organizations
Returns a list of the tenant organizations.
GET ops/orgs/:orgid
GETView organization details
Returns the details of an organization.
Request URL:
ops/orgs/:orgid
Example URL:
ops/orgs/2000
Example Response:
{
"org_id": 2000,
"ts_create": "2019-08-05T19:06:41.459029Z",
"ts_update": "2019-08-05T19:06:41.459029Z",
"name": "Demo User",
"id": 2000
}
PUT ops/orgs
PUTCreate an organization
Create a new tenant organization.
Example Request:
{
"name": "My Company"
}
Example Response:
{
"org_id": 2000,
"ts_create": "2019-08-05T19:37:08.065898054Z",
"ts_update": "2019-08-05T19:37:08.065898054Z",
"name": "My Company",
"id": 2000
}
POST ops/orgs/:orgid
POSTModify an organization
Modify the organization's name.
Request URL:
ops/orgs/:orgid
Example URL:
ops/org/2000
Example Request:
{
"name": "Updated Name"
}
Example Response:
{
"org_id": 2000,
"ts_create": "2019-08-05T19:37:08.065898Z",
"ts_update": "2019-08-05T19:37:08.065898Z",
"name": "Updated Name",
"id": 2000
}
DELETE ops/orgs/:orgid?token=abcdef
DELETEDelete an organization
Delete a tenant organization. This operation requires adding the token parameter with the operator's 2FA TOTP token.
Request URL:
ops/orgs/:orgid?token=abcdef
GET ops/orgs/:orgid/service/groups
GETView service groups associated with an organization
Returns a list of all service groups associated with an organization.
Request URL:
https://{api.mycompany.net}/v1/ops/orgs/:orgid/service/groups
Example URL:
https://{api.mycompany.net}/v1/ops/orgs/2000/service/groups
Example Response:
[
{
"require_unique_zones": false,
"name": "Global DNS",
"id": 1,
"config_tree_id": 1,
"type": "core",
"properties": {}
},
{
"require_unique_zones": false,
"name": "Private DNS",
"id": 2,
"config_tree_id": 1,
"type": "core",
"properties": {}
}
]
Service Definitions
GET ops/service/defs
GETView list of service definitions
Returns a list of all services of every type.
Example Response:
[
{
"config_tree_id": 0,
"properties": {},
"type": "DHCP",
"id": 4,
"name": "PDX DHCP"
},
{
"config_tree_id": 0,
"properties": {
"nameservers": [
"external.mycompany.net"
]
},
"type": "DNS",
"id": 2,
"name": "External DNS"
},
{
"config_tree_id": 0,
"properties": {
"nameservers": [
"internal.mycompany.net"
]
},
"type": "DNS",
"id": 3,
"name": "Internal DNS 2000"
},
{
"config_tree_id": 0,
"properties": {},
"type": "DHCP",
"id": 5,
"name": "RNO DHCP"
}
]
GET ops/service/defs/:definitionid
GETView service definition details
Returns the details of a service definition.
Request URL:
ops/service/defs/:definitionid
Example URL:
ops/service/defs/4
Example Response:
{
"config_tree_id": 0,
"properties": {},
"type": "DHCP",
"id": 4,
"name": "PDX DHCP"
}
POST ops/service/defs/:definitionid
POSTModify a service definition
Modify a service definition's information.
Request URL:
ops/service/defs/:definitionid
Example URL:
ops/service/defs/2
Example Request:
{ "properties": {
"nameservers": [
"ns1.mycompany.net",
"ns2.mycompany.net"
]
},
"type": "DNS",
"name": "External DNS"
}
Example Response:
{
"config_tree_id": 0,
"properties": {
"nameservers": [
"ns1.mycompany.net",
"ns2.mycompany.net"
]
},
"type": "DNS",
"id": 2,
"name": "External DNS"
}
DELETE ops/service/defs/:definitionid
DELETEDelete a service definition
Delete a service definition.
Request URL:
ops/service/defs/:definitionid
Example URL:
ops/service/defs/2
Example Response:
{}
PUT ops/service/defs
PUTCreate a new service definition
Create a new service definition (e.g. DNS Pools or DHCP Service). Service definitions groups application data for propagation to edge nodes.
Example Request:
{
"name": "External DNS",
"type": "DNS",
"nameservers": ["external.mycompany.net"],
"service_group_id": 1
}
Example Response:
{
"config_tree_id": 0,
"properties": {
"nameservers": [
"external.mycompany.net"
]
},
"type": "DNS",
"id": 2,
"name": "External DNS"
}
Example Request:
{
"name": "RNO DHCP",
"type": "DHCP",
"service_group_id": 2
}
Example Response:
{
"config_tree_id": 0,
"properties": {},
"type": "DHCP",
"id": 6,
"name": "RNO DHCP"
}
Service Groups
GET ops/service/groups
GETView a list of service groups
Returns a list of all service groups.
Example Response:
[
{
"properties": {},
"id": 1,
"name": "Global Services"
},
{
"properties": {},
"id": 2,
"name": "Private Services"
}
]
GET ops/service/groups/:servicegroupid
GETView service group details
Returns details of a service group.
Request URL:
ops/service/groups/:servicegroupid
Example URL:
ops/service/groups/1
Example Response:
{
"properties": {},
"id": 2,
"name": "Private Services"
}
PUT ops/service/groups
PUTCreate a service group
Creates a new service group.
Example Request:
{
"name": "Global Services",
}
Example Response:
{
"properties": null,
"id": 1,
"name": "Global Services"
}
POST ops/service/groups/:servicegroupid
POSTModify a service group
Modify a service group's name.
Request URL:
ops/service/groups/:servicegroupid
Example URL:
ops/service/groups/4
Example Request:
{
"name": "Updated Services"
}
Example Response:
{
"properties": null,
"id": 4,
"name": "Updated Services"
}
POST ops/service/groups/:servicegroupid/org/:orgid
POSTAssociate with an organization
Associate a service group with an organization. The tenant organization will have access to resources in this service group such as its DNS Pools and DHCP services.
Request URL:
ops/service/groups/:servicegroupid/org/:orgid
Example URL:
ops/service/groups/2/org/2000
Example Response:
{
"status": "success",
"org_id": "2000",
"service_group_id": "2"
}
DELETE ops/service/groups/:servicegroupid
DELETEDelete a service group
Deletes a service group from the system.
Request URL:
ops/service/groups/:servicegroupid
Example URL:
ops/service/groups/:4
Example Response:
{}
GET ops/service/groups/:servicegroupid/orgs
GETView organizations associated with a service group
Returns a list of organizations with access to this service group.
Request URL:
https://{api.mycompany.net}/v1/ops/service/groups/:servicegroupid/orgs
Example URL:
https://{api.mycompany.net}/v1/ops/service/groups/1/orgs
Example Response:
[
{
"properties": {},
"ts_create": "2019-12-19T18:25:05Z",
"ts_update": "2019-12-19T18:25:05Z",
"name": "Example Company",
"id": 2000
}
]
IPAM
GET /ipam/network
GETView a list of networks
Example URL:
https://api.mycompany.net/v1/ipam/network
Example Response:
[
{
"name": "string",
"desc": "string",
"rt": "string",
"kvps": {},
"tags": [
"string"
],
"free_addresses_v4": "string",
"used_addresses_v4": "string",
"total_addresses_v4": "string",
"num_prefixes_v4": "string",
"free_addresses_v6": "string",
"used_addresses_v6": "string",
"total_addresses_v6": "string",
"num_prefixes_v6": "string",
"addresses": [
{
"addr_id": 0,
"prefix": "string",
"name": "string"
}
]
}
]
GET /ipam/network/{networkId}
GETView a network
Example URL:
https://api.mycompany.net/v1/ipam/network/{networkId}
Example Response:
{
"name": "string",
"desc": "string",
"rt": "string",
"kvps": {},
"tags": [
"string"
],
"free_addresses_v4": "string",
"used_addresses_v4": "string",
"total_addresses_v4": "string",
"num_prefixes_v4": "string",
"free_addresses_v6": "string",
"used_addresses_v6": "string",
"total_addresses_v6": "string",
"num_prefixes_v6": "string",
"addresses": [
{
"addr_id": 0,
"prefix": "string",
"name": "string"
}
]
}
GET /ipam/network/{networkId}/report
GETView a network report
Get a report of network usage.
v{4,6}.total = sum(root.report.total for root in network.v{4,6}.root_addrs)v{4,6}.used = sum(root.report.used for root in network.v{4,6}.root_addrs)v{4,6}.free = network.v{4,6}.report.total - network.report.v{4,6}.used
Example URL:
https://api.nsone.net/v1/ipam/network/{networkId}/report
Example Response:
{
"v4": {
"total": "string",
"used": "string",
"free": "string"
},
"v6": {
"total": "string",
"used": "string",
"free": "string"
}
}
PUT /ipam/network
PUTCreate a network
Example URL:
https://api.mycompany.net/v1/ipam/network
Example Request:
{
"name": "My Cool Network",
"rt": "1.3.3.7:456"
}
Example Response:
{
"name": "string",
"desc": "string",
"rt": "string",
"kvps": {},
"tags": [
"string"
],
"free_addresses_v4": "string",
"used_addresses_v4": "string",
"total_addresses_v4": "string",
"num_prefixes_v4": "string",
"free_addresses_v6": "string",
"used_addresses_v6": "string",
"total_addresses_v6": "string",
"num_prefixes_v6": "string",
"addresses": [
{
"addr_id": 0,
"prefix": "string",
"name": "string"
}
]
}
POST /ipam/network/{networkId}
POSTUpdate a network
Example URL:
https://api.mycompany.net/v1/ipam/network/{networkId}
Example Request:
{
"tags": [
"my-awesome-tag"
]
}
Example Response:
{
"name": "string",
"desc": "string",
"rt": "string",
"kvps": {},
"tags": [
"string"
],
"free_addresses_v4": "string",
"used_addresses_v4": "string",
"total_addresses_v4": "string",
"num_prefixes_v4": "string",
"free_addresses_v6": "string",
"used_addresses_v6": "string",
"total_addresses_v6": "string",
"num_prefixes_v6": "string",
"addresses": [
{
"addr_id": 0,
"prefix": "string",
"name": "string"
}
]
}
DELETE /ipam/network/{networkId}
DELETERemove a network
Example URL:
https://api.mycompany.net/v1/ipam/network/{networkId}
GET /ipam/address
GETView a list of root addresses
Returns a list of all root addresses (i.e. indent == 0) in all networks for the requesting organization.
Example URL:
https://api.mycompany.net/v1/ipam/address
Example Response:
[
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
]
GET /ipam/address/{addressId}
GETView a subnet
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215",
"parent": {
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
}
GET /ipam/address/{addressID}/children
GETView address children
Request a list of all child addresses (or subnets) for the specified IP address.
Example Response:
[
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
]
| PATH PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| addressID* | integer | the ID of the address requests |
*Required
GET /ipam/address/{addressId}/parent
GETView address parent
Example URL:
https://api.mycompany.net/v1/ipam/address/{addressId}/parent
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
PUT /ipam/address
PUTCreate a subnet
Example URL:
https://api.mycompany.net/v1/ipam/address
Example Request:
{
"prefix": "10.0.0.0/16",
"network_id": 23,
"status": "assigned"
}
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
| Parameter | Type | Description |
|---|---|---|
| prefix* | string | an IPv4 or IPv6 subnet in CIDR notation |
| network_id* | integer | the ID of the containing network |
| kvps | object | user-defined key-value metadata |
| tags | array of strings | user-defined metadata inherited by children |
| desc | string | user-defined description |
| status | string | Default: "planned" Enum: "assigned" , "planned" the status of the subnet |
| name | string | user-defined name of the subnet |
*Required
POST /ipam/address/{addressId}
POSTEdit a subnet
Example URL:
https://api.mycompany.net/v1/ipam/address/{addressId}
Example Request:
{
"tags": [
"my-awesome-tag"
]
}
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215",
"parent": {
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
}
| Path Parameter | Type | Description |
|---|---|---|
| addressID* | integer | The ID of the address requested |
*Required
| Query Parameter | Type | Description |
|---|---|---|
| parent | boolean | Whether or not to include the parent in the parent field |
| Request Body Schema | Type | Description |
|---|---|---|
| kvps | object | user-defined, key-value metadata |
| tags | array of strings | user-defined metadata inhereted by children |
| desc | string | user-defined description |
| status | string | Default: "planned" Enum: "assigned" , "planned" the status of the subnet |
| name | string | user-defined name of the subnet |
POST /ipam/address/{addressId}/split
POSTSplit a subnet
Splitting an entire block of unassigned IP space into equal pieces. This will not function with ranges or individual hosts. Normal breaking out of a subnet is done with the standard PUT route. (Eg. root address is a /24 and request for /29s will break it into 32 /29s)
- Only planned subnets can be split
- Name and description will be unset on children
- KVPS and options will be copied; tags will be inherited as per normal
Example URL:
https://api.mycompany.net/v1/ipam/address/{addressId}/split
Example Request:
{
"prefix": 0
}
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "assigned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
TEST PARAMETERS
POST /ipam/address/merge
POSTMerge a subnet
Example URL:
https://api.mycompany.net/v1/ipam/address/merge
Example Request:
{
"root_address_id": 0,
"merged_address_id": 0
}
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"status": "planned",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
DELETE /ipam/address/{addressID}
DELETEDelete a subnet
Example URL:
https://api.mycompany.net/v1/ipam/address/{addressId}
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"type": "assignment",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215",
"parent": {
"prefix": "10.0.0.0/16",
"network_id": 12,
"kvps": {
"a": "2"
},
"tags": [
"custom-tag-1",
"custom-tag-2"
],
"desc": "Main subnet for US-EAST-1",
"type": "assignment",
"name": "US-EAST-1 Main",
"inherited_tags": [
"parent-tag-1",
"custom-tag-2"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"indent": 3,
"used_addresses": "53215"
}
}
GET /ipam/keys
GETView all organization keys
Get a list of all keys used by this organization for key-value pairs
Example Response:
[
"City",
"Hostname",
"Last Seen",
"LatLong",
"MAC",
"State",
"Zip"
]
GET /ipam/address/search
GETSearch for an address object
Returns a list of matching objects in the IP address management.
Example URL:
https://api.mycompany.net/v1/ipam/address/search/[?network=1][&max=5][&status=assigned][&tag=NA][&order_by=name][&asc_desc=asc][&mask=24]
Example URL:
https://api.mycompany.net/v1/ipam/address/search[?network=1][&order_by=name][&asc_desc=asc][&prefix=10.0.0.0]
Example Response:
[
{
"status": "assigned",
"free_addresses": "256",
"indent": 2,
"name": "Desk Phones",
"tags": [
"VOIP"
],
"kvps": {},
"children": 0,
"network_id": 1,
"prefix": "10.3.1.0/24",
"used_addresses": "0",
"inherited_tags": [
"NA",
"PDX"
],
"total_addresses": "256",
"id": 5
},
{
"status": "assigned",
"free_addresses": "255",
"indent": 2,
"name": "PC Workstations",
"tags": [
"PCs"
],
"kvps": {},
"children": 1,
"network_id": 1,
"prefix": "10.3.0.0/24",
"used_addresses": "1",
"inherited_tags": [
"NA",
"PDX"
],
"total_addresses": "256",
"id": 3
}
]
Example Response:
[
{
"status": "assigned",
"free_addresses": "65536",
"indent": 1,
"name": "New York Regional HQ",
"tags": [
"LGA"
],
"kvps": {
"City": "New York",
"LatLong": "40.705120,-74.011248",
"State": "NY",
"Zip": "10004"
},
"children": 0,
"network_id": 1,
"prefix": "10.0.0.0/16",
"used_addresses": "0",
"inherited_tags": [
"NA"
],
"total_addresses": "65536",
"id": 1,
"desc": "100 Chambers Blvd, Floor 20, New York, NY 10004"
},
{
"status": "planned",
"free_addresses": "8318976",
"indent": 0,
"name": "United States and Canada",
"tags": [
"NA"
],
"kvps": {},
"children": 2,
"network_id": 1,
"prefix": "10.0.0.0/9",
"used_addresses": "69632",
"inherited_tags": [],
"total_addresses": "8388608",
"id": 8,
"desc": "This /9 includes all subnets in North America locations."
}
]
| Parameter | Type | Description | Required? |
| network | Integer | A network identifier to filter against | |
| status | Enum | Limit the results to objects with the status of 'planned' or 'assigned' | |
| max | Integer | Limit the number of returned results to this amount | |
| tag | Array of strings | Comma delimited list of strings representing the tags to filter by; objects without these tags | |
| order_by | Enum | Order by either 'name' or 'addr' | |
| asc_desc | Enum | Sort in ascending ('asc') or descending ('desc') order | |
| mask | Integer | The mask length to search by (e.g. '/24') | |
| prefix | IP address | The address of the prefix to search for (e.g. '10.0.0.0') |
GET /v1/ipam/address/{addressID}/adjacent
GETView next (or previous) available prefix
Retrieves next or previous (aka adjacent) available IP address.
Copy CodeRetrieves the next-available IP address.
curl -L -X GET https://{webhost}/v1/ipam/address/{addressID}/adjacent -H "X-NSONE-Key: $APIKEY"
Copy CodeRetrieves previously available IP address.
curl -L -X GET https://{webhost}/v1/ipam/address/{addressID}/adjacent?previous=true -H "X-NSONE-Key: $APIKEY"
Note that you must include the query parameter, previous=true, in the URL path.
Example URL:
https://api.mycompany.net/v1/ipam/address/2/adjacent
Example URL:
https://api.mycompany.net/v1/ipam/address/2/adjacent?previous=true
Example Response:
{
"prefix": "10.3.16.0/20"
}
Example Response:
{
"prefix": "10.2.240.0/20"
}
GET /ipam/address/{subnet_id}/pool
GETList pools (IP range) within a subnet
Returns a list of pools (ranges of IP addresses) under a given subnet.
Example URL:
https://api.mycompany.net/v1/ipam/address/3/pool
Example Response:
[
{
"range": "10.3.0.1-10.3.0.100",
"id": 1,
"options": [
{
"name": "dhcpv4/time-offset",
"value": 777
}
]
},
{
"range": "10.3.0.111-10.3.0.115",
"id": 2,
"options": []
}
]
GET /ipam/address/{subnet_id}/pool/{pool_id}
GETView a pool (IP range) within a subnet
Returns a pool (range of IP addresses) under a given subnet.
Example URL:
https://api.mycompany.net/v1/ipam/address/3/pool/1
Example Response:
{
"range": "10.3.0.1-10.3.0.100",
"id": 1,
"options": [
{
"name": "dhcpv4/time-offset",
"value": 777
}
]
}
PUT /ipam/address/{subnet_id}/pool
PUTCreate a pool (IP range) within a subnet
Creates a pool (range of IP addresses) under a given subnet.
Example URL:
https://api.mycompany.net/v1/ipam/address/3/pool
Example Request:
{
"range": "10.3.0.1-10.3.0.100",
"options": []
}
Example Response:
{
"range": "10.3.0.1-10.3.0.100",
"id": 1,
"options": []
}
POST /ipam/address/{subnet_id}/pool/{pool_id}
POSTUpdate a pool (IP range) within a subnet
Updates a pool (range of IP addresses) under a given subnet.
Example URL:
https://api.mycompany.net/v1/ipam/address/3/pool/2
Example Request:
{
"options": [
{
"name": "dhcpv4/time-offset",
"value": 777,
"always-send": true
}
]
}
Example Response:
{
"range": "10.3.0.111-10.3.0.115",
"id": 2,
"options": [
{
"name": "dhcpv4/time-offset",
"value": 777
}
]
}
DELETE /ipam/address/{subnet_id}/pool/{pool_id}
DELETEDelete a pool (IP range) within a subnet
Deletes a pool (range of IP addresses) under a given subnet.
Example URL:
https://api.mycompany.net/v1/ipam/address/3/pool/2
DHCP
GET https://{api.mycompany.net}/v1/dhcp/scope
GETList scopes
Generate a list of the active scopes
Example Response:
[
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
}
]
| Parameter | Type | Description |
| scopeGroupID | integer | The id of a scope group to filter by. If set to -1, returns unassigned scopes. |
GET /dhcp/scope/{scopeID}
GETView scope details
Request details about a specific scope.
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
}
*required| Parameter | Type | Description |
| scopeID* | integer | the ID of the scope |
PUT /dhcp/scope
PUTCreate a scope
Create a scope.
Note: The DHCP server, if enabled, will allocate addresses from the associated IP address, grant any DHCP options associated with the address. The address and scope group must each meet certain invariants or else the request will result in a 422.
The address must:
- be of type
assignment. - not already be assigned to another scope group
options should be supported for the address' protocol.
Example Request:
{
"address_id": 1,
"scope_group_id": 2,
"options": []
}
| Parameter | Type | Description |
| address_id* | integer | the ID of the scope address; must not have host bits set |
| scope_group_id | integer | the ID of the scope group; if set and the scope group is active, the scope will be used for leases |
| options* | array of objects | the options assigned to this scope |
| name* | string | a namespaced DHCP option value |
| value* | string or array of strings | the DHCP option value |
*required
POST /dhcp/scope/{scopeID}
POSTModify a scope
Example Request:
{
"address_id": 1,
"scope_group_id": 2,
"options": []
}
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
}
| Parameter | Type | Description |
| scopeID* | integer | the ID of the scope |
| address_ID* | integer | the ID of the scope address; must not have host bits set |
| scope_group_id | integer | the ID of the associated scope group; if set and the scope group is active, the scope will be used for leases |
| options* | array of objects | the options assigned to this scope |
| name* | string | a namespaced DHCP option name |
| value* | string or array of strings | the DHCP option value |
*Required
DELETE /dhcp/scope/{scopeID}
DELETERemove a scope
Once removed, the address will no longer be used for leases and any current leases will be reclaimed.
Example URL:
https://api.mycompany.net/v1/dhcp/scope/{scopeId}
Example Response:
[
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
}
]
| Parameter | Type | Description |
| scopeGroupID | integer | The ID of a scope group by which to filter. If set to -1, returns unassigned scopes. |
GET /dhcp/scope/group
GETList scope groups
Request a list of all scope groups
Example Response:
[
{
"name": "string",
"dhcp_service_id": 0,
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"echo_client_id": true
},
"dhcpv6": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"preferred_lifetime_secs": 0
},
"id": 0
}
]
GET /dhcp/scopegroup/{scopegroupID}
GETView scope group
Request information about a scope groups using its unique ID.
Example URL:
http://api.mycompany.net/v1/dhcp/scopegroup/{scopegroupID}
Example Response:
{
"name": "string",
"dhcp_service_id": 0,
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"echo_client_id": true
},
"dhcpv6": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"preferred_lifetime_secs": 0
},
"id": 0,
"scopes": [
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"address_details": {
"name": "string",
"prefix": "string"
}
}
],
"reservations": [
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"mac": "a1:b2:c3:d4:e5:f6",
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"address_details": {
"name": "string",
"prefix": "string"
}
}
]
}
GET /dhcp/scopegroup/{scopeGroupId}/report
GETView scope group report
Returns a report about the specified scope group.
v{4,6}.total = sum(addr.report.total for addr in scope_group.v{4,6}.roots)v{4,6}.reserved = sum(1 for host in scope_group.v{4,6}.hosts if host.reserve and not host.lease)v{4,6}.fulfilled = sum(1 for host in scope_group.v{4,6}.hosts if host.reserve and host.lease)v{4,6}.leased = sum(1 for host in scope_group.v{4,6}.hosts if host.lease and not host.reserve)v{4,6}.free = scope_group.report.v{4,6}.total - scope_group.report.v{4,6}.leased - scope_group.report.v{4,6}.reserved - scope_group.v{4,6}.fulfilled
Notes:
- reserved and fulfilled, as separate states, are mutually exclusive – if a user wants to know the number of reservations,
reservations = reserved + fulfilled. - Similarly, if a user wants the total number of leases, including leases of static reservations,
leases = fulfilled + leased - Note that because a host cannot exist which is not one of
reserved,fulfilled, orleased,v{4,6}.freecould also be defined asv{4,6}.total - sum(1 for host in v{4,6}.hosts)
Example Response:
{
"v4": {
"total": "string",
"reserved": "string",
"fulfilled": "string",
"leased": "string",
"free": "string"
},
"v6": {
"total": "string",
"reserved": "string",
"fulfilled": "string",
"leased": "string",
"free": "string"
}
}
PUT /dhcp/scopegroup
PUTCreate a scope group
Creates a scope group with global settings and options.Options must be valid for the address's IP protocol. If the option has already been set, this request will overwrite it.
The following is a table of currently available DHCPv4 address options:
| Name | Type | Example |
| dhcpv4/routers | Array of IPv4 addresses | ["127.0.0.1", "127.0.0.2"] |
| dhcpv4/time-servers | Array of IPv4 Addresses | ["127.0.0.1", "127.0.0.2"] |
| dhcpv4/domain-name-servers | Array of IPv4 Addresses | ["127.0.0.1", "127.0.0.2"] |
| dhcpv4/host-name | string | "foobar" |
| dhcpv4/domain-name | string | "foobar.com" |
| dhcpv4/vendor-class-identifier | string | "supercoolcomputer" |
| dhcpv4/tftp-server-name | string | "tftp.foobar.com" |
| dhcpv4/bootfile-name | string | "/boot/from/here.img" |
Available DHCPv6 options include:
| Name | Type | Example |
| dhcpv6/dns-servers | Array of IPv6 addresses | ["2001:db8::cafe", "2001:db8::caff"] |
Copy CodeCreate a scope group with DDNS synthesis enabled
curl -L -X POST https://api.mycompany.net/v1/dhcp/scopegroup/1 -H "X-NSONE-Key: $API_KEY" -d '{ "dhcpv4": { "rebind_timer_secs": 43200, "renew_timer_secs": 21600, "echo_client_id": true, "enabled": true, "valid_lifetime_secs": 86400, "options": [], "synthesize_dns_records": { "enabled": true, "qualifying_suffix": "docker.local", "generated_prefix": "dynamic" } }, "dhcp_service_id": 3, "name": "Docker Network Scope" }'
Create a scope group with DDNS synthesis enabled, specifying the qualifying suffix, zone, and (optional) prefix.
Example Request:
{
"name": "my-scope-group",
"dhcpv4": {
"enabled": false
},
"dhcpv6": {},
"dhcp_service_id": 17
}
Example Response:
{
"name": "string",
"dhcp_service_id": 17,
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"echo_client_id": true
},
"dhcpv6": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"preferred_lifetime_secs": 0
},
"id": 4
}
POST /dhcp/scopegroup/{scopeGroupId}
POSTUpdate scope group by ID
Make changes to a scope group using its unique ID.
Copy CodeUpdate the scope group to enable DDNS synthesis
curl -L -X POST https://api.mycompany.net/v1/dhcp/scopegroup/1 -H "X-NSONE-Key: $API_KEY" -d '{ "dhcpv4": { "rebind_timer_secs": 43200, "renew_timer_secs": 21600, "echo_client_id": true, "enabled": true, "valid_lifetime_secs": 86400, "options": [], "synthesize_dns_records": { "enabled": true, "qualifying_suffix": "docker.local", "generated_prefix": "dynamic" } }, "dhcp_service_id": 3, "name": "Docker Network Scope" }'
Update the scope group with DDNS synthesis enabled, specifying the qualifying suffix, zone, and (optional) prefix.
Example URL:
https://api.mycompany.net/v1/dhcp/scopegroup/{scopeGroupId}
Example Request:
{
"name": "my-scope-group",
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 3600
},
"dhcpv6": {}
}
Example Response:
{
"name": "string",
"dhcp_service_id": 0,
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"echo_client_id": true
},
"dhcpv6": {
"enabled": true,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
],
"preferred_lifetime_secs": 0
},
"id": 0
}
DELETE /dhcp/scopegroup/{scopeGroupId}
DELETERemove scope group by ID
Example URL:
https://api.nsone.net/v1/dhcp/scopegroup/{scopeGroupId}
GET dhcp/reservation
GETList reservations
Request a list of all active DHCP reservations.
Request URL:
https://:apidomain/v1/dhcp/reservation
Example URL:
https://api.mycompany.net/v1/dhcp/reservation
Example Response:
[
{
"mac": "11:33:44:55:66:77",
"address_id": 6,
"id": 23,
"scope_group_id": 1,
"options": [
{
"name": "dhcpv4/host-name",
"value": "myhost"
},
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
},
{
"mac": "1C:22:AA:BB:DD:CC",
"address_id": 12,
"id": 21,
"options": [
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
}
]
| Parameter | Type | Description |
| scopeGroupID | integer | The id of a scope group by which to filter. If set to -1, returns unassigned scopes. |
GET https://{api.mycompany.net}/v1/dhcp/reservation/{reservationId}
GETView a reservation's details
Request URL:
https://{api.mycompany.net}/v1/dhcp/reservation/{reservationId}
Example URL:
https://api.mycompany.net/v1/dhcp/reservation/23
Example Response:
{
"mac": "11:33:44:55:66:77",
"address_id": 6,
"id": 23,
"scope_group_id": 1,
"options": [
{
"name": "dhcpv4/host-name",
"value": "myhostname"
}
]
}
| Parameter | Type | Description |
| reservationID | integer | The ID of the reservation |
PUT dhcp/reservation
PUTCreate a reservation
Creates a new host reservation.
Note: Currently, the reservation must be associated with an address. The DHCP server, if enabled, will provide the associated IP address and any DHCP options to the client with the associated MAC address. The address and scope group must each meet certain invariants or else the request will result in a 422.
The address must:
- Be of status = assigned.
- Not be associated with another scope group
- Not have another conflicting reservation
The scope group must:
- Only contain reservations and scopes from a single network.
Options should be supported for the address' protocol.
Request URL:
https://:apidomain/v1/dhcp/reservation
Example URL:
https://api.mycompany.net/v1/dhcp/reservation
Example Request:
{
"address_id": 12,
"scope_group_id": 2,
"mac": "a1:b2:c3:d4:e5:f6",
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
]
}
Example Response:
{
"address_id": 12,
"scope_group_id": 2,
"id": 21,
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
]
}
| Parameter | Type | Description |
| address_id* | integer | the id of the address which is being reserved |
| scope_group_id | integer | the id of the scope group; if present, this reservation will be published |
| mac | string | A mac address for which an address is reserved |
| options* | array of objects | the options assigned to this reservation |
| name* | string | a namespaced DHCP option name |
| value* | string or array of strings | the DHCP option value |
*required
POST dhcp/reservation/:reservationId
POSTModify a reservation
Modify an existing DHCP reservation.
Note: The DHCP server, if enabled, will provide the associated IP address and any DHCP options to the client with the associated MAC address. The address and scope group must each meet certain invariants or else the request will result in a 422.
The address must:
- Be of type
host. - Not be associated with another
scope group - Not have another conflicting
reservation
options should be supported for the address' protocol.
Request URL:
https://:apidomain/v1/dhcp/reservation/:reservationId
Example URL:
https://api.mycompany.net/v1/dhcp/reservation/23
Example Request:
{
"options": [
{
"name": "dhcpv4/host-name",
"value": "myhostname"
},
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
}
Example Response:
{
"mac": "11:33:44:55:66:77",
"address_id": 6,
"id": 23,
"scope_group_id": 1,
"options": [
{
"name": "dhcpv4/host-name",
"value": "myhostname"
},
{
"name": "dhcpv4/bootfile-name",
"value": "/boot.img"
}
]
}
| Parameter | Type | Description |
| address_id* | integer | the ID of the address that is being reserved |
| scope_group_id | integer | the id of the scope group. if present, this reservation will be published |
| mac | string | A mac address for which an address is reserved |
| options* | array of objects | the options assigned to this reservation |
| name* | string | a namespaced DHCP option name |
| value* | string or array of strings | the DHCP option value |
DELETE dhcp/reservation/:reservationid
DELETEDelete a reservation
Request URL:
https://:apidomain/v1/dhcp/:reservationid
Example URL:
https://api.mycompany.net/v1/dhcp/21
Example Response:
{}
GET dhcp/lease
GETList leases
Lists any active leases, optionally filtering by one or more parameters.
Request URL:
https://:apidomain/v1/dhcp/lease
Example URL:
https://api.mycompany.net/v1/dhcp/lease
Example Response:
{
"prefix": "string",
"scope_group_id": 0,
"dhcid": "string",
"mac": "string",
"expiration": "2019-08-05T17:09:33Z"
}
| Parameter | Type | Description |
| scopegroupID | integer | the ID of a scope group by which to filter |
| scopeID | integer | the ID of a scope by which to filter |
| limit | integer | the maximum number of records to return |
| offset | integer | the offset within the records list |
PUT dhcp/optiondef/:space/:key
PUTCreate an custom DHCP option definition
Create an option definition. The key and code must be unique in the chosen option space.
NOTE
The following are important guidelines to follow when configuring a custom DHCP option with “complex” schema selected:
- The record must consist of at least two fields.
- "String" or "binary" fields must be last in the order of primitive types.
- You can only enter one "string" field or one "binary" field per record.
- "Empty" type is not allowed in a complex record.
- You cannot create an array of “string” or “binary” field types.
- If a string contains commas, they must be escaped with double-backslash (\\).
The following are important guidelines to follow when configuring a custom DHCP option with "array" schema selected selected:
- You cannot create an array of "string", "binary", or "empty" field types.
Request URL:
https://{api.mycompany.net}/v1/dhcp/optiondef/:space/:key
Example URL:
https://{api.mycompany.net}/v1/dhcp/optiondef/dhcpv4/simple-example
Example URL:
https://{api.mycompany.net}/v1/dhcp/optiondef/dhcpv4/array-example
Example URL:
https://{api.mycompany.net}/v1/dhcp/optiondef/dhcpv4/complex-record-example
Example Request:
{
"friendly_name": "Single Data Type Option Definition",
"description": "Example of Single Data Type Option Definition",
"code": 215,
"standard": false,
"schema": {
"type": "fqdn"
}
}
Example Response:
{
"code": 215,
"description": "Example of Single Data Type Option Definition",
"space": "dhcpv4",
"friendly_name": "Single Data Type Option Definition",
"key": "simple-example",
"schema": {
"type": "fqdn"
}
}
Example Request:
{
"friendly_name": "Array Data Type Definition",
"description": "Example of Array Option Definition",
"code": 216,
"standard": false,
"schema": {
"items": "fqdn",
"type": "array"
}
}
Example Response:
{
"code": 216,
"description": "Example of Array Option Definition",
"space": "dhcpv4",
"friendly_name": "Array Data Type Definition",
"key": "array-example",
"schema": {
"items": "fqdn",
"type": "array"
}
}
Example Request:
{
"friendly_name": "Example Complex Record with Data Types",
"description": "An example dhcp option",
"code": 217,
"schema": {
"type": "record",
"fields": [
{
"name": "IPv4",
"type": "ipv4_address"
},
{
"name": "IPv6",
"type": "ipv6_address"
},
{
"name": "IPv6Prefix",
"type": "ipv6_prefix"
},
{
"name": "Boolean",
"type": "boolean"
},
{
"name": "Empty",
"type": "empty"
},
{
"name": "FQDN",
"type": "fqdn"
},
{
"name": "Hex",
"type": "hex"
},
{
"name": "Int16",
"type": "int16"
},
{
"name": "Int32",
"type": "int32"
},
{
"name": "Int8",
"type": "int8"
},
{
"name": "PSID",
"type": "psid"
},
{
"name": "String",
"type": "string"
},
{
"name": "Tuple",
"type": "tuple"
},
{
"name": "Uint16",
"type": "uint16"
},
{
"name": "Uint32",
"type": "uint32"
},
{
"name": "Uint8",
"type": "uint8"
}
]
}
}
Example Response:
{
"code": 217,
"description": "An example dhcp option",
"space": "dhcpv4",
"friendly_name": "Example Record with Data Types",
"key": "complex-record-example",
"schema": {
"fields": [
{
"type": "ipv4_address",
"name": "IPv4"
},
{
"type": "ipv6_address",
"name": "IPv6"
},
{
"type": "ipv6_prefix",
"name": "IPv6Prefix"
},
{
"type": "boolean",
"name": "Boolean"
},
{
"type": "empty",
"name": "Empty"
},
{
"type": "fqdn",
"name": "FQDN"
},
{
"type": "hex",
"name": "Hex"
},
{
"type": "int16",
"name": "Int16"
},
{
"type": "int32",
"name": "Int32"
},
{
"type": "int8",
"name": "Int8"
},
{
"type": "psid",
"name": "PSID"
},
{
"type": "string",
"name": "String"
},
{
"type": "tuple",
"name": "Tuple"
},
{
"type": "uint16",
"name": "Uint16"
},
{
"type": "uint32",
"name": "Uint32"
},
{
"type": "uint8",
"name": "Uint8"
}
],
"type": "record"
}
}
POST https://{api.mycompany.net}/v1/:space/optiondef/:key
POSTModify an custom DHCP option definition
Modify an option definition. The key and code must be unique in the chosen option space.
Request URL:
/v1/dhcp/optiondef/:space/:key
Example URL:
dhcp/optiondef/dhcpv4/simple-example
Example URL:
dhcp/optiondef/dhcpv4/array-example
Example URL:
dhcp/optiondef/dhcpv4/complex-record-example
Example Request:
{
"friendly_name": "Single Data Type Option Definition",
"description": "Modified Single Data Type Option Definition",
"code": 215,
"standard": false,
"schema": {
"type": "fqdn"
}
}
Example Response:
{
"code": 215,
"description": "Modified Single Data Type Option Definition",
"space": "dhcpv4",
"friendly_name": "Single Data Type Option Definition",
"key": "simple-example",
"schema": {
"type": "fqdn"
}
}
Example Request:
{
"friendly_name": "Array Data Type Definition",
"description": "Modified Array Option Definition",
"code": 216,
"standard": false,
"schema": {
"items": "fqdn",
"type": "array"
}
}
Example Response:
{
"code": 216,
"description": "Modified Array Option Definition",
"space": "dhcpv4",
"friendly_name": "Array Data Type Definition",
"key": "array-example",
"schema": {
"items": "fqdn",
"type": "array"
}
}
Example Request:
{
"friendly_name": "Example Complex Record with Data Types",
"description": "A modified example dhcp option",
"code": 217,
"schema": {
"type": "record",
"fields": [
{
"name": "IPv4",
"type": "ipv4_address"
},
{
"name": "IPv6",
"type": "ipv6_address"
},
{
"name": "IPv6Prefix",
"type": "ipv6_prefix"
},
{
"name": "Boolean",
"type": "boolean"
},
{
"name": "Empty",
"type": "empty"
},
{
"name": "FQDN",
"type": "fqdn"
},
{
"name": "Hex",
"type": "hex"
},
{
"name": "Int16",
"type": "int16"
},
{
"name": "Int32",
"type": "int32"
},
{
"name": "Int8",
"type": "int8"
},
{
"name": "PSID",
"type": "psid"
},
{
"name": "String",
"type": "string"
},
{
"name": "Tuple",
"type": "tuple"
},
{
"name": "Uint16",
"type": "uint16"
},
{
"name": "Uint32",
"type": "uint32"
},
{
"name": "Uint8",
"type": "uint8"
}
]
}
}
Example Response:
{
"code": 217,
"description": "A modified example dhcp option",
"space": "dhcpv4",
"friendly_name": "Example Record with Data Types",
"key": "complex-record-example",
"schema": {
"fields": [
{
"type": "ipv4_address",
"name": "IPv4"
},
{
"type": "ipv6_address",
"name": "IPv6"
},
{
"type": "ipv6_prefix",
"name": "IPv6Prefix"
},
{
"type": "boolean",
"name": "Boolean"
},
{
"type": "empty",
"name": "Empty"
},
{
"type": "fqdn",
"name": "FQDN"
},
{
"type": "hex",
"name": "Hex"
},
{
"type": "int16",
"name": "Int16"
},
{
"type": "int32",
"name": "Int32"
},
{
"type": "int8",
"name": "Int8"
},
{
"type": "psid",
"name": "PSID"
},
{
"type": "string",
"name": "String"
},
{
"type": "tuple",
"name": "Tuple"
},
{
"type": "uint16",
"name": "Uint16"
},
{
"type": "uint32",
"name": "Uint32"
},
{
"type": "uint8",
"name": "Uint8"
}
],
"type": "record"
}
}
DELETE dhcp/optiondef/:space/:key
DELETEDelete an option definition
Delete an option definition.
Request URL:
https://{api.mycompany.net}/v1/dhcp/optiondef/:space/:key
Example URL:
https://{api.mycompany.net}/v1/dhcp/optiondef/dhcpv4/simple-example
GET dhcp/optiondef
GETList option definitions
Return a list of option definitions available to this organization and optionally filter by parameters.
Request URL:
https://{api.mycompany.net}/v1/dhcp/optiondef
Example URL:
https://{api.mycompany.net}/v1/dhcp/optiondef
Example Response:
[
{
"schema": {
"items": "fqdn",
"type": "array"
},
"code": 216,
"friendly_name": "Array Data Type Definition",
"key": "array-example",
"space": "dhcpv4"
},
{
"schema": {
"fields": [
{
"type": "ipv4_address",
"name": "IPv4"
},
{
"type": "ipv6_address",
"name": "IPv6"
},
{
"type": "ipv6_prefix",
"name": "IPv6Prefix"
},
{
"type": "boolean",
"name": "Boolean"
},
{
"type": "empty",
"name": "Empty"
},
{
"type": "fqdn",
"name": "FQDN"
},
{
"type": "hex",
"name": "Hex"
},
{
"type": "int16",
"name": "Int16"
},
{
"type": "int32",
"name": "Int32"
},
{
"type": "int8",
"name": "Int8"
},
{
"type": "psid",
"name": "PSID"
},
{
"type": "string",
"name": "String"
},
{
"type": "tuple",
"name": "Tuple"
},
{
"type": "uint16",
"name": "Uint16"
},
{
"type": "uint32",
"name": "Uint32"
},
{
"type": "uint8",
"name": "Uint8"
}
],
"type": "record"
},
"code": 217,
"friendly_name": "Example Record with Data Types",
"key": "complex-record-example",
"space": "dhcpv4"
},
{
"schema": {
"type": "fqdn"
},
"code": 215,
"friendly_name": "Single Data Type Option Definition",
"key": "simple-example",
"space": "dhcpv4"
}
]
| Parameter | Type | Description |
| code | integer | Filter by option code (e.g. code=6). |
| space | dhcpv4 or dhcpv6 | Filter by the option space (e.g. space=dhcpv4). |
| key | string | Filter the list by key (e.g. domain-name-servers). |
| standard | boolean | Filter by whether or not the option definition is a standard option and not a user-defined custom option. |
Active Directory
Configure an Active Directory server configuration for the organization for using Active Directory authentication and role-based access controls.
GET activedirectory
GETView Active Directory configuration
Returns details of current Active Directory configuration.
Request URL:
https://{api.mycompany.net}/v1/activedirectory
Example URL:
https://{api.mycompany.net}/v1/activedirectory
Example Response:
{
"server": "1.1.1.1",
"port": 389,
"base_dn": "users.ns1.com",
"user": "john",
"domain": "ns1.com",
"secure": false
}
| server | string | IP for the Active Directory server |
| port | integer | (Optional) Port for the AD connection |
| domain | string | Domain used for the connections |
| base_dn | string | (Optional) The search base DN used as a start point on the tree search |
| user | string | Login name for the DN Bind |
| secure | boolean | Option to enable a secure connection |
DELETE activedirectory
DELETEDelete Active Directory configuration
Deletes the AD configuration entry associated with the current organization.
Request URL:
https://{api.mycompany.net}/v1/activedirectory
Example URL:
https://{api.mycompany.net}/v1/activedirectory
Example Response:
{}
POST activedirectory
POSTModify Active Directory configuration
Modifies the AD configuration entry associated with the current organization.
Example URL:
https://{api.mycompany.net}/v1/activedirectory
Request URL:
https://{api.mycompany.net}/v1/activedirectory
Example Request:
{
"server": "2.2.2.2",
"port": 389,
"domain": "ns1.com",
"base_dn": "users.ns1.com",
"user": "john",
"password": "abc1234",
"secure": false,
}
Example Response:
{
"server": "2.2.2.2",
"port": 389,
"base_dn": "users.ns1.com",
"user": "john",
"domain": "ns1.com",
"secure": false
}
| server | string | IP for the Active Directory server |
| port | integer | (Optional) Port for the AD connection |
| domain | string | Domain used for the connections |
| base_dn | string | (Optional) Base Distinguished Name |
| user | string | Login name for the DN Bind |
| password | string | Password for the DN Bind |
| secure | boolean | Option to enable a secure connection |
| tls_cert | string | TLS cert in case a secure connection is enabled |
PUT activedirectory
PUTCreate an Active Directory configuration
Create a new AD configuration entry associated with the current organization.
Request URL:
https://{api.mycompany.net}/v1/activedirectory
Example URL:
https://{api.mycompany.net}/v1/activedirectory
Example Request:
{
"server": "1.1.1.1",
"port": 389,
"domain": "ns1.com",
"base_dn": "users.ns1.com",
"user": "john",
"password": "abc1234",
"secure": false,
}
Example Response:
{
"server": "1.1.1.1",
"port": 389,
"base_dn": "users.ns1.com",
"user": "john",
"domain": "ns1.com",
"secure": false
}
| server | string | IP for the Active Directory server |
| port | integer | (Optional) Port for the AD connection |
| domain | string | Domain used for the connections |
| base_dn | string | (Optional) Base Distinguished Name |
| user | string | Login name for the DN Bind |
| password | string | Password for the DN Bind |
| secure | boolean | Option to enable a secure connection |
| tls_cert | string | TLS cert in case a secure connection is enabled |
POST activedirectory/test
POSTTest the Active Directory connection
Test the Microsoft Active Directory server connection.
Example URL:
https://{api.mycompany.net}/v1/activedirectory/test
Request URL:
https://{api.mycompany.net}/v1/activedirectory/test
Example Request:
{
"server": "2.2.2.2",
"port": 389,
"domain": "ns1.com",
"base_dn": "users.ns1.com",
"user": "john",
"password": "abc1234",
"secure": false,
}
Example Response:
{
"The connection to the Domain Controller was successful."
}
| server | string | IP address for the Active Directory server |
| port | integer | (Optional) Port for the AD connection |
| domain | string | Domain used for the connections |
| base_dn | string | (Optional) Base Distinguished Name |
| user | string | Login name for the DN Bind |
| password | string | Password for the DN Bind |
| secure | boolean | Option to enable a secure connection |
| tls_cert | string | TLS cert in case a secure connection is enabled |