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 NS1 portal (my.nsone.net).
Note: You should treat your API keys as secrets. You should also give them only the minimal access needed for your application.
Refer to the NS1 Help Center for our complete library of technical documentation.
If you have any questions or experience any issues while using the API, please submit a support ticket.
Client Libraries
Python | Go | PHP | Javascript
Account Management
General
GET /v1/account/settings
GET View account contact details
Returns details about the primary contact associated with the account.
Copy CodeReturns account admin contact details
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/settings
Request URL:
https://api.nsone.net/v1/account/settings
Example Response:
{
"email": "[email protected]",
"address": {
"country": "US",
"street": "Some Address Suite 2100",
"state": "NY",
"city": "New York",
"postalcode": "10005"
},
"phone": "",
"customerid": 5309,
"company": "NSONE API Example Account",
"lastname": "Example",
"firstname": "API"
}
POST /v1/account/settings
POST Edit account contact details
Modifies the primary contact details associated with the account.
Request body parameters:
| firstname | string | First name of the account admin |
| lasttname | string | Last name of the account admin |
| company | string | Name of the company associated with the account |
| address | object | Set of address details associated with the account |
| street | string | Street address associated with the account contact |
| city | string | City associated with the account contact address |
| state | string | State associated with the account contact address |
| postalcode | string or integer | Postal code associated with the account contact address |
| country | string | Country associated with the account contact address |
| string | Primary email address associated with the account | |
| secondary_email | string | Secondary (backup) email address associated with the account |
| phone | string | Phone number associated with the account |
| title | string | Title of the primary contact associated with the account |
| website | string | Company website associated with the account |
Copy CodeEdits account admin contact details
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/settings
Request URL:
https://api.nsone.net/v1/account/settings
Example Request:
{
"lastname": "Smith",
"firstname": "John"
}
Example Response:
{
"email": "[email protected]",
"address": {
"country": "US",
"street": "Some Address Suite 2100",
"state": "NY",
"city": "New York",
"postalcode": "10005"
},
"phone": "",
"customerid": 5309,
"company": "NSONE API Example Account",
"lastname": "Smith",
"firstname": "John"
}
GET /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.
Copy CodeReturns overage alert settings
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/usagewarnings
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 /v1/account/usagewarnings
POST Edit overage alert 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 body parameters:
| records | object | Object containing the overage alert settings for records |
| zones | object | Object containing the overage alert settings for zones |
| warning_1 | integer | Threshold (overage percentage) upon which to send the first overage alert |
| warning_2 | integer | Threshold (overage percentage) upon which to send the second overage alert |
| send_warnings | boolean | Indicates whether or not overage alerts are enabled |
Copy CodeEdits overage alert settings
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/usagewarnings
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 /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).
Example Response:
[
{
"permissions": {
"dns": {
"view_zones": true,
"manage_zones": true,
"zones_allow_by_default": false,
"zones_deny": [],
"zones_allow": [
"example.com"
],
"records_allow": [],
"records_deny": [
{
"zone": "example.com",
"domain": "deny.example.com",
"include_subdomains": false,
"type": "A"
}
]
},
"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,
"manage_ip_whitelist": false
},
"monitoring": {
"manage_lists": false,
"manage_jobs": false,
"view_jobs": false
},
"security": {
"manage_global_2fa": false
}
},
"teams": [],
"email": "[email protected]",
"last_access": 1376325771,
"notify": {
"billing": true
},
"name": "API Example",
"username": "apiexample",
"ip_whitelist_strict": false,
"ip_whitelist": []
},
{
"permissions": {
"dns": {
"view_zones": true,
"manage_zones": true,
"zones_allow_by_default": false,
"zones_deny": [],
"zones_allow": [
"example.com"
],
"records_allow": [],
"records_deny": [
{
"zone": "example.com",
"domain": "deny.example.com",
"include_subdomains": false,
"type": "A"
}
]
},
"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,
"manage_ip_whitelist": false
},
"monitoring": {
"manage_lists": false,
"manage_jobs": false,
"view_jobs": false
},
"security": {
"manage_global_2fa": false
}
},
"email": "[email protected]",
"last_access": null,
"notify": {
"billing": true
},
"name": "New User",
"username": "newuser",
"ip_whitelist_strict": false,
"ip_whitelist": [],
"shared_auth": {
"saml": {
"sso": false,
"idp": {
"use_metadata_url": null,
"metadata_url": null,
"metadata_file": null,
"provider": null
}
}
},
"2fa_enabled": false
}
]
GET /v1/account/users/:username
GETView user details
Returns details for the user specified in the URL path by their username.
Path Parameters:
| username | string | (Required) Username of the account user for whom you are requesting details. |
Copy CodeReturns user details
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/users/:username
Example Response:
{
"permissions": {
"dns": {
"view_zones": true,
"manage_zones": true,
"zones_allow_by_default": false,
"zones_deny": [],
"zones_allow": [
"example.com"
],
"records_allow": [],
"records_deny": [
{
"zone": "example.com",
"domain": "deny.example.com",
"include_subdomains": false,
"type": "AAAA"
}
]
},
"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,
"manage_ip_whitelist": false
},
"monitoring": {
"manage_lists": false,
"manage_jobs": false,
"view_jobs": false
},
"security": {
"manage_global_2fa": false
}
},
"teams": [
"520422919f782d37dffb588a"
],
"email": "[email protected]",
"last_access": null,
"notify": {
"billing": true
},
"name": "New User",
"username": "newuser",
"ip_whitelist_strict": false,
"ip_whitelist": []
}
PUT /v1/account/users
PUTCreate a new user
Creates a new user within the current NS1 account.
If adding a user to your Managed DNS account, executing this command will automatically send an invitation email to the user's email address. Users can click to set a password and log into https://my.nsone.net. The user cannot log into their Managed DNS account until they accept the invitation and set a password.
If adding a user to your Enterprise DDI account, an invite token is included in the response (next to invite_token). Provide this invite token to the user and instruct them to go to the invite URL (ex. http://{portal.mycompany.net}/#/invite/{invite_token} replacing portal.mycompany.net with your specific DDI portal FQDN). The user will set the password on this webpage.
Important note about API key security: NS1 recommends restricting access to your API key and reducing permissions only to include what the application requires. Keep your API key secret. If it is compromised, delete the API key immediately. Restrict access to this key by applying IP addresses or CIDR blocks in the ip_whitelist property (ex. ip_whitelist: ['104.20.48.182', '104.20.49.0/24']).
Request Body Parameters:
| username | string | (Required) Username for the new account user. Must be between 3-64 characters. |
| string | (Required) Email address associated with the new user. This is where the invite email and other notifications, if applicable, are sent. | |
| name | string | Full name of the new user. |
| teams | array of strings | Array of team IDs corresponding to teams with which to associate this user. If assigned to a team, the user inherits the permissions set for that team. |
| ip_whitelist_strict | boolean | Set to true to restrict access to only those IP addresses and networks listed in the ip_whitelist field. |
| ip_whitelist | array of strings | Array of IP addresses/networks to which to grant the user access. Optionally, set the ip_whitelist_strict field to true to restrict access to only those IP addresses/networks listed in this field. |
| notify | object | Set of supported notifications to enable or disable for this user. |
| billing | boolean | (part of notify object) Enables or disables notifications related to account billing events. |
| permissions | object | All supported permissions |
| account | object | (part of permissions object) Group of account-related permissions. |
| manage_account_settings | boolean | (part of account object) Allows (or prevents, if false) the user to manage account settings. |
| manage_teams | boolean | (part of account object) Allows (or prevents, if false) the user to create or update teams. |
| manage_users | boolean | (part of account object) Allows (or prevents, if false) the user to create or update users. |
| manage_apikeys | boolean | (part of account object) Allows (or prevents, if false) the user to create or update API keys. |
| manage_ip_whitelist | boolean | (part of account object) Allows (or prevents, if false) the user to create or update IP "allow" lists. |
| view_activity_log | boolean | (part of account object) Allows (or prevents, if false) the user to view the account activity log. |
| manage_payment_methods | boolean | (part of account object) Allows (or prevents, if false) the user to manage account payment methods. |
| view_invoices | boolean | (part of account object) Allows (or prevents, if false) the user to view account invoices. |
| manage_auth_tags | boolean | (part of account object) Allows (or prevents, if false) the user to create and edit authorization of ('auth:') tags. Auth tags determine access controls to view or manage resources. Auth tags control access, so the user must also have the 'manage_auth_keys' permission set to true. |
| manage_service | boolean | (part of account object) Allows (or prevents, if false) the user to create and modify services. (DDI only) |
| view_service | boolean | (part of account object) Allows (or prevents, if false) the user to view services. (DDI only) |
| data | object | (part of permissions object) Group of data-related permissions. |
| manage_datasources | boolean | (part of data object) Allows (or prevents, if false) the user to create and modify data sources. |
| manage_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the user to create and modify data feeds. |
| push_to_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the user to push data to NS1 data feeds. |
| dhcp | object | (part of permissions object) Group of DHCP-related permissions. |
| manage_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the user to manage DHCP configuration settings. |
| view_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the user to view DHCP configuration settings. |
| tags_allow | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to grant access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to deny access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| dns | object | (part of permissions object) Group of DNS-related permissions. |
| manage_zones | boolean | (part of dns object) Allows (or prevents, if false) the user to create or modify zones. |
| view_zones | boolean | (part of dns object) Allows (or prevents, if false) the user to view zones. |
| zones_allow_by_default | boolean | (part of dns object) Set to true to allow access to all zones except for those listed under zones_deny. Set to false to deny access to all zones by default except for those listed under zones_allow. |
| zones_allow | array of strings | (part of dns object) List of specific zones to which the API key is allowed access. If zones_allow_by_default property is set to false, the zones listed next to the zones_allow property are the only zones accessible to the user. |
| zones_deny | array of strings | (part of dns object) List of specific zones to which the user is denied access. If zones_allow_by_default property is set to true, the zones listed next to the zones_deny property are the only zones not accessible to the user. |
| records_allow | array of objects | (part of dns object) Array of specific record to which the user is allowed access. |
| records_deny | array of objects | (part of dns object) Array of specific record to which the user is denied access. |
| zone | string | (Required; part of records_allow and/or records_deny objects) Name of the zone to which the record belongs. |
| domain | string | (Required; part of records_allow and/or records_deny objects) Domain name associated with the record. |
| include_subdomains | boolean | (Required; part of records_allow and/or records_deny objects) If a domain is specified, set to "true" to apply the same permissions to all subdomains. |
| type | string | (Required; part of records_allow and/or records_deny objects) Type of record to which you are allowing or denying access. |
| ipam | object | (part of permissions object) Group of IPAM-related permissions. |
| manage_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the user to manage IPAM settings. |
| view_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the user to view IPAM settings. |
| tags_allow | array of objects | (part of ipam object) List of IPAM tag permission specifiers used to grant access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of IPAM tag permission specifiers used to deny access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| monitoring | object | (part of permissions object) Group of monitoring-related permissions. |
| manage_lists | boolean | (part of monitoring object) Allows (or prevents, if false) the user to create or modify notification lists. |
| manage_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the user to create or modify monitoring jobs. |
| view_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the user to view monitoring jobs. |
| security | object | (part of permissions object) Group of security-related permissions. |
| manage_global_2fa | boolean | (part of security object) Allows (or prevents, if false) the user to manage global two-factor authentication (2FA) settings. |
| manage_active_directory | boolean | (part of security object) Allows (or prevents, if false) the user to manage Active Directory settings. (DDI only) |
| manage_kerberos | boolean | (part of security object) Allows (or prevents, if false) the user to manage Kerberos settings. (DDI only) |
| manage_ddns | boolean | (part of security object) Allows (or prevents, if false) the user to manage dynamic DNS (DDNS) settings. (DDI only) |
| service | object | (part of permissions object) Group of DDI service-related permissions. (DDI only) |
| view_config | boolean | (part of service object) Allows (or prevents, if false) the user to view DDI service (container/node) configurations. (DDI only) |
| manage_config | boolean | (part of service object) Allows (or prevents, if false) the user to modify DDI service (container/node) configurations. (DDI only) |
Example Request:
{
"username": "newuser",
"email": "[email protected]",
"name": "New User",
"teams": [],
"permissions": {
"data": {
"push_to_datafeeds": false,
"manage_datafeeds": false,
"manage_datasources": false
},
"account": {
"view_invoices": false,
"view_activity_log": false,
"manage_teams": false,
"manage_apikeys": false,
"manage_users": false,
"manage_payment_methods": false,
"manage_plan": false,
"manage_account_settings": false,
"manage_ip_whitelist": false
},
"dns": {
"zones_allow": [
"example.com"
],
"zones_deny": [],
"zones_allow_by_default": false,
"manage_zones": false,
"view_zones": true,
"records_allow": [
{
"zone": "example.com",
"domain": "example.com",
"include_subdomains": false
},
{
"zone": "example.com"
}
],
"records_deny": [
{
"zone": "example.com",
"domain": "deny.example.com",
"type": "MX"
},
{
"zone": "foo.bar",
"domain": "deny.example.com",
"include_subdomains": true,
"type": "A"
},
{
"zone": "wha.what",
"type": "AAAA"
},
{
"zone": "example.com",
"type": "DNSSEC"
},
{
"zone": "another.example",
"domain": "noway.example.com"
}
]
},
"monitoring": {
"manage_lists": false,
"manage_jobs": false,
"view_jobs": false
},
"security": {
"manage_global_2fa": false
}
}
}
Example Response:
{
"2fa_enabled": true,
"created": 0,
"invite_token": "string",
"last_access": null,
"username": "some_username69",
"shared_auth": {
"saml": {
"sso": true,
"idp": {
"use_metadata_url": null,
"metadata_url": null,
"metadata_file": null,
"provider": null
}
}
},
"email": "string",
"ip_whitelist": [
"strings"
],
"ip_whitelist_strict": true,
"name": "string",
"notify": {
"billing": true
},
"permissions": {
"account": {
"manage_account_settings": true,
"manage_teams": true,
"manage_users": true,
"manage_apikeys": true,
"manage_ip_whitelist": true,
"view_activity_log": true,
"manage_payment_methods": true,
"manage_plan": true,
"view_invoices": true,
"manage_auth_tags": true,
"manage_service": true,
"view_service": true
},
"data": {
"manage_datasources": true,
"manage_datafeeds": true,
"push_to_datafeeds": true
},
"dhcp": {
"manage_dhcp": true,
"view_dhcp": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"dns": {
"manage_zones": true,
"view_zones": true,
"zones_allow_by_default": true,
"zones_allow": [
"foo.bar.com"
],
"zones_deny": [
"foo.bar.com"
],
"records_allow": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
],
"records_deny": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
]
},
"ipam": {
"manage_ipam": true,
"view_ipam": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"monitoring": {
"manage_lists": true,
"manage_jobs": true,
"view_jobs": true
},
"security": {
"manage_global_2fa": true,
"manage_active_directory": true,
"manage_kerberos": true,
"manage_ddns": true
},
"service": {
"view_config": true,
"manage_config": true
}
},
"teams": [
"50eb9d77830f784f98b0dd59"
]
}
POST /v1/account/users/:username
POSTEdit user details
Updates settings for an existing user.
Important note about API key security: NS1 recommends restricting access to your API key and reducing permissions only to include what the application requires. Keep your API key secret. If it is compromised, delete the API key immediately. Restrict access to this key by applying IP addresses or CIDR blocks in the ip_whitelist property (ex. ip_whitelist: ['104.20.48.182', '104.20.49.0/24']).
Path Parameters:
| username | string | (Required) Username associated with the user you are editing. |
Request Body Parameters:
| string | (Required) Email address associated with the new user. This is where the invite email and other notifications, if applicable, are sent. | |
| name | string | Full name of the new user. |
| teams | array of strings | Array of team IDs corresponding to teams with which to associate this user. If assigned to a team, the user inherits the permissions set for that team. |
| ip_whitelist_strict | boolean | Set to true to restrict access to only those IP addresses and networks listed in the ip_whitelist field. |
| ip_whitelist | array of strings | Array of IP addresses/networks to which to grant the user access. Optionally, set the ip_whitelist_strict field to true to restrict access to only those IP addresses/networks listed in this field. |
| notify | object | Set of supported notifications to enable or disable for this user. |
| billing | boolean | (part of notify object) Enables or disables notifications related to account billing events. |
| permissions | object | All supported permissions |
| account | object | (part of permissions object) Group of account-related permissions. |
| manage_account_settings | boolean | (part of account object) Allows (or prevents, if false) the user to manage account settings. |
| manage_teams | boolean | (part of account object) Allows (or prevents, if false) the user to create or update teams. |
| manage_users | boolean | (part of account object) Allows (or prevents, if false) the user to create or update users. |
| manage_apikeys | boolean | (part of account object) Allows (or prevents, if false) the user to create or update API keys. |
| manage_ip_whitelist | boolean | (part of account object) Allows (or prevents, if false) the user to create or update IP "allow" lists. |
| view_activity_log | boolean | (part of account object) Allows (or prevents, if false) the user to view the account activity log. |
| manage_payment_methods | boolean | (part of account object) Allows (or prevents, if false) the user to manage account payment methods. |
| view_invoices | boolean | (part of account object) Allows (or prevents, if false) the user to view account invoices. |
| manage_auth_tags | boolean | (part of account object) Allows (or prevents, if false) the user to create and edit authorization of ('auth:') tags. Auth tags determine access controls to view or manage resources. Auth tags control access, so the user must also have the 'manage_auth_keys' permission set to true. |
| manage_service | boolean | (part of account object) Allows (or prevents, if false) the user to create and modify services. (DDI only) |
| view_service | boolean | (part of account object) Allows (or prevents, if false) the user to view services. (DDI only) |
| data | object | (part of permissions object) Group of data-related permissions. |
| manage_datasources | boolean | (part of data object) Allows (or prevents, if false) the user to create and modify data sources. |
| manage_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the user to create and modify data feeds. |
| push_to_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the user to push data to NS1 data feeds. |
| dhcp | object | (part of permissions object) Group of DHCP-related permissions. |
| manage_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the user to manage DHCP configuration settings. |
| view_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the user to view DHCP configuration settings. |
| tags_allow | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to grant access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to deny access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| dns | object | (part of permissions object) Group of DNS-related permissions. |
| manage_zones | boolean | (part of dns object) Allows (or prevents, if false) the user to create or modify zones. |
| view_zones | boolean | (part of dns object) Allows (or prevents, if false) the user to view zones. |
| zones_allow_by_default | boolean | (part of dns object) Set to true to allow access to all zones except for those listed under zones_deny. Set to false to deny access to all zones by default except for those listed under zones_allow. |
| zones_allow | array of strings | (part of dns object) List of specific zones to which the API key is allowed access. If zones_allow_by_default property is set to false, the zones listed next to the zones_allow property are the only zones accessible to the user. |
| zones_deny | array of strings | (part of dns object) List of specific zones to which the user is denied access. If zones_allow_by_default property is set to true, the zones listed next to the zones_deny property are the only zones not accessible to the user. |
| records_allow | array of objects | (part of dns object) Array of specific record to which the user is allowed access. |
| records_deny | array of objects | (part of dns object) Array of specific record to which the user is denied access. |
| zone | string | (Required; part of records_allow and/or records_deny objects) Name of the zone to which the record belongs. |
| domain | string | (Required; part of records_allow and/or records_deny objects) Domain name associated with the record. |
| include_subdomains | boolean | (Required; part of records_allow and/or records_deny objects) If a domain is specified, set to "true" to apply the same permissions to all subdomains. |
| type | string | (Required; part of records_allow and/or records_deny objects) Type of record to which you are allowing or denying access. |
| ipam | object | (part of permissions object) Group of IPAM-related permissions. |
| manage_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the user to manage IPAM settings. |
| view_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the user to view IPAM settings. |
| tags_allow | array of objects | (part of ipam object) List of IPAM tag permission specifiers used to grant access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of IPAM tag permission specifiers used to deny access for the user to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the user will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| monitoring | object | (part of permissions object) Group of monitoring-related permissions. |
| manage_lists | boolean | (part of monitoring object) Allows (or prevents, if false) the user to create or modify notification lists. |
| manage_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the user to create or modify monitoring jobs. |
| view_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the user to view monitoring jobs. |
| security | object | (part of permissions object) Group of security-related permissions. |
| manage_global_2fa | boolean | (part of security object) Allows (or prevents, if false) the user to manage global two-factor authentication (2FA) settings. |
| manage_active_directory | boolean | (part of security object) Allows (or prevents, if false) the user to manage Active Directory settings. (DDI only) |
| manage_kerberos | boolean | (part of security object) Allows (or prevents, if false) the user to manage Kerberos settings. (DDI only) |
| manage_ddns | boolean | (part of security object) Allows (or prevents, if false) the user to manage dynamic DNS (DDNS) settings. (DDI only) |
| service | object | (part of permissions object) Group of DDI service-related permissions. (DDI only) |
| view_config | boolean | (part of service object) Allows (or prevents, if false) the user to view DDI service (container/node) configurations. (DDI only) |
| manage_config | boolean | (part of service object) Allows (or prevents, if false) the user to modify DDI service (container/node) configurations. (DDI only) |
Copy CodeEdits the name of an existing user
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{"name": "Jane Smith"}' https://api.nsone.net/v1/account/users/jsmith
Example Response:
{
"permissions": {
"dns": {
"view_zones": true,
"manage_zones": true,
"zones_allow_by_default": false,
"zones_deny": [],
"zones_allow": [
"example.com"
],
"records_allow": [],
"records_deny": [
{
"zone": "example.com",
"domain": "deny.example.com",
"include_subdomains": false,
"type": "A"
}
]
},
"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,
"manage_ip_whitelist": false
},
"monitoring": {
"manage_lists": false,
"manage_jobs": false,
"view_jobs": false
},
"security": {
"manage_global_2fa": false
}
},
"teams": [],
"email": "[email protected]",
"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 /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.
Path Parameters:
| username | string | (Required) Username for the account user you are deleting. |
Copy CodeDeletes the account user
curl -X DELETE -H "X-NSONE-Key: $API_KEY" http://api.nsone.net/v1/account/users/:username
POST /v1/account/reinvite/:username
POSTResend invitation to a user
In the event that a user does not receive their invitation email or the invitation has expired, you may resend the invitation. There is no response other than the HTTP status code. Note that if the user has already logged into their account, you will not be able to resent the invitation. Instead, the user should click the "Forgot Password" link on the login page to verify their email address and reset their password.
Path Parameters:
| username | string | (Required) Username for the user to whom you are resending the invitation. |
Request Body Parameters:
| string | Email address associated with the user | |
| name | string | Full name of the user |
| username | string | Username for the user |
Copy CodeInvite a new user with full access to your account
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{"username":"newuser", "name":"New User", "email":"[email protected]"}' https://api.nsone.net/v1/account/users/newuser
An invitation email will be sent to [email protected] allowing them to set a password and log in to my.nsone.net.
DELETE /v1/account/2factor/reset/:username
DELETEReset two-factor authentication (2FA) for user
This operation resets two-factor authentication (2FA) for user specified by their username. Once cleared, the user can log into the portal normally. If enabled globally, the user will be prompted to set up 2FA upon login.
Copy CodeClears existing 2FA configuration for the specified user
curl -X DELETE -H "X-NSONE-KEY:key" https://api.nsone.net/v1/account/2factor/reset/{username}
Example Response:
2FA disabled for user '{userId}'
API key
GET /v1/account/apikeys
GETList 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 conditions as users.
Copy CodeReturns a list of API keys
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/account/apikeys
Example Response:
[
{
"ip_whitelist_strict": false,
"name": "MyAPIKey",
"key": "abcdefghijklmnopqrst",
"ip_whitelist": [],
"last_access": null,
"teams": [],
"id": "5d727dc9f1e0e100621352a6",
"permissions": {
"account": {
"manage_account_settings": true,
"manage_apikeys": true,
"manage_users": true,
"manage_teams": true,
"view_activity_log": true,
"manage_ip_whitelist": true
},
"ipam": {
"view_ipam": true,
"manage_ipam": true,
"tags_allow": [
{
"name": "auth:allow1"
},
{
"name": "auth:allow2"
},
{
"name": "auth:zip",
"value": "07030"
},
{
"name": "auth:lat_lon",
"value": "+12.345-098.765"
}
],
"tags_deny": [
{
"name": "auth:deny1"
},
{
"name": "auth:deny2"
},
{
"name": "auth:zip",
"value": "90210"
},
{
"name": "auth:lat_lon",
"value": "+16.345-096.765"
}
]
},
"dns": {
"zones_allow": [
"example.com"
],
"manage_zones": true,
"zones_allow_by_default": true,
"view_zones": true
},
"dhcp": {
"manage_dhcp": true,
"view_dhcp": true
},
"security": {
"manage_global_2fa": true
},
"data": {
"manage_datafeeds": true,
"manage_datasources": true,
"push_to_datafeeds": true
}
}
}
]
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 /v1/account/apikeys
PUTCreate an API key
Creates a new API key and returns the API key string in the key field in the response.
Important note about API key security: NS1 recommends restricting access to your API key and reducing permissions only to include what the application requires. Keep your API key secret. If it is compromised, delete the API key immediately. Restrict access to this key by applying IP addresses or CIDR blocks in the ip_whitelist property (ex. ip_whitelist: ['104.20.48.182', '104.20.49.0/24']).
Request Body Parameters:
| ip_whitelist_strict | boolean | Set to true to restrict access to only those IP addresses and networks listed in the ip_whitelist field. |
| name | string | Name of the API key you are creating (2-64 characters). |
| ip_whitelist | array of strings | Array of IP addresses/networks to which to grant the API key access. Optionally, set the ip_whitelist_strict field to true to restrict access to only those IP addresses/networks listed in this field. |
| teams | array of strings | One or more teams with which this API key is associated. If assigned to a team, the API key inherits the permissions set for that team. |
| permissions | object | All supported permissions |
| account | object | (part of permissions object) Group of account-related permissions. |
| manage_account_settings | boolean | (part of account object) Allows (or prevents, if false) the API key to manage account settings. |
| manage_teams | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update teams. |
| manage_users | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update users. |
| manage_apikeys | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update API keys. |
| manage_ip_whitelist | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update IP "allow" lists. |
| view_activity_log | boolean | (part of account object) Allows (or prevents, if false) the API key to view the account activity log. |
| manage_payment_methods | boolean | (part of account object) Allows (or prevents, if false) the API key to manage account payment methods. |
| view_invoices | boolean | (part of account object) Allows (or prevents, if false) the API key to view account invoices. |
| manage_auth_tags | boolean | (part of account object) Allows (or prevents, if false) the API key to create and edit authorization of ('auth:') tags. Auth tags determine access controls to view or manage resources. Auth tags control access, so the API key must also have the 'manage_auth_keys' permission set to true. |
| manage_service | boolean | (part of account object) Allows (or prevents, if false) the API key to create and modify services. (DDI only) |
| view_service | boolean | (part of account object) Allows (or prevents, if false) the API key to view services. (DDI only) |
| data | object | (part of permissions object) Group of data-related permissions. |
| manage_datasources | boolean | (part of data object) Allows (or prevents, if false) the API key to create and modify data sources. |
| manage_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the API key to create and modify data feeds. |
| push_to_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the API key to push data to NS1 data feeds. |
| dhcp | object | (part of permissions object) Group of DHCP-related permissions. |
| manage_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the API key to manage DHCP configuration settings. |
| view_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the API key to view DHCP configuration settings. |
| tags_allow | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to grant access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to deny access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| dns | object | (part of permissions object) Group of DNS-related permissions. |
| manage_zones | boolean | (part of dns object) Allows (or prevents, if false) the API key to create or modify zones. |
| view_zones | boolean | (part of dns object) Allows (or prevents, if false) the API key to view zones. |
| zones_allow_by_default | boolean | (part of dns object) Set to true to allow access to all zones except for those listed under zones_deny. Set to false to deny access to all zones by default except for those listed under zones_allow. |
| zones_allow | array of strings | (part of dns object) List of specific zones to which the API key is allowed access. If zones_allow_by_default property is set to false, the zones listed next to the zones_allow property are the only zones accessible to the API key. |
| zones_deny | array of strings | (part of dns object) List of specific zones to which the API key is denied access. If zones_allow_by_default property is set to true, the zones listed next to the zones_deny property are the only zones not accessible to the API key. |
| records_allow | array of objects | (part of dns object) Array of specific record to which the API key is allowed access. |
| records_deny | array of objects | (part of dns object) Array of specific record to which the API key is denied access. |
| zone | string | (Required; part of records_allow and/or records_deny objects) Name of the zone to which the record belongs. |
| domain | string | (Required; part of records_allow and/or records_deny objects) Domain name associated with the record. |
| include_subdomains | boolean | (Required; part of records_allow and/or records_deny objects) If a domain is specified, set to "true" to apply the same permissions to all subdomains. |
| type | string | (Required; part of records_allow and/or records_deny objects) Type of record to which you are allowing or denying access. |
| ipam | object | (part of permissions object) Group of IPAM-related permissions. |
| manage_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the API key to manage IPAM settings. |
| view_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the API key to view IPAM settings. |
| tags_allow | array of objects | (part of ipam object) List of IPAM tag permission specifiers used to grant access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of IPAM tag permission specifiers used to deny access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| monitoring | object | (part of permissions object) Group of monitoring-related permissions. |
| manage_lists | boolean | (part of monitoring object) Allows (or prevents, if false) the API key to create or modify notification lists. |
| manage_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the API key to create or modify monitoring jobs. |
| view_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the API key to view monitoring jobs. |
| security | object | (part of permissions object) Group of security-related permissions. |
| manage_global_2fa | boolean | (part of security object) Allows (or prevents, if false) the API key to manage global two-factor authentication (2FA) settings. |
| manage_active_directory | boolean | (part of security object) Allows (or prevents, if false) the API key to manage Active Directory settings. (DDI only) |
| manage_kerberos | boolean | (part of security object) Allows (or prevents, if false) the API key to manage Kerberos settings. (DDI only) |
| manage_ddns | boolean | (part of security object) Allows (or prevents, if false) the API key to manage dynamic DNS (DDNS) settings. (DDI only) |
| service | object | (part of permissions object) Group of DDI service-related permissions. (DDI only) |
| view_config | boolean | (part of service object) Allows (or prevents, if false) the API key to view DDI service (container/node) configurations. (DDI only) |
| manage_config | boolean | (part of service object) Allows (or prevents, if false) the API key to modify DDI service (container/node) configurations. (DDI only) |
Copy CodeCreate an API Key that can only view one zone
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -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.
Example Request:
{
"ip_whitelist_strict": true,
"name": "string",
"key": "stringstringstringst",
"ip_whitelist": [
"strings"
],
"last_access": null,
"teams": [
"50eb9d77830f784f98b0dd59"
],
"id": "string",
"permissions": {
"account": {
"manage_account_settings": true,
"manage_teams": true,
"manage_users": true,
"manage_apikeys": true,
"manage_ip_whitelist": true,
"view_activity_log": true,
"manage_payment_methods": true,
"manage_plan": true,
"view_invoices": true,
"manage_auth_tags": true,
"manage_service": true,
"view_service": true
},
"data": {
"manage_datasources": true,
"manage_datafeeds": true,
"push_to_datafeeds": true
},
"dhcp": {
"manage_dhcp": true,
"view_dhcp": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"dns": {
"manage_zones": true,
"view_zones": true,
"zones_allow_by_default": true,
"zones_allow": [
"foo.bar.com"
],
"zones_deny": [
"foo.bar.com"
],
"records_allow": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
],
"records_deny": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
]
},
"ipam": {
"manage_ipam": true,
"view_ipam": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"monitoring": {
"manage_lists": true,
"manage_jobs": true,
"view_jobs": true
},
"security": {
"manage_global_2fa": true,
"manage_active_directory": true,
"manage_kerberos": true,
"manage_ddns": true
},
"service": {
"view_config": true,
"manage_config": true
}
}
}
Example Response:
{
"ip_whitelist_strict": true,
"name": "string",
"key": "stringstringstringst",
"ip_whitelist": [
"strings"
],
"last_access": null,
"teams": [
"50eb9d77830f784f98b0dd59"
],
"id": "string",
"permissions": {
"account": {
"manage_account_settings": true,
"manage_teams": true,
"manage_users": true,
"manage_apikeys": true,
"manage_ip_whitelist": true,
"view_activity_log": true,
"manage_payment_methods": true,
"manage_plan": true,
"view_invoices": true,
"manage_auth_tags": true,
"manage_service": true,
"view_service": true
},
"data": {
"manage_datasources": true,
"manage_datafeeds": true,
"push_to_datafeeds": true
},
"dhcp": {
"manage_dhcp": true,
"view_dhcp": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"dns": {
"manage_zones": true,
"view_zones": true,
"zones_allow_by_default": true,
"zones_allow": [
"foo.bar.com"
],
"zones_deny": [
"foo.bar.com"
],
"records_allow": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
],
"records_deny": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
]
},
"ipam": {
"manage_ipam": true,
"view_ipam": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"monitoring": {
"manage_lists": true,
"manage_jobs": true,
"view_jobs": true
},
"security": {
"manage_global_2fa": true,
"manage_active_directory": true,
"manage_kerberos": true,
"manage_ddns": true
},
"service": {
"view_config": true,
"manage_config": true
}
}
}
POST /v1/account/apikeys/:keyID
POSTEdit an API key
Updates the settings for the API key specified in the URL path by its unique keyID and returns the API key string in the key field in the response.
Important note about API key security: NS1 recommends restricting access to your API key and reducing permissions only to include what the application requires. Keep your API key secret. If it is compromised, delete the API key immediately. Restrict access to this key by applying IP addresses or CIDR blocks in the ip_whitelist property (ex. ip_whitelist: ['104.20.48.182', '104.20.49.0/24']).
Path Parameters:
| keyID | string | Unique identifier for the API key. This value is returned in the response after creating an API key and can be viewed by executing an API call to view API key details. |
Request Body Parameters:
| ip_whitelist_strict | boolean | Set to true to restrict access to only those IP addresses and networks listed in the ip_whitelist field. |
| name | string | Name of the API key you are creating (2-64 characters). |
| ip_whitelist | array of strings | Array of IP addresses/networks to which to grant the API key access. Optionally, set the ip_whitelist_strict field to true to restrict access to only those IP addresses/networks listed in this field. |
| teams | array of strings | One or more team IDs corresponding to teams with which this API key is associated. If assigned to a team, the API key inherits the permissions set for that team. |
| permissions | object | All supported permissions |
| account | object | (part of permissions object) Group of account-related permissions. |
| manage_account_settings | boolean | (part of account object) Allows (or prevents, if false) the API key to manage account settings. |
| manage_teams | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update teams. |
| manage_users | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update users. |
| manage_apikeys | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update API keys. |
| manage_ip_whitelist | boolean | (part of account object) Allows (or prevents, if false) the API key to create or update IP "allow" lists. |
| view_activity_log | boolean | (part of account object) Allows (or prevents, if false) the API key to view the account activity log. |
| manage_payment_methods | boolean | (part of account object) Allows (or prevents, if false) the API key to manage account payment methods. |
| view_invoices | boolean | (part of account object) Allows (or prevents, if false) the API key to view account invoices. |
| manage_auth_tags | boolean | (part of account object) Allows (or prevents, if false) the API key to create and edit authorization of ('auth:') tags. Auth tags determine access controls to view or manage resources. Auth tags control access, so the API key must also have the 'manage_auth_keys' permission set to true. |
| manage_service | boolean | (part of account object) Allows (or prevents, if false) the API key to create and modify services. (DDI only) |
| view_service | boolean | (part of account object) Allows (or prevents, if false) the API key to view services. (DDI only) |
| data | object | (part of permissions object) Group of data-related permissions. |
| manage_datasources | boolean | (part of data object) Allows (or prevents, if false) the API key to create and modify data sources. |
| manage_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the API key to create and modify data feeds. |
| push_to_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the API key to push data to NS1 data feeds. |
| dhcp | object | (part of permissions object) Group of DHCP-related permissions. |
| manage_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the API key to manage DHCP configuration settings. |
| view_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the API key to view DHCP configuration settings. |
| tags_allow | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to grant access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to deny access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| dns | object | (part of permissions object) Group of DNS-related permissions. |
| manage_zones | boolean | (part of dns object) Allows (or prevents, if false) the API key to create or modify zones. |
| view_zones | boolean | (part of dns object) Allows (or prevents, if false) the API key to view zones. |
| zones_allow_by_default | boolean | (part of dns object) Set to true to allow access to all zones except for those listed under zones_deny. Set to false to deny access to all zones by default except for those listed under zones_allow. |
| zones_allow | array of strings | (part of dns object) List of specific zones to which the API key is allowed access. If zones_allow_by_default property is set to false, the zones listed next to the zones_allow property are the only zones accessible to the API key. |
| zones_deny | array of strings | (part of dns object) List of specific zones to which the API key is denied access. If zones_allow_by_default property is set to true, the zones listed next to the zones_deny property are the only zones not accessible to the API key. |
| records_allow | array of objects | (part of dns object) Array of specific record to which the API key is allowed access. |
| records_deny | array of objects | (part of dns object) Array of specific record to which the API key is denied access. |
| zone | string | (Required; part of records_allow and/or records_deny objects) Name of the zone to which the record belongs. |
| domain | string | (Required; part of records_allow and/or records_deny objects) Domain name associated with the record. |
| include_subdomains | boolean | (Required; part of records_allow and/or records_deny objects) If a domain is specified, set to "true" to apply the same permissions to all subdomains. |
| type | string | (Required; part of records_allow and/or records_deny objects) Type of record to which you are allowing or denying access. |
| ipam | object | (part of permissions object) Group of IPAM-related permissions. |
| manage_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the API key to manage IPAM settings. |
| view_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the API key to view IPAM settings. |
| tags_allow | array of objects | (part of ipam object) List of IPAM tag permission specifiers used to grant access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of IPAM tag permission specifiers used to deny access for the API key to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the API key will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| monitoring | object | (part of permissions object) Group of monitoring-related permissions. |
| manage_lists | boolean | (part of monitoring object) Allows (or prevents, if false) the API key to create or modify notification lists. |
| manage_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the API key to create or modify monitoring jobs. |
| view_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the API key to view monitoring jobs. |
| security | object | (part of permissions object) Group of security-related permissions. |
| manage_global_2fa | boolean | (part of security object) Allows (or prevents, if false) the API key to manage global two-factor authentication (2FA) settings. |
| manage_active_directory | boolean | (part of security object) Allows (or prevents, if false) the API key to manage Active Directory settings. (DDI only) |
| manage_kerberos | boolean | (part of security object) Allows (or prevents, if false) the API key to manage Kerberos settings. (DDI only) |
| manage_ddns | boolean | (part of security object) Allows (or prevents, if false) the API key to manage dynamic DNS (DDNS) settings. (DDI only) |
| service | object | (part of permissions object) Group of DDI service-related permissions. (DDI only) |
| view_config | boolean | (part of service object) Allows (or prevents, if false) the API key to view DDI service (container/node) configurations. (DDI only) |
| manage_config | boolean | (part of service object) Allows (or prevents, if false) the API key to modify DDI service (container/node) configurations. (DDI only) |
Example Request:
{
"ip_whitelist_strict": true,
"name": "string",
"key": "stringstringstringst",
"ip_whitelist": [
"strings"
],
"last_access": null,
"teams": [
"50eb9d77830f784f98b0dd59"
],
"id": "string",
"permissions": {
"account": {
"manage_account_settings": true,
"manage_teams": true,
"manage_users": true,
"manage_apikeys": true,
"manage_ip_whitelist": true,
"view_activity_log": true,
"manage_payment_methods": true,
"manage_plan": true,
"view_invoices": true,
"manage_auth_tags": true,
"manage_service": true,
"view_service": true
},
"data": {
"manage_datasources": true,
"manage_datafeeds": true,
"push_to_datafeeds": true
},
"dhcp": {
"manage_dhcp": true,
"view_dhcp": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"dns": {
"manage_zones": true,
"view_zones": true,
"zones_allow_by_default": true,
"zones_allow": [
"foo.bar.com"
],
"zones_deny": [
"foo.bar.com"
],
"records_allow": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
],
"records_deny": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
]
},
"ipam": {
"manage_ipam": true,
"view_ipam": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"monitoring": {
"manage_lists": true,
"manage_jobs": true,
"view_jobs": true
},
"security": {
"manage_global_2fa": true,
"manage_active_directory": true,
"manage_kerberos": true,
"manage_ddns": true
},
"service": {
"view_config": true,
"manage_config": true
}
}
}
Example Response:
{
"ip_whitelist_strict": true,
"name": "string",
"key": "stringstringstringst",
"ip_whitelist": [
"strings"
],
"last_access": null,
"teams": [
"50eb9d77830f784f98b0dd59"
],
"id": "string",
"permissions": {
"account": {
"manage_account_settings": true,
"manage_teams": true,
"manage_users": true,
"manage_apikeys": true,
"manage_ip_whitelist": true,
"view_activity_log": true,
"manage_payment_methods": true,
"manage_plan": true,
"view_invoices": true,
"manage_auth_tags": true,
"manage_service": true,
"view_service": true
},
"data": {
"manage_datasources": true,
"manage_datafeeds": true,
"push_to_datafeeds": true
},
"dhcp": {
"manage_dhcp": true,
"view_dhcp": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"dns": {
"manage_zones": true,
"view_zones": true,
"zones_allow_by_default": true,
"zones_allow": [
"foo.bar.com"
],
"zones_deny": [
"foo.bar.com"
],
"records_allow": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
],
"records_deny": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
]
},
"ipam": {
"manage_ipam": true,
"view_ipam": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"monitoring": {
"manage_lists": true,
"manage_jobs": true,
"view_jobs": true
},
"security": {
"manage_global_2fa": true,
"manage_active_directory": true,
"manage_kerberos": true,
"manage_ddns": true
},
"service": {
"view_config": true,
"manage_config": true
}
}
}
DELETE /v1/account/apikeys/:keyid
DELETEDelete an API key
Deletes an API key specified in the URL path by its unique key ID. 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.
Path Parameters:
| keyID | string | Unique identifier for the API key. |
Copy CodeDeletes the API key
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/apikeys/:keyid
Team
GET /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.
Copy CodeReturns a list of teams
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/teams
Example Response:
[
{
"id": "50eb9d77830f784f98b0dd59",
"name": "string",
"permissions": {
"account": {
"manage_account_settings": true,
"manage_teams": true,
"manage_users": true,
"manage_apikeys": true,
"manage_ip_whitelist": true,
"view_activity_log": true,
"manage_payment_methods": true,
"manage_plan": true,
"view_invoices": true,
"manage_auth_tags": true,
"manage_service": true,
"view_service": true
},
"data": {
"manage_datasources": true,
"manage_datafeeds": true,
"push_to_datafeeds": true
},
"dhcp": {
"manage_dhcp": true,
"view_dhcp": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"dns": {
"manage_zones": true,
"view_zones": true,
"zones_allow_by_default": true,
"zones_allow": [
"foo.bar.com"
],
"zones_deny": [
"foo.bar.com"
],
"records_allow": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
],
"records_deny": [
{
"zone": "foo.bar.com",
"domain": "*.foo.bar.com",
"include_subdomains": true,
"type": "string"
}
]
},
"ipam": {
"manage_ipam": true,
"view_ipam": true,
"tags_allow": [
{
"name": "string",
"value": "string"
}
],
"tags_deny": [
{
"name": "string",
"value": "string"
}
]
},
"monitoring": {
"manage_lists": true,
"manage_jobs": true,
"view_jobs": true
},
"security": {
"manage_global_2fa": true,
"manage_active_directory": true,
"manage_kerberos": true,
"manage_ddns": true
},
"service": {
"view_config": true,
"manage_config": true
}
},
"ip_whitelist": [
{
"id": "string",
"name": "string",
"values": [
"string"
]
}
]
}
]
GET /v1/account/teams/:teamid
GETView team details
Returns configuration settings including permissions for the team specified in the URL path by its unique team ID.
Path Parameters:
| teamID | string | Unique identifier for the team |
Copy CodeReturns details for the team
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/teams/:teamid
Example Response:
{
"id": "5d839a45a38fef004eb22f25",
"ip_whitelist": [],
"name": "Test team",
"permissions": {
"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,
"manage_ip_whitelist": false
},
"data": {
"manage_datafeeds": false,
"manage_datasources": false,
"push_to_datafeeds": false
},
"dns": {
"zones_allow": [
"example.com"
],
"manage_zones": false,
"zones_allow_by_default": false,
"view_zones": true
},
"security": {
"manage_global_2fa": false
}
}
}
PUT /v1/account/teams
PUTCreate a new team
Creates a new team within the current NS1 account. After creating the team, you can associate users and API keys with this team by adding the team ID to the team property within the user and API key objects. All users and API keys associated with the team will inherit the permissions set at the team level and all permission settings applied to the individual user or key are ignored.
Important note about API key security: NS1 recommends restricting access to your API key and reducing permissions only to include what the application requires. Keep your API key secret. If it is compromised, delete the API key immediately. Restrict access to this key by applying IP addresses or CIDR blocks in the ip_whitelist property. In contrast to the user and API key objects, teams support names on the 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 Body Parameters:
| name | string | Name for the team |
| ip_whitelist | array of objects | Array of IP addresses objects to which to grant the team access. Each object includes an id (string), name (string), and values (array of strings) associated with each "allow" list. |
| permissions | object | All supported permissions |
| account | object | (part of permissions object) Group of account-related permissions. |
| manage_account_settings | boolean | (part of account object) Allows (or prevents, if false) the team to manage account settings. |
| manage_teams | boolean | (part of account object) Allows (or prevents, if false) the team to create or update teams. |
| manage_users | boolean | (part of account object) Allows (or prevents, if false) the team to create or update users. |
| manage_apikeys | boolean | (part of account object) Allows (or prevents, if false) the team to create or update API keys. |
| manage_ip_whitelist | boolean | (part of account object) Allows (or prevents, if false) the team to create or update IP "allow" lists. |
| view_activity_log | boolean | (part of account object) Allows (or prevents, if false) the team to view the account activity log. |
| manage_payment_methods | boolean | (part of account object) Allows (or prevents, if false) the team to manage account payment methods. |
| view_invoices | boolean | (part of account object) Allows (or prevents, if false) the team to view account invoices. |
| manage_auth_tags | boolean | (part of account object) Allows (or prevents, if false) the team to create and edit authorization of ('auth:') tags. Auth tags determine access controls to view or manage resources. Auth tags control access, so the team must also have the 'manage_auth_keys' permission set to true. |
| manage_service | boolean | (part of account object) Allows (or prevents, if false) the team to create and modify services. (DDI only) |
| view_service | boolean | (part of account object) Allows (or prevents, if false) the team to view services. (DDI only) |
| data | object | (part of permissions object) Group of data-related permissions. |
| manage_datasources | boolean | (part of data object) Allows (or prevents, if false) the team to create and modify data sources. |
| manage_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the team to create and modify data feeds. |
| push_to_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the team to push data to NS1 data feeds. |
| dhcp | object | (part of permissions object) Group of DHCP-related permissions. |
| manage_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the team to manage DHCP configuration settings. |
| view_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the team to view DHCP configuration settings. |
| tags_allow | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to grant access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to deny access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| dns | object | (part of permissions object) Group of DNS-related permissions. |
| manage_zones | boolean | (part of dns object) Allows (or prevents, if false) the team to create or modify zones. |
| view_zones | boolean | (part of dns object) Allows (or prevents, if false) the team to view zones. |
| zones_allow_by_default | boolean | (part of dns object) Set to true to allow access to all zones except for those listed under zones_deny. Set to false to deny access to all zones by default except for those listed under zones_allow. |
| zones_allow | array of strings | (part of dns object) List of specific zones to which the API key is allowed access. If zones_allow_by_default property is set to false, the zones listed next to the zones_allow property are the only zones accessible to the team. |
| zones_deny | array of strings | (part of dns object) List of specific zones to which the team is denied access. If zones_allow_by_default property is set to true, the zones listed next to the zones_deny property are the only zones not accessible to the team. |
| records_allow | array of objects | (part of dns object) Array of specific record to which the team is allowed access. |
| records_deny | array of objects | (part of dns object) Array of specific record to which the team is denied access. |
| zone | string | (Required; part of records_allow and/or records_deny objects) Name of the zone to which the record belongs. |
| domain | string | (Required; part of records_allow and/or records_deny objects) Domain name associated with the record. |
| include_subdomains | boolean | (Required; part of records_allow and/or records_deny objects) If a domain is specified, set to "true" to apply the same permissions to all subdomains. |
| type | string | (Required; part of records_allow and/or records_deny objects) Type of record to which you are allowing or denying access. |
| ipam | object | (part of permissions object) Group of IPAM-related permissions. |
| manage_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the team to manage IPAM settings. |
| view_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the team to view IPAM settings. |
| tags_allow | array of objects | (part of ipam object) List of IPAM tag permission specifiers used to grant access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of IPAM tag permission specifiers used to deny access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| monitoring | object | (part of permissions object) Group of monitoring-related permissions. |
| manage_lists | boolean | (part of monitoring object) Allows (or prevents, if false) the team to create or modify notification lists. |
| manage_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the team to create or modify monitoring jobs. |
| view_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the team to view monitoring jobs. |
| security | object | (part of permissions object) Group of security-related permissions. |
| manage_global_2fa | boolean | (part of security object) Allows (or prevents, if false) the team to manage global two-factor authentication (2FA) settings. |
| manage_active_directory | boolean | (part of security object) Allows (or prevents, if false) the team to manage Active Directory settings. (DDI only) |
| manage_kerberos | boolean | (part of security object) Allows (or prevents, if false) the team to manage Kerberos settings. (DDI only) |
| manage_ddns | boolean | (part of security object) Allows (or prevents, if false) the team to manage dynamic DNS (DDNS) settings. (DDI only) |
| service | object | (part of permissions object) Group of DDI service-related permissions. (DDI only) |
| view_config | boolean | (part of service object) Allows (or prevents, if false) the team to view DDI service (container/node) configurations. (DDI only) |
| manage_config | boolean | (part of service object) Allows (or prevents, if false) the team to modify DDI service (container/node) configurations. (DDI only) |
Example Request:
{
"name": "Test team",
"ip_whitelist": [],
"permissions": {
"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,
"manage_ip_whitelist": false
},
"data": {
"push_to_datafeeds": false,
"manage_datafeeds": false,
"manage_datasources": false
},
"dns": {
"zones_allow": [
"example.com"
],
"zones_allow_by_default": false,
"manage_zones": false,
"view_zones": true
},
"security": {
"manage_global_2fa": false
}
}
}
Example Response:
{
"id": "5d839a45a38fef004eb22f25",
"ip_whitelist": [],
"name": "Test team",
"permissions": {
"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,
"manage_ip_whitelist": false
},
"data": {
"manage_datafeeds": false,
"manage_datasources": false,
"push_to_datafeeds": false
},
"dns": {
"zones_allow": [
"example.com"
],
"manage_zones": false,
"zones_allow_by_default": false,
"view_zones": true
},
"security": {
"manage_global_2fa": false
}
}
}
POST /v1/account/teams/:teamid
POSTEdit team details
Modifies a new team within the current NS1 account.
Important note about API key security: NS1 recommends restricting access to your API key and reducing permissions only to include what the application requires. Keep your API key secret. If it is compromised, delete the API key immediately. Restrict access to this key by applying IP addresses or CIDR blocks in the ip_whitelist property. In contrast to the user and API key objects, teams support names on the 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']} ]).
Path Parameters:
| teamid | string | (Required) Unique identifier for the team you are editing. |
Request Body Parameters:
| name | string | Name for the team |
| ip_whitelist | array of objects | Array of IP addresses objects to which to grant the team access. Each object includes an id (string), name (string), and values (array of strings) associated with each "allow" list. |
| permissions | object | All supported permissions |
| account | object | (part of permissions object) Group of account-related permissions. |
| manage_account_settings | boolean | (part of account object) Allows (or prevents, if false) the team to manage account settings. |
| manage_teams | boolean | (part of account object) Allows (or prevents, if false) the team to create or update teams. |
| manage_users | boolean | (part of account object) Allows (or prevents, if false) the team to create or update users. |
| manage_apikeys | boolean | (part of account object) Allows (or prevents, if false) the team to create or update API keys. |
| manage_ip_whitelist | boolean | (part of account object) Allows (or prevents, if false) the team to create or update IP "allow" lists. |
| view_activity_log | boolean | (part of account object) Allows (or prevents, if false) the team to view the account activity log. |
| manage_payment_methods | boolean | (part of account object) Allows (or prevents, if false) the team to manage account payment methods. |
| view_invoices | boolean | (part of account object) Allows (or prevents, if false) the team to view account invoices. |
| manage_auth_tags | boolean | (part of account object) Allows (or prevents, if false) the team to create and edit authorization of ('auth:') tags. Auth tags determine access controls to view or manage resources. Auth tags control access, so the team must also have the 'manage_auth_keys' permission set to true. |
| manage_service | boolean | (part of account object) Allows (or prevents, if false) the team to create and modify services. (DDI only) |
| view_service | boolean | (part of account object) Allows (or prevents, if false) the team to view services. (DDI only) |
| data | object | (part of permissions object) Group of data-related permissions. |
| manage_datasources | boolean | (part of data object) Allows (or prevents, if false) the team to create and modify data sources. |
| manage_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the team to create and modify data feeds. |
| push_to_datafeeds | boolean | (part of data object) Allows (or prevents, if false) the team to push data to NS1 data feeds. |
| dhcp | object | (part of permissions object) Group of DHCP-related permissions. |
| manage_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the team to manage DHCP configuration settings. |
| view_dhcp | boolean | (part of dhcp object) Allows (or prevents, if false) the team to view DHCP configuration settings. |
| tags_allow | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to grant access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of DHCP tag permission specifiers used to deny access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| dns | object | (part of permissions object) Group of DNS-related permissions. |
| manage_zones | boolean | (part of dns object) Allows (or prevents, if false) the team to create or modify zones. |
| view_zones | boolean | (part of dns object) Allows (or prevents, if false) the team to view zones. |
| zones_allow_by_default | boolean | (part of dns object) Set to true to allow access to all zones except for those listed under zones_deny. Set to false to deny access to all zones by default except for those listed under zones_allow. |
| zones_allow | array of strings | (part of dns object) List of specific zones to which the API key is allowed access. If zones_allow_by_default property is set to false, the zones listed next to the zones_allow property are the only zones accessible to the team. |
| zones_deny | array of strings | (part of dns object) List of specific zones to which the team is denied access. If zones_allow_by_default property is set to true, the zones listed next to the zones_deny property are the only zones not accessible to the team. |
| records_allow | array of objects | (part of dns object) Array of specific record to which the team is allowed access. |
| records_deny | array of objects | (part of dns object) Array of specific record to which the team is denied access. |
| zone | string | (Required; part of records_allow and/or records_deny objects) Name of the zone to which the record belongs. |
| domain | string | (Required; part of records_allow and/or records_deny objects) Domain name associated with the record. |
| include_subdomains | boolean | (Required; part of records_allow and/or records_deny objects) If a domain is specified, set to "true" to apply the same permissions to all subdomains. |
| type | string | (Required; part of records_allow and/or records_deny objects) Type of record to which you are allowing or denying access. |
| ipam | object | (part of permissions object) Group of IPAM-related permissions. |
| manage_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the team to manage IPAM settings. |
| view_ipam | boolean | (part of ipam object) Allows (or prevents, if false) the team to view IPAM settings. |
| tags_allow | array of objects | (part of ipam object) List of IPAM tag permission specifiers used to grant access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will have access to those objects with the matching name. If both a name and value are provided, both must match in order to grant access. |
| tags_deny | array of objects | (part of dhcp object) List of IPAM tag permission specifiers used to deny access for the team to specific objects containing the same tag. Each tag includes a name (required) and a value (optional). If just a name is provided, the team will be denied access to those objects with the matching name. If both a name and value are provided, both must match in order to deny access. |
| monitoring | object | (part of permissions object) Group of monitoring-related permissions. |
| manage_lists | boolean | (part of monitoring object) Allows (or prevents, if false) the team to create or modify notification lists. |
| manage_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the team to create or modify monitoring jobs. |
| view_jobs | boolean | (part of monitoring object) Allows (or prevents, if false) the team to view monitoring jobs. |
| security | object | (part of permissions object) Group of security-related permissions. |
| manage_global_2fa | boolean | (part of security object) Allows (or prevents, if false) the team to manage global two-factor authentication (2FA) settings. |
| manage_active_directory | boolean | (part of security object) Allows (or prevents, if false) the team to manage Active Directory settings. (DDI only) |
| manage_kerberos | boolean | (part of security object) Allows (or prevents, if false) the team to manage Kerberos settings. (DDI only) |
| manage_ddns | boolean | (part of security object) Allows (or prevents, if false) the team to manage dynamic DNS (DDNS) settings. (DDI only) |
| service | object | (part of permissions object) Group of DDI service-related permissions. (DDI only) |
| view_config | boolean | (part of service object) Allows (or prevents, if false) the team to view DDI service (container/node) configurations. (DDI only) |
| manage_config | boolean | (part of service object) Allows (or prevents, if false) the team to modify DDI service (container/node) configurations. (DDI only) |
Example Request:
{
"name": "Test team",
"ip_whitelist": [],
"permissions": {
"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,
"manage_ip_whitelist": false
},
"data": {
"push_to_datafeeds": false,
"manage_datafeeds": false,
"manage_datasources": false
},
"dns": {
"zones_allow": [
"example.com"
],
"zones_allow_by_default": false,
"manage_zones": false,
"view_zones": true
},
"security": {
"manage_global_2fa": false
}
}
}
Example Response:
{
"id": "5d839a45a38fef004eb22f25",
"ip_whitelist": [],
"name": "Test team",
"permissions": {
"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,
"manage_ip_whitelist": false
},
"data": {
"manage_datafeeds": false,
"manage_datasources": false,
"push_to_datafeeds": false
},
"dns": {
"zones_allow": [
"example.com"
],
"manage_zones": false,
"zones_allow_by_default": false,
"view_zones": true
},
"security": {
"manage_global_2fa": false
}
}
}
DELETE /v1/account/teams/:teamID
DELETEDelete a team
Deletes a team. Any associated users or API keys will be removed from the team and inherit the permissions of any other teams with which they are associated. If they do not belong to any other teams, they will retain the permissions from this team.
There is no response other than the HTTP status code.
Path Parameters:
| teamID | string | (Required) Unique identifier for the team you are deleting |
Copy CodeDeletes a team
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/teams/:teamID
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 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
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
POSTEdit an IP whitelist
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
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 /v1/account/plantypes
GETView Managed DNS plan type
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 [email protected].
Request URL:
https://api.nsone.net/v1/account/plantypes
Example Response:
[
{
"overage_order": "ascending",
"overages": {
"static": {
"queries": "2",
"records": "1"
},
"intelligent": {
"queries": "6",
"records": "1"
},
"dynamic": {
"queries": "4",
"records": "1"
}
},
"monthly_price": "0.00",
"discount": "0.00",
"discount_type": "percentage",
"included": {
"any": {
"queries": 1e+07,
"records": 50
},
"static": {
"queries": 0,
"records": 0
},
"intelligent": {
"queries": 0,
"records": 0
},
"dynamic": {
"queries": 0,
"records": 0
}
},
"recurring_cost": "0.00",
"access_charges": {
"static": "0.00",
"intelligent": "0.00",
"dynamic": "0.00"
},
"monitoring": {
"jobs": 2,
"frequency": 60,
"regions": 1
},
"type": "startup",
"period": "monthly"
},
{
"overage_order": "ascending",
"overages": {
"static": {
"queries": "0.75",
"records": "0.25"
},
"intelligent": {
"queries": "2",
"records": "0.25"
},
"dynamic": {
"queries": "1.25",
"records": "0.25"
}
},
"monthly_price": "50.00",
"discount": "0.00",
"discount_type": "percentage",
"included": {
"any": {
"queries": 2.5e+07,
"records": 250
},
"static": {
"queries": 0,
"records": 0
},
"intelligent": {
"queries": 0,
"records": 0
},
"dynamic": {
"queries": 0,
"records": 0
}
},
"recurring_cost": "50.00",
"access_charges": {
"static": "0.00",
"intelligent": "0.00",
"dynamic": "0.00"
},
"monitoring": {
"jobs": 25,
"frequency": 20,
"regions": 3
},
"type": "business",
"period": "monthly"
},
{
"overage_order": "ascending",
"overages": {
"static": {
"queries": "0.75",
"records": "0.25"
},
"intelligent": {
"queries": "2",
"records": "0.25"
},
"dynamic": {
"queries": "1.25",
"records": "0.25"
}
},
"monthly_price": "47.50",
"discount": "0.00",
"discount_type": "percentage",
"included": {
"any": {
"queries": 2.5e+07,
"records": 250
},
"static": {
"queries": 0,
"records": 0
},
"intelligent": {
"queries": 0,
"records": 0
},
"dynamic": {
"queries": 0,
"records": 0
}
},
"recurring_cost": "47.50",
"access_charges": {
"static": "0.00",
"intelligent": "0.00",
"dynamic": "0.00"
},
"monitoring": {
"jobs": 25,
"frequency": 20,
"regions": 3
},
"type": "business",
"period": "quarterly"
},
...
]
GET /v1/account/plan
GETView Managed DNS 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 /v1/account/plan
POSTChange your Managed DNS plan type
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 /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 /v1/account/invoices/{invoiceID}
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').
| Parameter | Type | Description | Required? |
| invoiceid | String | Example: '727' | Yes |
| authtoken | String | Example: d4a2080c926b85c9936908852454cb181249622a | No |
Request URL:
https://api.nsone.net/v1/account/invoices/:invoiceid[?authtoken=21900a196f...]
Example URL:
https://api.nsone.net/v1/account/invoices/727?authtoken=d4a2080c926b85c9936908852454cb181249622a
Example URL:
https://api.nsone.net/v1/account/invoices/invoiceid?authtoken=d4a2080c926b85c9936908852454cb181249622a
| Parameter | Type | Description | Required? |
| invoiceid | String | Example: '727' | Yes |
| authtoken | String | Example: d4a2080c926b85c9936908852454cb181249622a | No |
GET /v1/account/billataglance
GETView bill at a glance
Returns current usage and charges that will appear on the next invoice.
WARNING
Please note that the metrics shown do not reflect real-time data. Usage information is generated daily at 00:30 UTC.
Copy CodeReturns usage and charges based on the last instance of 00:30 UTC
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/billataglance
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 /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 /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 /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 body parameters:
| type | string | Payment type (e.g., creditcard) |
| default | boolean | Indicates whether or not this is the default payment method |
| cc_number | string | Credit card numbers (between 12-19 digits) |
| cc_expire_month | integer | Month of the credit card expiration date |
| cc_expire_year | integer | Year of the credit card expiration date |
| cc_cvv2 | string | Card verification code (between 3-4 characters) |
| firstname | string | First name on with the credit card |
| lastname | string | Last name on the credit card |
| company | string | Company associated with the payment method (if applicable) |
| phone | string | Phone number associated with the payment method |
| address | object | Address details associated with the payment method |
| street | string | Street address associated with the payment method |
| city | string | City associated with the payment method address |
| state | string | State associated with the payment method address |
| postalcode | string | Postal code associated with the payment method address |
| country | string | Country associated with the payment method address |
Copy CodeAdds a new payment method
curl -X PUT -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/account/paymentmethods
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 /v1/account/activity
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.
Query Parameters:
| Parameter | Type | Description |
| limit | integer | Maximum number of entries to return |
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range. |
| resource_type | string | Type of resource |
| user | string | Username or an API key ID |
| resource_id | string | Unique identifier for a resource |
| export | string | The file type of the report that should be generated. Can be one of the following file types: json, xml, csv, pdf, xslx, or html. |
Copy CodeExports the activity log in PDF format
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/account/activity?export=pdf
Request URL:
https://api.nsone.net/v1/account/activity
Example Response:
[
{
"resource_type": "zonefile",
"user_id": "myuser",
"resource_id": "52276047830f787e2ff88d4c",
"timestamp": 1378312263,
"user_type": "user",
"action": "create",
"resource": {
"id": "52276047830f787e2ff88d4c",
"hostmaster": "[email protected]",
"meta": {},
"nx_ttl": 60,
"retry": 3600,
"zone": "myzone.net",
"warnings": [],
"refresh": 21600,
"expiry": 1209600,
"records": [
{
"id": "52276047830f787e2ff88d4f",
"type": "NS",
"tier": 1,
"short_answers": [
"dns1.p03.nsone.net",
"dns2.p03.nsone.net",
"dns3.p03.nsone.net",
"dns4.p03.nsone.net"
],
"domain": "myzone.net"
},
{
"id": "52276047830f787e2ff88d53",
"type": "A",
"tier": 1,
"short_answers": [
"1.1.1.1",
"2.2.2.2"
],
"domain": "*.myzone.net"
}
],
"dns_servers": [
"dns1.p03.nsone.net",
"dns2.p03.nsone.net",
"dns3.p03.nsone.net",
"dns4.p03.nsone.net"
],
"networks": [0],
"network_pools": ["p03"]
},
"user_name": "My User",
"id": "52276047830f787e2ff88d59"
},
{
"resource_type": "user",
"user_id": "myuser",
"resource_id": "olduser",
"timestamp": 1378312122,
"user_type": "user",
"action": "delete",
"resource": {
"permissions": {
"dns": {
"zones_allow_by_default": true,
"view_zones": true,
"zones_deny": [],
"manage_zones": true,
"zones_allow": []
},
"data": {
"manage_datafeeds": true,
"manage_datasources": true,
"push_to_datafeeds": true
},
"account": {
"manage_payment_methods": true,
"manage_teams": true,
"manage_apikeys": true,
"manage_account_settings": true,
"view_activity_log": true,
"view_invoices": true,
"manage_users": true,
"manage_plan": true
},
"monitoring": {
"manage_lists": false,
"manage_jobs": false,
"view_jobs": false
}
},
"email": "[email protected]",
"last_access": null,
"notify": {
"billing": true
},
"name": "Old User",
"username": "olduser"
},
"user_name": "My User",
"id": "52275fba830f787e2ff88d42"
},
...
]
Zones & Records
To learn more about managing NS1 zones and records, refer to the NS1 Help Center.
Zones
GET /v1/zones
GET List all zones
Returns a list of all active DNS zones along with 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
Example Response:
[
{
"dns_servers": [
"string"
],
"expiry": 0,
"primary_master": "string",
"hostmaster": "string",
"id": "string",
"meta": {
"asn": [
"string"
],
"ca_province": [
"string"
],
"connections": 0,
"country": [
"string"
],
"georegion": [
"string"
],
"high_watermark": 0,
"ip_prefixes": [
"string"
],
"latitude": 0,
"loadAvg": 0,
"longitude": 0,
"low_watermark": 0,
"note": "string",
"priority": 0,
"pulsar": "string",
"requests": 0,
"up": true,
"us_state": [
"string"
],
"weight": 0
},
"network_pools": [
"string"
],
"networks": [
0
],
"nx_ttl": 0,
"primary": {
"enabled": true,
"secondaries": [
{
"ip": "string",
"networks": [
0
],
"notify": true,
"port": 0
}
]
},
"records": [
{
"domain": "string",
"id": "string",
"short_answers": [
"string"
],
"tier": 0,
"ttl": 0,
"type": "string"
}
],
"refresh": 0,
"retry": 0,
"ttl": 0,
"zone": "string",
"views": [
"string"
],
"local_tags": [
"string"
],
"tags": {}
}
]
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.
Path Parameters:
| Parameter | Type | Description |
| zone | string | (Required) FQDN of the zone. |
Example Response:
{
"dns_servers": [
"string"
],
"expiry": 0,
"primary_master": "string",
"hostmaster": "string",
"id": "string",
"meta": {
"asn": [
"string"
],
"ca_province": [
"string"
],
"connections": 0,
"country": [
"string"
],
"georegion": [
"string"
],
"high_watermark": 0,
"ip_prefixes": [
"string"
],
"latitude": 0,
"loadAvg": 0,
"longitude": 0,
"low_watermark": 0,
"note": "string",
"priority": 0,
"pulsar": "string",
"requests": 0,
"up": true,
"us_state": [
"string"
],
"weight": 0
},
"network_pools": [
"string"
],
"networks": [
0
],
"nx_ttl": 0,
"primary": {
"enabled": true,
"secondaries": [
{
"ip": "string",
"networks": [
0
],
"notify": true,
"port": 0
}
]
},
"records": [
{
"domain": "string",
"id": "string",
"short_answers": [
"string"
],
"tier": 0,
"ttl": 0,
"type": "string"
}
],
"refresh": 0,
"retry": 0,
"ttl": 0,
"zone": "string",
"views": [
"string"
],
"local_tags": [
"string"
],
"tags": {}
}
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.
Linked zones
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.
Secondary zones
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.
Zone replication
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 the 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.
Path parameters:
| zone | string | (Required) FQDN of the zone you are creating. Note for DDI users: You may have multiple zone names associated with the same zone (FQDN). |
Query parameters:
| limit | integer | Maximum number of entries to return in the response. |
| after | string | The name of the zone after which to return results. In other words, only the zones listed after the zone entered here will appear in the response. Note that zones are listed alphabetically. Also, note that if you did not apply a unique "zone name" associated with the zone, the zone name defaults to the zone FQDN. |
Request body parameters:
| name | string | (DDI only) Vanity name for the zone used for associating the zone with DNS views. If left undefined, the zone name defaults to the zone FQDN. You can have multiple zone names associated with the same zone (FQDN). |
| views | string | (DDI only) Name of the DNS view(s) with which this zone is associated. |
| networks | array of integers | If you account has access to multiple DNS networks, you may pass a list of network IDs for which the zone should be made available. If not set, the zone is created in network 0 (primary NSONE Global Network). DNS servers will be selected and assigned across all the networks you specify. |
| expiry | integer | If refresh and Retry fail repeatedly, this is the time period after which the primary should be considered down and no longer authoritative for the given zone. |
| nx_ttl | integer | In the event that the DNS query results in an NXDOMAIN error, because the domain name does not exist (and this is also true for all names under it), or in an EBOT (aka NODATA) response, this is the length of time that the ‘negative’ answer should be cached for. |
| primary | object | Applied to support zone replication by third-party DNS servers. |
| enabled | boolean | (Required; part of the primary object) If true, AXFR queries (and optionally NOTIFY messages) will be enabled for the zone. |
| secondaries | array of objects | (Required if set to primary; part of the primary object) An array of objects to define secondary nodes |
| ip | string | (Included in the secondaries array) IPv4 address of the secondary zone. |
| notify | boolean | (Included in the secondaries array) If set to "true," NS1 will send NOTIFY messages to the secondary host upon zone changes. |
| port | integer | (Included in the secondaries array) The port on the host to send NOTIFY messages. Default is 53. |
| refresh | integer | The interval at which secondary DNS servers are set to refresh the zone file from the primary server. |
| retry | integer | The rate at which a secondary DNS servers will retry to refresh the zone file if the initial refresh failed. |
| ttl | integer | The interval at which the SOA record itself is refreshed. |
| tags | objects | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets/addresses. |
Copy CodeCreate a new DNS zone
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"{zoneFQDN}", "nx_ttl":60}' https://api.nsone.net/v1/zones/{zoneFQDN}
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/{zoneFQDN}
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}
Copy CodeCreate a zone with associated DNS views and networks (DDI only)
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "'{domain}'", "name": "'{zone_name}", "views": [{view_name}], "networks": [{network_ids}] }' https://{api.mycompany.net}/v1/zones/{zone-name}
Example Request:
{
"zone": "newzone.com",
"ttl&tuot;: 3600,
"nx_ttl": 60
}
Example Response:
{
"id": "52051b2c9f782d58bb4df41b",
"hostmaster": "[email protected]",
"ttl": 3600,
"nx_ttl": 60,
"retry": 7200,
"zone": "newzone.com",
"refresh": 43200,
"expiry": 1209600,
"dns_servers": [
"dns1.p06.nsone.net",z
"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": {}
}
Example Request:
{
"expiry": 0,
"hostmaster": "string",
"nx_ttl": 0,
"primary": {
"enabled": true,
"secondaries": [
{
"ip": "string",
"networks": [
0
],
"notify": true,
"port": 0
}
]
},
"refresh": 0,
"retry": 0,
"ttl": 0,
"zone": "string",
"local_tags": [
"string"
],
"tags": {}
}
Example Response:
{
"dns_servers": [
"string"
],
"expiry": 0,
"name": "string",
"link": "string",
"primary_master": "string",
"hostmaster": "string",
"id": "string",
"meta": {
"asn": [
"string"
],
"ca_province": [
"string"
],
"connections": 0,
"country": [
"string"
],
"georegion": [
"string"
],
"high_watermark": 0,
"ip_prefixes": [
"string"
],
"latitude": 0,
"loadAvg": 0,
"longitude": 0,
"low_watermark": 0,
"note": "string",
"priority": 0,
"pulsar": "string",
"requests": 0,
"up": true,
"us_state": [
"string"
],
"weight": 0
},
"network_pools": [
"string"
],
"networks": [
0
],
"nx_ttl": 0,
"serial": 0,
"primary": {
"enabled": true,
"secondaries": [
{
"ip": "string",
"networks": [
0
],
"notify": true,
"port": 0
}
]
},
"records": [
{
"domain": "string",
"zone": "string",
"tags": {
"property1": "string",
"property2": "string"
},
"link": "string",
"use_client_subnet": true,
"regions": {
"property1": "string",
"property2": "string"
},
"meta": {
"property1": "string",
"property2": "string"
},
"zone_name": "string",
"networks": [
0
],
"id": "string",
"short_answers": [
"string"
],
"tier": 0,
"ttl": 0,
"type": "string"
}
],
"refresh": 0,
"retry": 0,
"secondary": {
"status": "string",
"last_xfr": 0,
"primary_ip": "string",
"primary_port": 0,
"enabled": true,
"tsig": {
"enabled": true,
"hash": "string",
"name": "string",
"key": "string"
},
"other_ports": [
0
],
"other_ips": [
"string"
],
"expired": true
},
"ttl": 0,
"zone": "string",
"views": [
"string"
],
"local_tags": [
"string"
],
"tags": {
"property1": "string",
"property2": "string"
}
}
POST /v1/zones/:zone
POST Edit 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.
Path Parameters:
| zone | string | (Required) FQDN of the zone you are creating. Note for DDI users: You may have multiple zoneNames associated with the same zone (FQDN). |
Request Body Paramters:
| views | string | (DDI only) Name of the DNS view(s) with which this zone is associated. |
| networks | array of integers | If you account has access to multiple DNS networks, you may pass a list of network IDs for which the zone should be made available. If not set, the zone is created in network 0 (primary NSONE Global Network). DNS servers will be selected and assigned across all the networks you specify. |
| expiry | integer | If refresh and retry fail repeatedly, this is the time period after which the primary should be considered down and no longer authoritative for the given zone. |
| nx_ttl | integer | In the event that the DNS query results in an NXDOMAIN error, because the domain name does not exist (and this is also true for all names under it), or in an EBOT (aka NODATA) response, this is the length of time that the ‘negative’ answer should be cached for. |
| primary | object | Applied to support zone replication by third-party DNS servers. |
| enabled | boolean | (Required; part of the primary object) If true, AXFR queries (and optionally NOTIFY messages) will be enabled for the zone. |
| secondaries | array of objects | (Required if set to primary; part of the primary object) An array of objects to define secondary nodes |
| ip | string | (Included in the secondaries array) IPv4 address of the secondary zone. |
| notify | boolean | (Included in the secondaries array) If set to "true," NS1 will send NOTIFY messages to the secondary host upon zone changes. |
| port | integer | (Included in the secondaries array) The port on the host to send NOTIFY messages. Default is 53. |
| refresh | integer | The interval at which secondary DNS servers are set to refresh the zone file from the primary server. |
| retry | integer | The rate at which a secondary DNS servers will retry to refresh the zone file if the initial refresh failed. |
| ttl | integer | The interval at which the SOA record itself is refreshed. |
| tags | objects | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets/addresses. |
Copy CodeModifies the specified zone
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "expiry": 0, "hostmaster": "string", "nx_ttl": 0, "primary": { "enabled": true, "secondaries": [ { "ip": "string", "networks": [0],"notify": true, "port": 0 }]}, "refresh": 0, "retry": 0, "ttl": 0, "zone": "string", "local_tags": ["string"], "tags": {}}' https://{api.mycompany.net}/v1/zones/{zoneFQDN}
Copy CodeForces a refresh on a secondary zone
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/zones/{zoneFQDN}?refresh=true
Execute the command above on a secondary zone to force a refresh, overriding any refresh interval setting defined. Note: Do not include any data in the request body.
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:
{
"dns_servers": [
"string"
],
"expiry": 0,
"primary_master": "string",
"hostmaster": "string",
"id": "string",
"meta": {
"asn": [
"string"
],
"ca_province": [
"string"
],
"connections": 0,
"country": [
"string"
],
"georegion": [
"string"
],
"high_watermark": 0,
"ip_prefixes": [
"string"
],
"latitude": 0,
"loadAvg": 0,
"longitude": 0,
"low_watermark": 0,
"note": "string",
"priority": 0,
"pulsar": "string",
"requests": 0,
"up": true,
"us_state": [
"string"
],
"weight": 0
},
"network_pools": [
"string"
],
"networks": [
0
],
"nx_ttl": 0,
"primary": {
"enabled": true,
"secondaries": [
{
"ip": "string",
"networks": [
0
],
"notify": true,
"port": 0
}
]
},
"records": [
{
"domain": "string",
"id": "string",
"short_answers": [
"string"
],
"tier": 0,
"ttl": 0,
"type": "string"
}
],
"refresh": 10800,
"retry": 0,
"ttl": 0,
"zone": "string",
"views": [
"string"
],
"local_tags": [
"string"
],
"tags": {}
}
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 [email protected] -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": "[email protected]",
"meta": {},
"ttl": 3600,
"nx_ttl": 300,
"retry": 7200,
"zone": "newzone.com",
"warnings": [],
"refresh": 43200,
"expiry": 1209600,
"dns_servers": [
"dns1.p06.nsone.net",
"dns2.p06.nsone.net",
"dns3.p06.nsone.net",
"dns4.p06.nsone.net"
],
"networks": [0],
"network_pools": ["p06"],
"records": [
{
"id": "52052aa99f782d5b1a10a836",
"type": "NS",
"tier": 1,
"short_answers": [
"dns1.p06.nsone.net",
"dns2.p06.nsone.net",
"dns3.p06.nsone.net",
"dns4.p06.nsone.net"
],
"domain": "newzone.com"
},
{
"id": "52052aa99f782d5bcc10a847",
"type": "A",
"tier": 1,
"domain": "newzone.com",
"zone": "newzone.com",
"short_answers": [
"1.2.3.4"
]
},
{
"id": "52052aa99f78375bcc10a666",
"type": "A",
"tier": 1,
"domain": "www.newzone.com",
"zone": "newzone.com",
"short_answers": [
"1.2.3.4"
]
}
]
}
Example Response:
{
"sent": 1376070394,
"id": "zIbC9VfrnVtubXfJbM6a",
"type": "importzonefile",
"percent": 20,
"status": "Creating zone"
}
| 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": "[email protected]",
"meta": {},
"ttl": 3600,
"nx_ttl": 300,
"retry": 7200,
"zone": "newzone.com",
"warnings": [],
"refresh": 43200,
"expiry": 1209600,
"records": [
{
"id": "52052afa9f782d5b1a10a844",
"type": "NS",
"tier": 1,
"short_answers": [
"dns1.p01.nsone.net",
"dns2.p01.nsone.net",
"dns3.p01.nsone.net",
"dns4.p01.nsone.net"
],
"domain": "newzone.com"
},
{
"type": "A",
"feeds": [],
"tier": 1,
"domain": "newzone.com",
"zone": "newzone.com",
"answers": [
{
"id": "52052afa9f782d5b1a10a846",
"answer": [
"1.2.3.4"
]
}
],
"regions": {},
"meta": {},
"filters": [],
"ttl": 300
},
{
"type": "A",
"feeds": [],
"tier": 1,
"domain": "www.newzone.com",
"zone": "newzone.com",
"answers": [
{
"id": "52052afa9f782d5b1a10a848",
"answer": [
"1.2.3.4"
]
}
],
"regions": {},
"meta": {},
"filters": [],
"ttl": 300
}
],
"dns_servers": [
"dns1.p01.nsone.net",
"dns2.p01.nsone.net",
"dns3.p01.nsone.net",
"dns4.p01.nsone.net"
],
"networks": [0],
"network_pools": ["p01"]
},
"percent": 100,
"status": "Created zone and 3 records",
}
| 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
NOTE: NS1 Enterprise DDI and NS1 Connect users should use the new and improved zone/record search endpoints below. Refer to "Search for DNS zones" and "Search for DNS 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.
Query parameters:
| q | string | Search query |
| max | integer | Maximum number of search results to display |
| type | string | Filters search results by type. Enum: "zone", "record", "all", "answers" |
| expand | string | Expands contents of search results. Enum: false, "f", true, or "t" |
Request URL:
https://api.nsone.net/v1/search?q=[querystring][&max=10][&type=all]
Example URL:
https://api.nsone.net/v1/search?q=example
Example Response:
[
{
"zone": "example.com"
},
{
"zone": "example.com",
"type": "NS",
"domain": "example.com"
},
{
"zone": "example.com",
"type": "MX",
"domain": "mail.example.com"
},
{
"zone": "example.com",
"type": "A",
"domain": "www.example.com"
}
]
GET /v1/dns/zone/search
GET Search for DNS zones (DDI only)
Returns a list of all zones based on any specified filters.
Query Parameters:
| fqdn | string | Filter by fully-qualified domain name (FQDN) |
| tags | array of strings | Filter by specified keys or key-value pairs. For example, tag=key, tag=key*, tag=key=>value, tag=key*=>value, tag=key=>value*, or tag=key*=>value* Text can be prefixed and/or suffixed with * for pattern matching. Other * characters in the answer should be escaped. |
| limit | integer | Limits the number of results returned. Default is 20. |
| next | string | If your total number of zones exceeds the limit set, a next value is returned in the response. Apply the next value when searching for the next batch of zone results. |
| expand | string | Option to include associated records in the search results. Enum: "false" (default), "f", "true", "t" |
Copy CodeReturns a list of all zones
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dns/zone/search
Request URL:
https://api.nsone.net/v1/dns/zone/search
Request URL:
https://api.nsone.net/v1/dns/zone/search?expand=true
Example Response:
{
"total_results": 1,
"next": "next",
"limit": 1,
"results": [
{
"fqdn": "example.com",
"handle": "example.com"
}
]
}
Example Response:
{
"total_results": 1,
"next": "next",
"limit": 1,
"results": [
{
"fqdn": "example.com",
"handle": "example.com",
"network_pools": [
"p00"
],
"networks": [
1
],
"primary": {
"enabled": true,
"secondaries": [
{
"ip": "127.0.0.1",
"notify": true,
"port": 53
}
]
},
"record": [
"dns1.p00.nsone.net",
"hostmaster.example.net.",
6,
43200,
7200,
1209600,
3600
],
"secondary": {
"enabled": false,
"expired": false,
"last_try": 1616692983,
"last_xfr": 1616692983,
"other_ips": [],
"other_ports": [],
"primary_ip": "127.0.0.1",
"primary_port": 53,
"status": "ok"
},
"ttl": 3600,
"views": []
}
]
}
GET /v1/dns/record/search
GET Search for DNS records (DDI only)
Returns a list of all zones based on any specified filters.
Query Parameters:
| domain | string | Filter by domain. |
| type | string | Filter by record type. |
| answers | string | Filter by answers. Text can be prefixed and/or suffixed with * for pattern matching. Other * characters in the answer should be escaped. |
| tags | array of strings | Filter by specified keys or key-value pairs. For example, tag=key, tag=key*, tag=key=>value, tag=key*=>value, tag=key=>value*, or tag=key*=>value* |
| limit | integer | Limits the number of results returned. Default is 20. |
| next | string | If your total number of records exceeds the limit set, a next value is returned in the response. Apply the next value when searching for the next batch of record results. |
| expand | string | Option to include record details in the search results. Enum: "false" (default), "f", "true", "t" |
Copy CodeReturns all records
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dns/record/search
Request URL:
https://api.nsone.net/v1/dns/record/search
Request URL:
https://api.nsone.net/v1/dns/record/search?expand=true
Example Response:
{
"total_results": 1,
"next": "next",
"limit": 1,
"results": [
{
"domain": "www.example.com",
"type": "A",
"zone_fqdn": "example.com",
"zone_handle": "example.com"
}
]
}
Example Response:
{
"total_results": 1,
"next": "next",
"limit": 1,
"results": [
{
"answers": [
{
"answer": [
"192.0.2.1"
],
"id": "605cc6f6b407da12cd986c9f"
}
],
"domain": "www.example.com",
"id": "605cc6f6b407da12cd986ca0",
"meta": {},
"networks": [
1
],
"regions": {},
"tags": {
"tag0": "value0",
"tag1": "value1",
"tag2": "value2",
"tag3": "value3",
"tag4": "value4"
},
"tier": 1,
"ttl": 3600,
"type": "A",
"zone_fqdn": "example.com",
"zone_handle": "example.com",
"use_client_subnet": false
}
]
}
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 [email protected] 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": "[email protected]",
"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_name}
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":"[email protected]","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"}
Records
GET /v1/zones/:zone/:domain/:type
GETView record 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.
Path Parameters:
| Parameter | Type | Description |
| zone | string | (Required) Name of the zone within which this record is located. (ex. example.com) |
| domain | string | (Required) Domain name (ex. www.example.com) |
| type | string | (Required) The type of record whose details you are requesting (ex. A). |
Copy CodeReturns details about the specified record
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/zones/:zone/:domain/:type
Example Response:
{
"answers": [
{
"answer": [
"string"
],
"id": "string",
"meta": {
"asn": [
"string"
],
"ca_province": [
"string"
],
"connections": 0,
"country": [
"string"
],
"georegion": [
"string"
],
"high_watermark": 0,
"ip_prefixes": [
"string"
],
"latitude": 0,
"loadAvg": 0,
"longitude": 0,
"low_watermark": 0,
"note": "string",
"priority": 0,
"pulsar": "string",
"requests": 0,
"up": true,
"us_state": [
"string"
],
"weight": 0
},
"region": "string"
}
],
"domain": "string",
"filters": [
{
"disabled": true,
"filter": "string",
"config": {
"eliminate": false
}
}
],
"id": "50eb9d77830f784f98b0dd59",
"link": "string",
"meta": {
"asn": [
"string"
],
"ca_province": [
"string"
],
"connections": 0,
"country": [
"string"
],
"georegion": [
"string"
],
"high_watermark": 0,
"ip_prefixes": [
"string"
],
"latitude": 0,
"loadAvg": 0,
"longitude": 0,
"low_watermark": 0,
"note": "string",
"priority": 0,
"pulsar": "string",
"requests": 0,
"up": true,
"us_state": [
"string"
],
"weight": 0
},
"networks": [
0
],
"regions": {
"meta": {
"asn": [
"string"
],
"ca_province": [
"string"
],
"connections": 0,
"country": [
"string"
],
"georegion": [
"string"
],
"high_watermark": 0,
"ip_prefixes": [
"string"
],
"latitude": 0,
"loadAvg": 0,
"longitude": 0,
"low_watermark": 0,
"note": "string",
"priority": 0,
"pulsar": "string",
"requests": 0,
"up": true,
"us_state": [
"string"
],
"weight": 0
}
},
"tier": 0,
"ttl": 0,
"type": "string",
"use_client_subnet": true,
"zone": "string",
"blocked_tags": [
"string"
],
"local_tags": [
"string"
],
"tags": {}
}
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.
Path Parameters:
| Parameter | Type | Description |
| zone | string | (Required) Name of the zone within which this record is located. (ex. example.com) |
| domain | string | (Required) Domain name (ex. www.example.com) |
| type | string | (Required) The type of record whose details you are requesting (ex. A). |
Copy CodeCreates 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
(RFC 1035) The most common DNS record used, an A record maps a hostname to an IPv4 address (ex. 33.22.33.44). All zones must contain an A record in order for users to access a website or application using its hostname as opposed to memorizing the IPv4 address.
Copy CodeCreates 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
Using a linked record avoids the timely and error-prone tasks of manually creating and maintaining identical configurations across multiple records. Linked records tell the NS1 authoritative server to use the full configuration from a target record that exists somewhere else on the NS1 platform. Note: The target record does not need to be in the same zone as the linked record.
For example, a CDN using NS1 DNS services can instruct its customer (who is also using NS1) to use a linked record to point to the customer’s domain at the CDN, instead of a CNAME. This eliminates DNS round trips and (for A or AAAA records) allows direct resolution at the zone apex. A linked record can be any record type (A, MX, CNAME, etc.), but it must be the same types as a target or it will not resolve.
Compared to a CNAME record, a linked record typically requires one less DNS lookup—often shortening the response time for the requesting resolver or user to receive the final answer.
Linked records are specific to NS1, and their resolution is a completely internal process. During resolution, the full configuration from the target record (including advanced configuration options) is duplicated into the source record such that (other than the name of the record) they resolve identically. DNS recursors making the query will not be able to differentiate between a linked record and the “real” target to which it points. Linked records support all NS1 features and capabilities used by the target record—including real-time data feeds.
Refer to this article for more information.
Copy CodeCreates 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
(RFC 1035, RFC 7505) Mail exchange (MX) records are used to direct emails sent to your domain. MX records, coupled with a mail server, provide organizations (employees, clients, etc.) with emails the organization's domain, such as support@ns1.com. If you have multiple mail servers configured, you can add multiple MX records with varying priorities.
Copy CodeCreates 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 CodeCreates 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 CodeCreates 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.
(RFC 1035) Pointer (PTR) records are usually described as the opposite of an A record. Whereas A records point the domain to an IP address, a PTR record points an IP to a domain (ex. reverse zone lookups). This is often used as spam verification with certain email programs to confirm a mail server is authorized to use the domain from which the email was sent. PTR records usually have to be defined by the owner of the IP address for your server—usually your server hosts. Many hosting companies will set this up for you when you set up a server.
Copy CodeCreates a URLFWD record
curl -X PUT -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/zones/example.com/www.example.com/URLFWD -d '{"zone": "example.com", "domain": "www.example.com", "type": "URLFWD", "answers": [{"answer": ["/one", "http://one.com", 0, 0, 0]}, {"answer": ["/two", "http://two.com", 301, 1, 1]}, {"answer": ["/three", "http://three.com", 302, 2, 0]}]}'
where
- zone is the name of the zone to which you want to add the URLFWD record
- domain is the FQDN within the zone to which you want to add the URLFWD record
- type is the type of record you are creating (in this case, URLFWD)
- each answer specifies five values
- "from" path (ex. /one , /two. /three) indicated by the query
- domain (ex. http://one.com, etc.) to which you want to redirect the query
- forwarding type; either 0 (masking), 301 (permanent), 302 (temporary)
- query forwarding enabled or disabled; either 0 (disabled) or 1 (enabled)
Similar structures can be used with GET or POST commands to retrieve or update the record. For more information, refer to the NS1 API documentation.
Refer to this article to learn more about URLFWD record configuration settings.
Note: URL forwarding must be enabled on your NS1 account in order to create URLFWD record. To enable this feature, contact the NS1 support team by submitting a ticket or emailing [email protected]
Copy CodeCreates a AAAA record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "aaaarecord.example.com", "type": "AAAA", "answers": [ { "answer": [ "dead:beef:cafe::1" ] } ] }' https://api.nsone.net/v1/zones/example.com/aaaarecord.example.com/AAAA
(RFC 3596) AAAA records function in the same way as A records, except that they map hostnames to an IPv6 address (ex. FE80::0202:B3FF:FE1E:8329). The limited number of permutations possible for IPv4 addresses has resulted in recent growth in the number of IPv6 addresses being used.
Copy CodeCreates an AFSDB record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "afsdbrecord.example.com", "type": "AFSDB", "answers": [ { "answer": [ 1, "arecord.example.com" ] } ] }' https://api.nsone.net/v1/zones/example.com/afsdbrecord.example.com/AFSDB
(RFC 1183) AFSDB records are used to connect domain names to Andrew File System (AFS) servers. AFS is similar to NFS, but better suited to handle the latency of wide area networks (such as the internet) and locally caches files. The AFSDB record is key to this operation—providing the location to the file database.
Note: This record is experimental and not recognized by all services, and not all nameservers recognize or implement it. The AFSDB record type is deprecated and has been replaced by the SRV record.
Copy CodeCreates an ALIAS record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "aliasrecord.example.com", "type": "ALIAS", "answers": [ { "answer": [ "arecord.example.com" ] } ] }' https://api.nsone.net/v1/zones/example.com/aliasrecord.example.com/ALIAS
ALIAS is an NS1-specific record type. It is a pseudo-record that works like a CNAME record, but can be used safely at the zone apex because it always resolves to A (or AAAA) record(s). Resolution to the target is a completely internal process—DNS recursors making the query will not be able to differentiate between an ALIAS record and a “real” A (or AAAA) record. When queried, an ALIAS record will always return one or more A or AAAA records. Since ALIAS is a pseudo-record, the query result will never contain ALIAS. There is no good reason to use an ALIAS record outside of the zone apex. Since it requires an extra external lookup, resolution can be slower than a CNAME or linked record. Refer to this article for more information.
Copy CodeCreates a CAA record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "caarecord.example.com", "type": "CAA", "answers": [ { "answer": [ 0, "tag", "value" ] } ] }' https://api.nsone.net/v1/zones/example.com/caarecord.example.com/CAA
(RFC 6844) Domain owners can use DNS Certification Authority Authorization (CAA) records to specify which certificate authorities (CAs) are allowed to issue SSL certificates for their domains. A single domain may contain multiple CAA records. The CAA record prevents an unauthorized CA from issuing an SSL certificate for your domain—in other words, only the CA(s) authorized in the CAA record can issue an SSL certificate for your domain. CAA records specify the following fields:
CAA <flags> <tag> <value>
where
flagsis an unsigned integer between 0 and 255tagis a non-zero sequence of US-ASCII letters and numbers in lowercase.valueis the <character-string> encoding of the value field.
For example:
$ORIGIN example.com
@ CAA 0 issue "ca.example.net"
@ CAA 0 iodef "mailto:[email protected]"
@ CAA 0 iodef "http://iodef.example.com/"
Copy CodeCreates a CERT record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "certrecord.example.com", "type": "CERT", "answers": [ { "answer": [ 3, 0, 0, "dGVzda==" ] } ] }' https://api.nsone.net/v1/zones/example.com/certrecord.example.com/CERT
(RFC 4398, 6944) CERT resource records provide a space in the DNS for certificates and related certificate revocation lists (CRLs). These certificates verify the authenticity of the sending and receiving parties. The CRLs identify the certificates that are no longer valid.
Copy CodeCreates a CNAME record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "cnamerecord.example.com", "type": "CNAME", "answers": [ { "answer": [ "arecord.example.com" ] } ] }' https://api.nsone.net/v1/zones/example.com/cnamerecord.example.com/CNAME
(RFC 1034, 2181) A Canonical Name (CNAME) record maps one domain name (an alias) to another (the canonical name). There may be only one such canonical name for any one alias. That name should generally be a name that exists elsewhere in the DNS, though there are some rare applications for aliases with the accompanying canonical name undefined in the DNS. An alias name (label of a CNAME record) may, if DNSSEC is in use, have SIG, NXT, and KEY RRs, but may have no other data. Refer to this article for more information.
Copy CodeCreates a DNAME record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "example.com", "type": "DNAME", "answers": [ { "answer": [ "newzone.net" ] } ] }' https://api.nsone.net/v1/zones/example.com/example.com/DNAME
(RFC 6672) As opposed to a CNAME record which maps only a single node, a DNAME record is used to redirect an entire subsection (or subtree) of the DNS namespace to another domain. Once implemented, all names that end with a particular suffix are redirected to another part of the DNS.
Copy CodeCreates a HINFO record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "hinforecord.example.com", "type": "HINFO", "answers": [ { "answer": [ "fancy", "potato" ] } ] }' https://api.nsone.net/v1/zones/example.com/hinforecord.example.com/HINFO
(RFC 1035) Host information (HINFO) records are used to associate general information about a host’s CPU and OS with the host’s domain name. For example, if www.example.com was running Ubuntu 16.04 with a 3.2 GHz Intel CPU, this information can be made publicly available by creating an HINFO record with “PC-Intel-3200mhz” and “Ubuntu 16.04” in the CPU and OS fields, respectively. This information is used by services like FTP to determine the correct procedures for connecting to hosts based on their configuration.
Copy CodeCreates a NAPTR record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "naptrrecord.example.com", "type": "NAPTR", "answers": [ { "answer": [ 1, 2, "S", "http", "replace/me/i", "hi" ] } ] }' https://api.nsone.net/v1/zones/example.com/naptrrecord.example.com/NAPTR
(RFC 3403) Naming Authority Pointer (NAPTR) records are most commonly used with internet telephony (or VoIP) services. It can be used to map telephone numbers and email addresses for VoIP users to SIP servers via SRV records to initiate calls.
Copy CodeCreates an NS record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "nsrecord.example.com", "type": "NS", "answers": [ { "answer": [ "arecord.example.com" ] } ] }' https://api.nsone.net/v1/zones/example.com/nsrecord.example.com/NS
(RFC 1035) Typically configured with your registrar, Name server (NS) records are used to delegate a domain or subdomain to a set of name servers. Name servers, such as NS1, hold all the other DNS records for your domain and tell all the other computers connected to the internet what records your domain holds. Therefore, setting the NS record is a critical step in getting your domains and servers online.
Copy CodeCreates an RP record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "rprecord.example.com", "type": "RP", "answers": [ { "answer": [ "bob.example.com", "alice.example.com"] } ] }' https://api.nsone.net/v1/zones/example.com/rprecord.example.com/RP
(RFC 1183) Typically, the "responsible person" record contains information about the person responsible for the domain. It is usually an email address where the "@" sign is replaced by a period (.).
Copy CodeCreates an SPF record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "spfrecord.example.com", "type": "SPF", "answers": [ { "answer": [ "v=spf1", "ip4:1.2.3.4", "include:example.com", "-all" ] } ] }' https://api.nsone.net/v1/zones/example.com/spfrecord.example.com/SPF
(RFC 4408, 7208) Sender Policy Framework (SPF) records are used during email verification to prevent your domain name from being used by spammers or malicious users. Simply creating an SPF record on your main domain with the content: v=spf1 ip4:11.11.11.11 a -all (replacing 11.11.11.11 with your mail server’s IP address) will tell email receivers that your mail server is the only server allowed to send emails from your domain. All emails received from other servers are to be rejected or marked as spam. If you have multiple mail servers, you can add another ip4:x.x.x.x after the previous one to allow another IP address. Note: The SPF record is still supported, but shouldn’t be used in new configurations. Instead, making a TXT record with the same content is the more accepted practice today. Commonly, mail servers will define both an SPF and a TXT record for the most compatibility.
Copy CodeCreates an SRV record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "srvrecord.example.com", "type": "SRV", "answers": [ { "answer": [ 1, 1, 80, "srvrecord.example.com" ] } ] }' https://api.nsone.net/v1/zones/example.com/srvrecord.example.com/SRV
(RFC 2782) Service locator (SRV) records are a way to use DNS to locate services for a specific domain. SRV records allow for built-in load balancing of multiple servers using the priority and weight values in the records. SRV record parameters include:
- service is the name of a service, such as SIP or XMPP. Underscore required.
- proto is the protocol in use for the service. Normally either TCP or UDP. Underscore required.
- domainname is the FQDN of the domain using the service.
- ttl is the time-to-live for the DNS record.
- priority is the priority of the target. A lower number indicates a higher preference.
- weight is the weight of the target. A higher number indicates a higher preference.
- target is the hostname of the server which is hosting the service.
You can verify the record has been created correctly using the dig tool as shown in this example:
test:~ test$ dig srv _www._tcp.zone.example @dns1.p08.nsone.net +short 1 100 80 www.zone.example.
test:~ test
Copy CodeCreates a TXT record
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "zone": "example.com", "domain": "txtrecord.example.com", "type": "TXT", "answers": [ { "answer": [ "some", "text", "here" ] } ] }' https://api.nsone.net/v1/zones/example.com/txtrecord.example.com/TXT
(RFC 1035) Text (TXT) records allow you to contain any text-based information on a domain or subdomain. Applications can use this to collect information about a service—typically, SPF records, DomainKeys, and DKIM (two other email verification processes). Usage with SPF can be read about above in the SPF Records section. TXT records may contain any information up to 255 characters per string. A zone may container multiple TXT records.
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": [],
"customer": 1004,
"domain": "mail.example.com",
"zone": "example.com",
"answers": [
{
"id": "52053b569f782d5b1a10a859",
"feeds": [
{
"source": "a53252f9e583c6708331a1daeb172e12",
"feed": "520533b89f782d5b1a10a854"
}
],
"answer": [
10,
"1.2.3.4"
],
"meta": {
"up": { feed: "520533b89f782d5b1a10a854" }
}
}
],
"regions": {},
"meta": {},
"filters": [],
"ttl": 3600,
"use_client_subnet": true
}
POST /v1/zones/:zone/:domain/:type
POSTUpdate a record
Modifies configuration details for an existing DNS record.
Path Parameters:
| Parameter | Type | Description |
| zone | string | (Required) Name of the zone within which this record is located. (ex. example.com) |
| domain | string | (Required) Domain name (ex. www.example.com) |
| type | string | (Required) The type of record whose details you are requesting (ex. A). |
Copy CodeDisable use of edns-client-subnet data for a record
curl -X POST -H 'X-NSONE-Key: qACMD09OJXBxT7XOuRs8' -d '{"use_client_subnet":false}' https://api.nsone.net/v1/zones/example.com/example.com/A
Request URL:
https://api.nsone.net/v1/zones/:zone/:domain/:type
Example URL:
https://api.nsone.net/v1/zones/example.com/mail.example.com/MX
Example Request:
{
"answers": [
{
"answer": [
10,
"1.2.3.4"
]
},
{
"answer": [
20,
"5.6.7.8"
]
}
]
}
Example Response:
{
"id": "52053b569f782d5b1a10a85a",
"networks": [0],
"type": "MX",
"feeds": [],
"tier": 1,
"customer": 1004,
"domain": "mail.example.com",
"zone": "example.com",
"answers": [
{
"id": "52053c239f782d5b1a10a85e",
"answer": [
10,
"1.2.3.4"
]
},
{
"id": "52053c239f782d5b1a10a85f",
"answer": [
20,
"5.6.7.8"
]
}
],
"regions": {},
"meta": {},
"filters": [],
"ttl": 3600,
"use_client_subnet": true
}
DELETE /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"
]
}
DNS views (DDI only)
GET /v1/views/
GETList all DNS views
Returned all available DNS views. Optionally, you can specify a set of views to skip or specify a maximum number of views to return.
Note: At this time, DNS views are not supported on Managed DNS or Managed DNS for China networks.
Query Parameters:
| offset | string | Number of DNS views to skip in the returned list. |
| limit | string | Maximum number of views to return. A value of 0 indicates no limit. |
Copy CodeReturns a list of all available DNS views
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/views
Example Response:
[
{
"name": "string",
"created_at": 0,
"updated_at": 0,
"read_acls": [
"string"
],
"update_acls": [
"string"
],
"zones": [
"string"
],
"networks": [
1
],
"preference": 0
}
]
GET /v1/views/{view_name}
GETView DNS view details
Returns configuration details about the specific DNS View.
Path Parameters:
| view_name | string | (Required) Name of the DNS view. |
Copy CodeReturns DNS View details
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/views/{view_name}
Example Response:
[
{
"name": "string",
"created_at": 0,
"updated_at": 0,
"read_acls": [
"string"
],
"update_acls": [
"string"
],
"zones": [
"string"
],
"networks": [
1
],
"preference": 0
}
]
PUT /v1/views/{view_name}
PUTCreate a DNS view
You must include a JSON body in the request with the associated zones, ACLs, and networks. An empty array of ACLs implies that all will be denied.
Defined in RFC 8499, the term DNS view (aka split-horizon, split-view DNS, etc.) is a configuration for a DNS server that allows it to serve one set of data to one group of clients (e.g. internal employees), and a different set of data to another group of clients (e.g. public internet).
In the NS1 DDI platform, users can create access control lists (ACLs) that define a group of clients (by IP address, TSIG key, and/or GSS-TSIG identity). One or more ACLs are attached to a DNS view which is configured to either allow or deny those clients access for queries and updates.
Common use cases include creating an internal (corporate) view and an external (public) view, attaching ACLs that point IP addresses within your organization to the internal view and all other clients to the external view. This allows the internal or corporate user to view internal specific resources that are not viewable to the public audience.
Note: At this time, DNS views are not supported for Managed DNS or Managed DNS for China networks (i.e., networks 0 and 5).
Path Parameters:
| view_name | string | (Required) Name of the DNS view you are creating. |
Request Body Parameters:
| read_acls | array of strings | List of ACL names used with "read" permissions (multiple ACLs separated by a comma). The order of the ACLs determines how they are processed. |
| update_acls | array of strings | List of ACL names used with "update" permissions (multiple ACLs separated by a comma). The order of the ACLs determines how they are processed. |
| zones | array of strings | List of zone names (unique strings) specified upon zone creation. If you did not specify a name during zone creation, the name defaults to match the FQDN. |
| networks | array of integers | (optional) Networks is an array of positive integers corresponding to the service definition(s) to which the zone is published. |
| preference | integer | Determines the view order. Preference is a unique value that indicates the priority of this view. This can be any value greater than 0 where a value of 1 indicates top priority. |
Copy CodeCreates a new DNS view
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"read_acls":["{read_acls}"],"update_acls":["{update_acls}"],"zones": ["{zone_names}"],"networks": [{networks}],"preference":{pref_number} }' https://api.nsone.net/v1/views/{view_name}
Example Request:
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"filters":{},"read_acls":["private_net","staging_net"],"update_acls":[],"zones":["mycompany.local","mycompany.net"],"networks":[1],"preference":0}' https://api.nsone.net/v1/views/internal_view
Example Response:
{"name":"internal_view","networks":[1],"preference":0,"read_acls":["private_net","staging_net"],"update_acls":[],"zones":["mycompany.local","mycompany.net"]}
Example Request:
{
"read_acls": [
"SF_office",
"LA_office"
],
"zones": [
"example.com"
],
"networks": [
1,
2
]
}
POST /v1/views/{view_name}
POSTEdit a DNS view
Modifies a DNS view. You must include a JSON body in the request which may contain the associated zones, ACLs, and networks. An empty array of ACLs implies that all will be denied.
Path Parameters:
| name | string | (Required) Name of the DNS view you are creating. |
Request Body Parameters:
| read_acls | array of strings | List of ACL names used with "read" permissions (multiple ACLs separated by a comma). The order of the ACLs determines how they are processed. |
| update_acls | array of strings | List of ACL names used with "update" permissions (multiple ACLs separated by a comma). The order of the ACLs determines how they are processed. |
| zones | array of strings | List of zone names (unique strings) specified upon zone creation. If you did not specify a name during zone creation, the name defaults to match the FQDN. |
| networks | array of integers | (optional) Networks is an array of positive integers corresponding to the service definition(s) to which the zone is published. |
| preference | integer | Determines the view order. Preference is a unique value that indicates the priority of this view. This can be any value greater than 0 where a value of 1 indicates top priority. |
Copy CodeModifies a DNS view configuration
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{"read_acls": ["{read_acls}"], "update_acls": ["{update_acls}"], "zones": ["{zone_names}"], "networks": [{networks}], "preference": {pref_number} }' https://api.nsone.net/v1/views/{view_name}
Example Request:
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{"filters":{},"read_acls":["private_net","staging_net"],"update_acls":["trusted_ips"],"zones":["mycompany.local","mycompany.net"],"networks":[1],"preference":0}' https://api.nsone.net/v1/views/internal_view
Example Response:
{"name":"internal_view","networks":[1],"preference":0,"read_acls":["private_net","staging_net"],"update_acls":["trusted_ips"],"zones":["mycompany.local","mycompany.net"]}
DELETE /v1/views/{view_name}
DELETEDelete a DNS view
Removes an existing DNS view.
Path Parameters:
| name | string | (Required) Name of the DNS view you are deleting. |
Copy CodeRemoves an existing DNS view.
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/views/{view_name}
Example Request:
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/views/internal_view
GET /v1/config/views/preference
GETGet DNS view preference
Returns the preference number for all available views.
Copy CodeReturns the preference number for all available views
curl -X GET -H 'X-NSONE-Key: $API_KEY' https://api.nsone.net/v1/config/views/preference
Example Response:
{
"property1": 0,
"property2": 0
}
POST /v1/config/views/preference
POSTEdit DNS view preference
Modifies the preference number associated with the specified DNS view. In the request body, enter one or more key-value pairs matching the name of the DNS view to the desired preference number.
Request body parameters:
| view_name | string | The "key" in the key-value pair. Set this to the name of the DNS view. |
| preference_number | integer | The "value" in the key-value pair. Set this to the desired preference number for the corresponding DNS view. |
Copy CodeModifies the preference number for the specific DNS view
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{"{view_name}": {preference_number} }' https://api.nsone.net/v1/config/views/preference
Example Request:
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{
"internalview": 1,
"externalview": 2
}' https://api.nsone.net/v1/config/views/preference
Access control lists (DDI only)
GET /v1/acls
GETList all ACLs
View a list of all access control lists (ACLs).
Copy CodeReturns a list of all ACLs
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/acls
Example Response:
[{"name":"docker.acl","gss_tsig_identities":[],"src_prefixes":["172.18.11.0/24","127.0.0.1/32"],"tsig_keys":[]},{"name":"private_net","gss_tsig_identities":["test/[email protected]"],"src_prefixes":["172.18.11.0/24","192.168.0.11-192.168.0.56"],"tsig_keys":["my.test.key."]}]
GET /v1/acls/{acl_name}
GETView ACL details
View details about the specified access control list (ACL).
Copy CodeReturns details about the specified ACL.
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/acls/{acl_name}
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/acls/private_net
Example Response:
{
"name": "string",
"src_prefixes": [
"string"
],
"tsig_keys": [
"string"
],
"gss_tsig_identities": [
"string"
]
}
PUT /v1/acls/{acl_name}
PUTCreate an ACL
An access control list (ACL) is a named object associated with one or more IP addresses, TSIG keys, or GSS-TSIG identities (service principals). You must specify at least one of these per ACL. One or more ACLs can be attached to a DNS view which is configured to either allow or deny those clients access for queries and updates.
Common use cases include creating an internal (corporate) view and an external (public) view, attaching ACLs that point IP addresses within your organization to the internal view and all other clients to the external view. This allows the internal or corporate user to view internal specific resources that are not viewable to the public audience.
Run the PUT command below to create one or more access control lists (ACLs).
Note: The order in which the attributes appear determines how each query is processed. From top to bottom, items of the same type (i.e. IP addresses, TSIG keys, or GSS-TSIG identity) are processed using logical “or” statements. Items of different types are processed as logical “and” statements.
Note: You can specify which clients should not be included in the ACL by entering an exclamation mark “!” before the address, subnet, or range. For example !1.0.1.100-1.0.1.200 indicates that this IP range should not be included in the ACL.
Path Parameters:
| name | string | Name of the access control list (ACL) you are creating |
Request Body Parameters:
| src_prefixes | array of strings | List of prefixes (IP address, CIDR, or range). If not provided, this defaults to ["0.0.0.0/0", "::/0"]. Each prefix can have an optional ! negation mark at the begin and should be in CIDR or single-host format. |
| tsig_keys | array of strings | List of bound TSIG keys |
| gss_tsig_identities | array of strings | List of bound GSS-TSIG identities |
Copy CodeCreate an ACL
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "src_prefixes":["{ip_range}"], "tsig-keys":["{tsig_key}"], "gss-tsig-identities":["{gss_tsig_id}"] }' https://{api.mycompany.net}/v1/acls/{acl_name}
Request URL:
https://{api.mycompany.net}/v1/acls/{acl_name}
Example Request:
{
"src_prefixes": [
"172.18.0.0/16",
"!172.18.12.0/24"
],
"tsig_keys": [
"tsig3",
"tsig4"
],
"gss_tsig_identities": [
"[email protected]",
"[email protected]"
]
}
Example Response:
{
"name": "string",
"src_prefixes": [
"string"
],
"tsig_keys": [
"string"
],
"gss_tsig_identities": [
"string"
]
}
POST /v1/acls/{acl_name}
POSTEdit an ACL
Update an access control list (ACL). Refer to Create an access control list (ACL) for important notes and details about each parameter.
Note: The order in which the attributes appear determines how each query is processed. From top to bottom, items of the same type (i.e. IP addresses, TSIG keys, or GSS-TSIG identity) are processed using logical “or” statements. Items of different types are processed as logical “and” statements.
Note: You can specify which clients should not be included in the ACL by entering an exclamation mark “!” before the address, subnet, or range. For example !1.0.1.100-1.0.1.200 indicates that this IP range should not be included in the ACL.
Path Parameters:
| name | string | Name of the access control list (ACL) you are modifying |
Request Body Parameters:
| src_prefixes | array of strings | List of prefixes (IP address, CIDR, or range). If not provided, this defaults to ["0.0.0.0/0", "::/0"]. Each prefix can have an optional ! negation mark at the begin and should be in CIDR or single-host format. |
| tsig_keys | array of strings | List of bound TSIG keys |
| gss_tsig_identities | array of strings | List of bound GSS-TSIG identities |
Copy CodeModifies an ACL configuration
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "src_prefixes":["{ip_range}"], "tsig-keys":["{tsig_key}"], "gss-tsig-identities":["{gss_tsig_id}"] }' https://api.mycompany.net/v1/acls/{acl_name}
Example Request:
{
"src_prefixes": [
"172.18.0.0/16",
"!172.18.12.0/24"
],
"tsig_keys": [
"tsig3",
"tsig4"
],
"gss_tsig_identities": [
"[email protected]",
"[email protected]"
]
}
Example Response:
{
"name": "string",
"src_prefixes": [
"string"
],
"tsig_keys": [
"string"
],
"gss_tsig_identities": [
"string"
]
}
DELETE /v1/acls/{acl_name}
DELETEDelete an ACL
Deletes an access control list (ACL).
Copy CodeDeletes and ACL
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/acls/{acl_name}
Example Request:
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/acls/private_net
TSIG
GET /v1/tsig
GETList TSIG keys
Returns all available TSIG keys.
Query Parameters:
| offset | integer | Number of TSIG keys to skip in the response. |
| limit | integer | Maximum number of TSIG keys to return. A value of 0 equates to no limit. |
Copy CodeReturns a list of TSIG keys
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/tsig
Example Response:
[
{
"name": "string",
"algorithm": "hmac-sha1",
"secret": "string"
}
]
GET /v1/tsig/{key_name}
GETView TSIG key details
Returns details for the TSIG key specified in the path by its name.
Path parameters:
| key_name | string | (Required) Name of the TSIG key. This should be a valid domain name. |
Copy CodeReturns TSIG key details
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/tsig/{key_name}
Example Response:
{
"name": "string",
"algorithm": "hmac-sha1",
"secret": "string"
}
PUT /v1/tsig/{key_name}
PUTCreate a TSIG key
Creates a new TSIG key. Note that you must include a JSON body in the request with the algorithm and secret.
Path Parameters:
| key_name | string | Name of the TSIG key you are creating. This should be a valid domain name. |
Request Body Parameters:
| algorithm | string (enum) | (Required) TSIG key algorithm. Supported values include:"hmac-sha1", "hmac-sha224", "hmac-sha256", "hmac-sha384", "hmac-sha512", "hmac-md5" |
| secret | string | TSIG key secret encoded into Base64. |
Copy CodeCreates a new TSIG key
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "algorithm": "hmac-sha512", "secret": "Ok1qR5IW1ajVka5cHPEJQIXfLyx5V3PSkFBROAzOn21JumDq6nIpoj6H8rfj5Uo+Ok55ZWQ0Wgrf302fDscHLw==" }' https://api.nsone.net/v1/tsig/{key_name}
Example Request:
{
"algorithm": "hmac-sha512",
"secret": "Ok1qR5IW1ajVka5cHPEJQIXfLyx5V3PSkFBROAzOn21JumDq6nIpoj6H8rfj5Uo+Ok55ZWQ0Wgrf302fDscHLw=="
}
Example Response:
{
"name": "string",
"algorithm": "hmac-sha1",
"secret": "string"
}
POST /v1/tsig/:name
POSTModify a TSIG key
Modifies an existing TSIG key. You must include a JSON body in the request, which may contain key algorithm and/or secret.
Path parameters:
| name | string | (Required) Name of the TSIG key you are modifying. This should be a valid domain name. |
Request body parameters:
| algorithm | string (enum) | TSIG key algorithm. Supported values include: "hmac-sha1" "hmac-sha224" "hmac-sha256" "hmac-sha384" "hmac-sha512" "hmac-md5" |
| secret | string | TSIG key secret encoded into Base64. |
Copy CodeEdits the specified TSIG key
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "algorithm": "hmac-sha1", "secret": "$TSIG_KEY" }' https://api.nsone.net/v1/tsig/{key_name}
Example Request:
{
"algorithm": "hmac-sha1",
"secret": "string"
}
Example Response:
{
"name": "string",
"algorithm": "hmac-sha1",
"secret": "string"
}
DELETE /v1/tsig/{key_name}
DELETERemove a TSIG key
Deletes the TSIG key specified in the path by its name.
Path parameters:
| name | string | (Required) Name of the TSIG key you are deleting. |
Copy CodeRemoves the specified TSIG key
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/tsig/{key_name}
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 /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/sources
Example Request:
[
{
"name": "string",
"sourcetype": "string",
"config": {
"property1": "string",
"property2": "string"
},
"feeds": [],
"id": "abfa2a71776ae5246724dce7b53c4371"
}
]
GET /v1/data/sources/:sourceid
GET View a single data source
Returns the details for a single data source — including configuration details, all connected data feeds, and, within each connected data feed, any associated metadata table (destinations).
Path parameters:
| sourceID | string | (Required) Unique identifier for the data source |
Copy CodeReturns details for the specified data source
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/data/sources/:sourceid
Request URL:
https://api.nsone.net/v1/data/sources/:sourceid
Example URL:
https://api.nsone.net/v1/data/sources/f443e609c9a9182b3dab56b7abd74546
Example Response:
{
"sourcetype": "rackspace",
"id": "f443e609c9a9182b3dab56b7abd74546",
"config": {
"webhook_token": "none"
},
"feeds": [
{
"destinations": [],
"id": "520849a99f782d5b1a10a86d",
"data": {
"up": "false"
},
"config": {
"entity_id": "enAAAAA",
"alarm_id": "alAAAA"
},
"name": "server.example.com alert"
}
],
"name": "My Rackspace Source",
"status": "ok"
}
PUT /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.
Path parameters:
| name | string | Name of the data source |
| sourcetype | string | Type of data source |
| config | object | Configuration property name and value based on the source type. This object must contain fields that correspond to the config description in /data/sourcetypes for the sourcetype specified. |
Copy CodeConnect a Catchpoint data source
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "sourcetype": "catchpoint", "name": "catchpoint source", "config": {} }' https://api.nsone.net/v1/data/sources
Copy CodeConnect a Cloudwatch data source
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"sourcetype":"cloudwatch", "name":"My Cloudwatch Topic", "config":{}}' https://api.nsone.net/v1/data/sources
After creating the Cloudwatch data source in NSONE, create an SNS topic in your Amazon account, connect any alerts you want to feed to NSONE to that topic, and create an HTTPS subscription for the topic with the NSONE Feed URL (https://api.nsone.net/v1/feed/:feedid). New data feeds for this source should specify the Alarm Name of a Cloudwatch alarm.
Copy CodeConnect a Datadog data source
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "sourcetype": "datadog", "name": "datadog source", "config": {} }' https://api.nsone.net/v1/data/sources
Copy CodeConnect a New Relic data source
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "sourcetype": "newrelic_webhook", "name": "newrelic_webhook source", "config": { "account_id": 1 } }' https://api.nsone.net/v1/data/sources
Copy CodeConnect an NS1 monitoring webhook
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "sourcetype": "nsone_monitoring", "name": "nsone_monitoring source", "config": {} }' https://api.nsone.net/v1/data/sources
Copy CodeConnect a native NS1 data source
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "sourcetype": "nsone_v1", "name": "nsone_v1 source", "config": {} }' https://api.nsone.net/v1/data/sources
Copy CodeConnect a Pingdom data source
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "sourcetype": "pingdom", "name": "pingdom source", "config": {} }' https://api.nsone.net/v1/data/sources
Copy CodeConnect a Rackspace data source
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "sourcetype": "rackspace", "name": "rackspace source", "config": { "webhook_token": "abcd1234" }}' https://api.nsone.net/v1/data/sources
Request URL:
https://api.nsone.net/v1/data/sources
Example Response:
{
"name": "string",
"sourcetype": "string",
"config": {
"property1": "string",
"property2": "string"
},
"feeds": [],
"id": "abfa2a71776ae5246724dce7b53c4371"
}
POST /v1/data/sources/:sourceid
POST Edit 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.
Path parameters:
| sourceID | string | (Required) Unique identifier for the data source you are modifying |
Copy CodeEdits the specified data source
curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '{ "name": "string", "sourcetype": "string", "config": { "property1": "string", "property2": "string" }, "feeds": [] }' https://api.nsone.net/v1/data/sources/:sourceid
Request URL:
https://api.nsone.net/v1/data/sources/:sourceid
Example URL:
https://api.nsone.net/v1/data/sources/0e308ec0266d9127d166e0cbd7ceffda
Example Request:
{
"name": "Monitor.us New Name"
}
Example Response:
{
"sourcetype": "monitor_us",
"id": "0e308ec0266d9127d166e0cbd7ceffda",
"config": {
"api_key": "15PSVFCXA377TGUY0FJA7T9VZY",
"secret_key": "47AOG8ATA1QNUC3H3UH2DRBXYZ"
},
"feeds": [],
"name": "Monitor.us New Name",
"status": "ok"
}
DELETE /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.
Path parameters:
| sourceID | string | (Required) Unique identifier of the data source |
Copy CodeDeletes the specified data source
curl -X DELETE -H 'X-NSONE-Key: $API_KEY' https://api.nsone.net/v1/data/sources/:sourceid
Request URL:
https://api.nsone.net/v1/data/sources/:sourceid
Example URL:
https://api.nsone.net/v1/data/sources/0e308ec0266d9127d166e0cbd7ceffda
Data Feeds
GET https://api.nsone.net/v1/data/feeds/:sourceid
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 |
Filter Chain
Filters
To create any filter via the API, you must create or update a record for your domain with the answers you plan to use. You must also define any metadata that would be required for the filters you want to create. Finally, you specify the resource record to which to apply these changes. You create via a PUT request, and you update via a POST request.
Example
Suppose that you want to create an A record with two answers on the pulsar.example.com domain that uses the Pulsar Performance Sort filter. In the first step of this process, we often recommend that you start by defining backup logic, such as basic geographical steering, in order to have backup logic if Pulsar does not have enough data to make a decision. To do this, you would:
- Define the
zone,domain, and the recordtype. - Define at least one
answerwithin the record. - Add geographic metadata using the
metaobject for the answer to define the backup filter.So far, your command would read as follows:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.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"} https://api.nsone.net/v1/zones/example.com/pulsar.example.com/AFrom here, you would add definitions for the Pulsar metadata, filters, and their associated thresholds. Changes are showcased in the following example. We have:
- Added Pulsar metadata to both answers.
- Defined filters for the
9.9.9.9answer.
The result should look something like this:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.example.com","type":"A",
"answers":[{"answer":["1.1.1.1"],"meta":{"georegion":["US-EAST"],
"pulsar":["job_id": "1uxw9ir"]},
{"answer":["9.9.9.9"],"meta":{"georegion":["US-WEST"],
"pulsar":["job_id": "1uxxo37"]}}],"filters":[{"filter":"geotarget_regional"},{"filter":"pulsar_performance_sort"}]}]' https://api.nsone.net/v1/zones/example.com/pulsar.example.com/A
Your performance metric is latency, so you decide to sort in ascending order. The changes are highlighted in the following sample:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.example.com","type":"A",
"answers":[{"answer":["1.1.1.1"],"meta":{"georegion":["US-EAST"],
"pulsar":["job_id": "1uxw9ir"]},{"answer":["9.9.9.9"],
"meta":{"georegion":["US-WEST"],"pulsar":["job_id": "1uxxo37"]}}],
"filters":[{"filter":"geotarget_regional"},
{"filter":"pulsar_performance_sort","config":{"sort_descending": false}}]
}]' https://api.nsone.net/v1/zones/example.com/pulsar.example.com/A
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 Sort
This filter is being deprecated by 1 October 2021. The following filters can help replicate the behavior of the Pulsar Sort filter, allowing you more flexibility in defining a policy that best meets your needs:
The Pulsar Sort filter sorts answers based on real-time routing data. Each answer is associated with a specific job_id, 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
This filter will be deprecated by 1 October 2021. The best replacement filters for this filter are:
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 |
Pulsar Availability Sort
NOTE
You should set up a proper fallback strategy to ensure that other filters in NS1’s Filter Chain can intelligently route traffic when there isn’t sufficient performance telemetry. You should set up your Filter Chain to include these filters before each Pulsar filter. For example, you could include any of the geotarget filters to fall back on a geotargeting strategy. If you are distributing traffic across endpoints like CDNs or distributing traffic across a geographically dispersed infrastructure, use the shuffle or cost filters to better balance the lowest-cost traffic across your endpoints.
The following parameter is common to all of the Pulsar availability filters:
| Parameter | Type | Description |
|---|---|---|
| job_id | string | Required. The ID of the Pulsar job to be associated with this record. |
By default, answers are sorted from lowest to highest value. If there is not enough performance data available to make a decision, answers are passed through unchanged, and these decisions are logged as “insufficient” when you view Pulsar decision data.
Each answer is associated with a specific job_id, which is tied to a probe that gathers performance and availability telemetry that is used to rate the answer.
The Pulsar Availability Sort filter requires the pulsar input metadata field, which is a custom data structure. It must be a dictionary, nested inside a list. You can find the fields of the dictionary above.
If there is not enough availability data, possible answers are passed through unchanged, and fallback logic is used. In these instances, the query is then marked as having “insufficient data” and is added to the associated category within Pulsar’s reporting dashboard. To learn more about insufficiency reporting, click here and scroll to the Decisions header. To retrieve decision insufficiencies via API, visit the NS1 API Documentation endpoint.
Copy CodeDefine a Pulsar Availability Sort filter for a record
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":":zone","domain":":child_domain","type":":record_type","answers":[{"answer":["9.9.9.9"],"meta":{"pulsar":["job_id": ":job_id"]}}],"filters":[{"filter":"pulsar_availability_sort"]}]' https://api.nsone.net/v1/zones/:zone/:domain/:record_type
Example Request:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.example.com","type":"A", "answers":[{"answer":["1.1.1.1"],"meta":{"georegion":["US-EAST"],"pulsar":["job_id": "1uxw9ir"]},{"answer":["9.9.9.9"],"meta":{"georegion":["US-WEST"],"pulsar":["job_id": "1uxxo37"]}}],"filters":[{“filter”:“geotarget_regional”},{"filter":"pulsar_availability_sort"]}]' https://api.nsone.net/v1/zones/example.com/pulsar.example.com/A
Pulsar Performance Sort
NOTE
You should set up a proper fallback strategy to ensure that other filters in NS1’s Filter Chain can intelligently route traffic when there isn’t sufficient performance telemetry. You should set up your Filter Chain to include these filters before each Pulsar filter. For example, you could include any of the geotarget filters to fall back on a geotargeting strategy. If you are distributing traffic across endpoints like CDNs or distributing traffic across a geographically dispersed infrastructure, use the shuffle or cost filters to better balance the lowest-cost traffic across your endpoints.
The following parameters are common to Pulsar performance filters:
| Parameter | Type | Description |
|---|---|---|
| job_id | string | Required. The ID of the Pulsar job to be associated with this record. |
| bias | string | Only applies to the Pulsar Performance Stabilize and Pulsar Performance Sort filters. 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. |
By default, answers are sorted from lowest to highest value. You can set the sort_descending parameter to true to sort in ascending order to account for certain metrics that require answers to be sorted from highest to lowest. If there is not enough performance data available to make a decision, answers are passed through unchanged, and these decisions are logged as “insufficient” when you view Pulsar decision data.
Sorting by ascending answers (worst to best) is best when your sort criteria is latency, because you want to send end users to endpoints that have lower latency values. On the other hand, if your performance measurement is defined by bandwidth and MBps, sorting in descending order would be more advantageous, because you would be sorting from the best value to the worst value.
Each answer is associated with a specific job_id, which is tied to a probe that gathers performance and availability telemetry that is used to rate the answer.
The Pulsar Performance Sort filter requires the pulsar input metadata field, which is a custom data structure. It must be a dictionary, nested inside a list. You can find the fields of the dictionary above.
If there is not enough availability data, possible answers are passed through unchanged, and fallback logic is used. In these instances, the query is then marked as having “insufficient data” and is added to the associated category within Pulsar’s reporting dashboard. To learn more about insufficiency reporting, click here and scroll to the Decisions header. To retrieve decision insufficiencies via API, visit the NS1 API Documentation endpoint.
Copy CodeDefine a Pulsar Performance Sort filter for a record
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":":zone","domain":":child_domain","type":":record_type","answers":[{"answer":["1.1.1.1"],"meta":{"pulsar":["job_id":"1uxw9ir"]},{"answer":["9.9.9.9"],{"pulsar":["job_id":":jobID"]}}],"filters":[{"filter":"pulsar_performance_sort","config":{"sort_descending": true}}]}]' https://api.nsone.net/v1/zones/:zone/:domain/:record_type
Example Request:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.example.com","type":"A","answers":[{"answer":["1.1.1.1"],"meta":{"pulsar":["job_id":"1uxw9ir"]},{"answer":["9.9.9.9"],{"pulsar":["job_id":"1uxxo37"]}}],"filters":[{"filter":"pulsar_performance_sort","config":{"sort_descending": true}}]}]' https://api.nsone.net/v1/zones/example.com/pulsar.example.com/A
Example Request:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.example.com","type":"A", "answers":[{"answer":["1.1.1.1"],"meta":{"georegion":["US-EAST"],{"pulsar":["job_id":"1uxw9ir"]},{"answer":["9.9.9.9"],"meta":{"georegion":["US-WEST"],"pulsar":["job_id": "1uxxo37"]}}],"filters":[{"filter":"geotarget_regional"},{"filter":"pulsar_performance_sort","config":{"sort_descending": false}}]}]' https://api.nsone.net/v1/zones/example.com/pulsar.example.com/A
| Parameter | Type | Description |
|---|---|---|
| sort_descending | boolean | If enabled, the filter bases its sorting behavior on the worst-performing answer instead of the best, then sorts the remaining answers accordingly. |
Pulsar Performance Stabilize
NOTE
You should set up a proper fallback strategy to ensure that other filters in NS1’s Filter Chain can intelligently route traffic when there isn’t sufficient performance telemetry. You should set up your Filter Chain to include these filters before each Pulsar filter. For example, you could include any of the geotarget filters to fall back on a geotargeting strategy. If you are distributing traffic across endpoints like CDNs or distributing traffic across a geographically dispersed infrastructure, use the shuffle or cost filters to better balance the lowest-cost traffic across your endpoints.
The following parameters are common to all of the Pulsar performance filters:
| Parameter | Type | Description |
|---|---|---|
| job_id | string | Required. The ID of the Pulsar job to be associated with this record. |
| bias | string | Only applies to the Pulsar Performance Stabilize and Pulsar Performance Sort filters. 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. |
By default, this filter determines which answer has the best performance relative to the other answers that have also passed through to this filter. After determining the best or worst performance in each of the answers, the filter then compares its defined performance threshold to the other responses. If there is not enough performance data available to make a decision, answers are passed through unchanged, and these decisions are logged as “insufficient” when you view Pulsar decision data.
If you sort by the default behavior, the answer that has the best performance based on the threshold is discarded. This can be useful if, for example, you are setting a threshold for latency, where a higher value can slow the flow of traffic. Conversely, your threshold could be based on bandwidth. if you sort in descending order, the worst-performing answer will be discarded.
For example, assume that you have three endpoints: Endpoint A, Endpoint B, and Endpoint C. You set the latency threshold to 50%. Endpoint A has a response time of 160ms, Endpoint B has a response time of 110ms, and Endpoint C has a response time of 100ms. Of these three endpoints, Endpoint A is dropped, because it had a higher latency. Endpoints B and C are passed along in the order that they were passed into the filter.
Use other filters, such as geographic filters or shuffle filters before this filter as a fallback to adequately balance traffic.
Set the stabilization threshold in the filter definition. If you want to set a different threshold for an answer, define it in the answer metadata.
The Pulsar Performance Stabilize filter requires the pulsar input metadata field, which is a custom data structure. It must be a dictionary, nested inside a list. You can find the fields of the dictionary above.
Copy CodeDefine a Pulsar Performance Stabilize filter and its configuration for a record
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":":zone","domain":":child_domain","type":":type","answers":[{"answer":["9.9.9.9"],"meta":{"pulsar":["job_id":":job_id"]}}],"filters":[{"filter":"pulsar_performance_stabilize", "config": {"stabilization_threshold": ":threshold_value"}]}]' https://api.nsone.net/v1/zones/:zone/:domain/:record_type
Example Request:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.example.com","type":"A", "answers":[{"answer":["1.1.1.1"],"meta":{"country":["US"],"pulsar":["job_id": "1uxw9ir"]},{"answer":["9.9.9.9"],"meta":{"country":["CA"],"pulsar":["job_id": "1uxxo37"]}}],"filters":[{“geotarget_country”},{"filter":"pulsar_performance_stabilize", "config": {"stabilization_threshold": "10"}]}]' https://api.nsone.net/v1/zones/example.com/pulsar.example.com/A
| Parameter | Type | Description |
|---|---|---|
| sort_descending | boolean | If enabled, the filter bases the cutoff on the best-performing answer instead of the worst, then removes all answers below that cutoff instead of above. The cutoff will be the Pulsar value of the best answer, minus whatever amount is specified by the stabilization_threshold, instead of adding. The default value is false. |
| stabilization_threshold | string | Required. Specifies a threshold above or below the percentage that you specify. |
Pulsar Availability Threshold
NOTE
You should set up a proper fallback strategy to ensure that other filters in NS1’s Filter Chain can intelligently route traffic when there isn’t sufficient performance telemetry. You should set up your Filter Chain to include these filters before each Pulsar filter. For example, you could include any of the geotarget filters to fall back on a geotargeting strategy. If you are distributing traffic across endpoints like CDNs or distributing traffic across a geographically dispersed infrastructure, use the shuffle or cost filters to better balance the lowest-cost traffic across your endpoints.
The following parameter is common to all of the Pulsar availability filters:
| Parameter | Type | Description |
|---|---|---|
| job_id | string | Required. The ID of the Pulsar job to be associated with this record. |
The Pulsar Availability Threshold filter determines which answers have the best availability based on a specified threshold. Answers with the most availability (based on a defined availability threshold) are kept. Answers that do not meet this stabilization threshold are removed. The availability threshold that you set is the value used to determine which answers should be removed.
For example, assume that you have three endpoints (Endpoint A, Endpoint B, and Endpoint C). You set the threshold to 95%. Endpoint A has an availability of 90%, Endpoint B has an availability of 97%, and Endpoint C has an availability of 100%. Endpoint A will be removed, because it’s available less than 95% of the time. Endpoints B and C are passed through in the existing order they were passed into this filter.
If there is not enough availability data, possible answers are passed through unchanged, and fallback logic is used. In these instances, the query is then marked as having “insufficient data” and is added to the associated category within Pulsar’s reporting dashboard. To learn more about insufficiency reporting, click here and scroll to the Decisions header. To retrieve decision insufficiencies via API, visit the NS1 API Documentation endpoint.
Use other filters, such as geographic filters or shuffle filters before this filter as a fallback to adequately balance traffic.
Set the threshold in the filter definition. If you want to define different thresholds for answers, set the threshold for each answer in the answer metadata.
The Pulsar Availability Threshold filter requires the pulsar input metadata field, which is a custom data structure. It always must be a dictionary, nested inside a list. The dictionary is defined above.
Copy CodeDefine a Pulsar Availability Threshold filter for an answer
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":":zone","domain":":child_domain","type":":record_type", "answers":[{"answer":["9.9.9.9"],”meta”:{"pulsar":["job_id": ":job_id"]}}],"filters":[{"filter":"pulsar_availability_threshold","config": {"threshold":":threshold_value"}]}]' https://api.nsone.net/v1/zones/:zone/:domain/:record_type
Example Request:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone":"example.com","domain":"pulsar.example.com","type":"A", "answers":[{"answer":["1.1.1.1"],”meta”:{"pulsar":["job_id": "1uxw9ir"]},{"answer":["9.9.9.9"],”meta”:{"pulsar":["job_id": "1uxxo37"]}}],"filters":[{“filter”: “shuffle”:}{"filter":"pulsar_availability_threshold","config": {”threshold”:”0.95”}]}]' https://api.nsone.net/v1/zones/example.com/pulsar.example.com/A
| Parameter | Type | Description |
|---|---|---|
| threshold | string | Required. Specifies a threshold above or below the percentage that you specify. |
Additional Metadata
Passes along metadata as TXT records in the additional section of the DNS response.
You can use the additional_metadata metatype within the meta object to include additional information (key-value pairs) for DNS responses as TXT records.
The Additional Metadata filter has no effect on traffic steering. Use it for system troubleshooting, organization, and more.
IMPORTANT
If you are configuring multiple filters, you must place the additional_metadata filter last in the Filter Chain. If you do not do this, the order of the TXT records that are returned might not match the order of the answers in the DNS response.
Path Parameters
Parameter | Type | Description |
|---|---|---|
| zone | string | Required. Name of the zone within which this record is located (for example, example.com). |
| domain | string | Required. Domain name (for example, www.example.com). |
| type | string | Required. The type of record whose details you are requesting (for example, A). |
Configuration Options
| Option | Type | Description |
|---|---|---|
| answer1 | string | Required. Answer for which the additional metadata should be applied. |
| key1 | string | The key that should be included as a TXT record in a DNS response (for example, "foo"). |
| value1 | string | The value that should be included as a TXT record in a DNS response (for example, "bar"). |
IMPORTANT
If you have configured decisions over HTTP, you must specify additional metadata within the meta object. An example of how this is done is displayed in the following request:
$ curl -s -H "X-NSONE-Key: $API_KEY" -H "X-Forwarded-For:192.0.2.1" 'https://rt.ns1p.net/v1/decision?name=test.example.com&type=CNAME' | jq .
{
"resources": [
{
"label": "answer1.test.com",
"meta": {
"baz": "blarg",
"foo": "bar"
}
},
{
"label": "answer2.test.com",
"meta": {
"red": "blue"
}
}
],
"ttl": 3600
}
Copy CodeUpdating an existing answer to include additional metadata
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' https://api.nsone.net/v1/zones/{zone}/{domain}/{type} -d '{ "answers": [{"answer": ["{answer1}"],"meta": {"additional_metadata": [{"{key1}": "{value1}"]}}],"filters": [{"filter": "additional_metadata","config": {}}]}'
Example Request:
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' \
https://api.nsone.net/v1/zones/example.com/test.example.com/CNAME \
-d '{
"answers": [
{
"answer": [
"answer1.test.com"
],
"meta": {
"additional_metadata": [
{
"foo": "bar",
"baz": "blarg"
}
]
}
},
{
"answer": [
"answer2.test.com"
],
"meta": {
"additional_metadata": [
{
"red": "blue"
}
]
}
}
],
"filters": [
{
"filter": "additional_metadata",
"config": {}
}
]
}'
Example Response:
$ dig @dns1.p01.nsone.net test.example.com ; <<>> DiG 9.10.6 <<>> @dns1.p01.nsone.net test.example.com ; (1 server found) ;; global options: +cmd ;; Got answer: ;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1750 ;; flags: qr aa rd; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 5 ;; WARNING: recursion requested but not available ;; OPT PSEUDOSECTION: ; EDNS: version: 0, flags:; udp: 1232 ;; QUESTION SECTION: ;test.example.com. IN CNAME ;; ANSWER SECTION: test.example.com. 3600 IN CNAME answer1.test.com. test.example.com. 3600 IN CNAME answer2.test.com. ;; ADDITIONAL SECTION: 0.meta._ns1. 0 IN TXT "baz=blarg" 0.meta._ns1. 0 IN TXT "foo=bar" 1.meta._ns1. 0 IN TXT "red=blue" ;; Query time: 13 msec ;; SERVER: 198.51.44.1#53(198.51.44.1) ;; WHEN: Thu Sep 16 15:54:04 GMT 2021 ;; MSG SIZE rcvd: 189
Monitoring & Notifications
Monitoring Jobs
GET /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.
Copy CodeReturns a list of all monitoring jobs
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/monitoring/jobs
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 /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 overall 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.
Path parameter:
| jobID | string | (Required) Unique identifier for the monitoring job |
Request URL:
https://api.nsone.net/v1/monitoring/jobs/:jobid
Example URL:
https://api.nsone.net/v1/monitoring/jobs/52cae678830f7809ec5c9f6b
Example Response:
{
"notes": null,
"name": "example.com:80",
"notify_repeat": 0,
"id": "52cae678830f7809ec5c9f6b",
"region_scope": "fixed",
"rapid_recheck": false,
"frequency": 30,
"job_type": "tcp",
"notify_delay": 0,
"notify_list": null,
"notify_regional": false,
"regions": [
"ams"
],
"policy": "quorum",
"config": {
"send": "HEAD / HTTP/1.0\r\n\r\n",
"port": 80,
"host": "1.2.3.4",
"ssl": "0",
"ipv6": false
},
"status": {
"ams": {
"since": 1389052665,
"status": "down"
},
"global": {
"since": 1389052665,
"status": "down"
}
},
"notify_failback": true,
"rules": [
{
"value": "200 OK",
"key": "output",
"comparison": "contains"
}
],
"active": true
}
PUT /v1/monitoring/jobs
PUT Create a new monitoring job
Creates a new HTTP/S, PING, TCP, or DNS monitoring job.
Request body parameters:
| name | string | Name of the monitoring job (for internal reference only) |
| active | boolean | Indicates whether or not the job is actively running or temporarily disabled. |
| mute | boolean | Set to true to stop up/down notifications related to this monitor. Note that enabling this option does not deactivate the monitor, it just stops the alerts. If enabled, you can still view the history of up/down events. |
| region_scope | string | Controls the behavior of how the job is assigned to monitoring regions. Currently, this must be set to fixed so that monitoring regions are explicitly defined. |
| regions | array of strings | List of region codes in which to run the monitoring job. Available monitoring regions are provided by the /v1/monitoring/regions endpoint. the number of regions you can apply depends on your account type and billing plan. |
| job_type | string | Indicates the type of monitoring job you are creating. A full list of available types is returned by the /monitoring/jobtypes endpoint, but can include http, ping, tcp, and dns. |
| frequency | integer | Number indicating 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 | boolean | Upon any apparent status change, the job is quickly re-run after one second to confirm the state change before sending the notification. |
| policy | string | Policy for determining the monitor's global status based on the job status in all regions. May be the quorum (majority status), all (status change only when all regions are in agreement), or one (down if any region is down). Enum: "quorum", "all", "one" |
| notes | string or null | Internal notes to be included in any notifications about this job (e.g., instructions for operators who will receive the notifications) |
| config | object | A set of configuration details in the form of key-value pairs. Supported properties depend on the type of job you are creating and can be viewed by executing a GET command to /v1/monitoring/jobtypes. |
| rules | array of objects | 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 output), and value (the value by which to compare). For example, {"key":"rtt", "comparison":"<", "value":100} indicates a rule requiring the rtt from a job to be under 100ms or it will be marked as failed. Available output keys, comparators, and value types are indicated by /monitoring/jobtypes. |
| key | string | (Part of rules object array) Output key (e.g., "rtt") |
| comparison | string | (Part of rules object array) Enum: "<", ">", "<=",">=","==","!=","regex", or "contains". |
| value | any | (Part of rules object array) Value by which to compare |
| notify_delay | integer | 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 | integer | Time (in seconds) between repeat notifications of a failed job. Set to 0 to disable repeating notifications. Otherwise, the value must be at least 60 (i.e., After 60 seconds, the notification will repeat.). |
| notify_fallback | 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) |
| notify_list | string or null | ID of the associated NS1 notification list. If no list is specified, no notifications are sent for this job. |
Copy CodeCreate a new ping monitor
curl -X PUT -H "X-NSONE-Key: $API_KEY" -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 monitor
curl -X PUT -H "X-NSONE-Key: $API_KEY" -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 /v1/monitoring/jobs/:jobid
POST Edit 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.
Path parameters:
| jobID | string | (Required) Unique identifier for the monitoring job you are updating |
Request body parameters:
Refer to "Create a monitoring job" endpoint (PUT v1/monitoring/jobs) for request body parameters.
Request URL:
https://api.nsone.net/v1/monitoring/jobs/:jobid
Example URL:
https://api.nsone.net/v1/monitoring/jobs/52cc79123db8711b6713554a
Example Request:
{
"notes": "Some new notes for this job",
"policy": "all",
"frequency": 40
}
Example Response:
{
"status": {
"global": {
"since": 1389458558,
"status": "pending"
}
},
"notes": "Some new notes for this job",
"policy": "all",
"frequency": 40,
"regions": [
"lga",
"sjc"
],
"region_scope": "fixed",
"active": true,
"rapid_recheck": false,
"name": "myhost.com:443 monitor",
"job_type": "tcp",
"config": {
"ssl": "1",
"send": "HEAD / HTTP/1.0\r\n\r\n",
"port": 443,
"host": "1.2.3.4"
},
"rules": [
{
"value": "200 OK",
"comparison": "contains",
"key": "output"
},
{
"value": 200,
"comparison": "<=",
"key": "connect"
}
],
"notify_delay": 65,
"notify_repeat": 0,
"notify_failback": true,
"notify_regional": false,
"notify_list": "52cc775a2db1561b55135327",
"id": "52cc79123db8711b6713554a"
}
DELETE /v1/monitoring/jobs/:jobid
DELETE Delete a monitoring job
Immediately terminates and deletes an existing monitoring job. There is no response other than the HTTP status code.
Path parameters:
| jobID | string | (Required) Unique identifier for the monitoring job |
Copy CodeDeletes the specified monitoring job using the jobID
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/monitoring/jobs/:jobid
Request URL:
https://api.nsone.net/v1/monitoring/jobs/:jobid
Example URL:
https://api.nsone.net/v1/monitoring/jobs/52cc79123db8711b6713554a
GET /v1/monitoring/history/:jobid
GET View history of monitoring jobs
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.
Path parameters:
| jobID | string | (Required) Unique identifier for the monitoring job whose history you are requesting |
Query parameters:
| exact | boolean | If set to true, the exact start and end times are computed and returned as part of the status history |
| period | string | Indicates a specific time period for the historical results you are requesting. Enum: "1h", "24h","30d" |
| limit | integer | Maximum number of results to return |
| start | integer | Absolute start time in UNIX timestamp |
| end | integer | Absolute end time in UNIX timestamp (defaults to current time) |
| region | string | Region code (e.g, "global") |
Copy CodeReturns job history for the specified job over the last 24 hours
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/monitoring/history/{jobid}?period=24h
GET /v1/monitoring/metric
GET View historical metrics for all jobs
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 type (http, ping, tcp, dns). 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 any applied query parameters.
Path parameters:
| jobID | string | (Optional) Unique identifier for the monitoring job. If entered, only the metrics for the specified job are returned. Otherwise, all historical job metrics are returned. |
Query parameters:
| region | string | (Optional) Region code; may be "global" or a specific region as listed in the /monitoring/regions endpoint. Note that you can only specify this parameter if you have also specified a jobID. Only metrics from the specific region are returned. If set to "global", the average value of the metric across all active regions is returned. |
| metric | string | (Optional) Metric name (e.g., "rtt" or "connect"). Valid metric names are described by the /monitoring/jobtypes endpoint and vary based on the type of monitoring job. Only the metrics for jobs providing a matching metric name are returned. |
| period | string | Enum: "1h", "24h", or "30d"; The interval of time for which to return results. Response is a list of metric objects, each containing jobID, region, and metric fields. The metric field is a mapping of metric names to statistics objects including the average value of the metric over the specified period (excluding times when no data was collected) and a graph for the metric over the period. |
Copy CodeReturns historical metrics for the specific job over the last 30 days
https://api.nsone.net/v1/monitoring/metric/{jobID}?period=30d
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
],
...
]
}
}
}
]
GET /v1/monitoring/jobtypes
GET List monitoring job types
Returns the list of all available monitoring jobs types, and details of configuration options for each job type. Job types include http, ping, tcp, and dns.
Request URL:
https://api.nsone.net/v1/monitoring/jobtypes
Example Response:
{
"http": {
"shortdesc": "HTTP",
"config": {
"url": {
"shortdesc": "URL",
"desc": "URL to query. i.e. https://ns1.com",
"required": true,
"type": "string",
"validator": "text"
},
"method": {
"default": "GET",
"required": false,
"validator": "text",
"shortdesc": "HTTP Method",
"type": "string",
"desc": "Valid methods are HEAD, GET and POST"
},
"idle_timeout": {
"default": 3,
"required": false,
"validator": "number",
"shortdesc": "Idle Timeout",
"type": "number",
"desc": "Timeout (in seconds) waiting for expected data before closing the connection."
},
"user_agent": {
"default": "NS1 HTTP Monitoring Job",
"required": false,
"validator": "text",
"shortdesc": "User Agent",
"type": "string",
"desc": "Describes the text provided in the User-Agent request header. String escapes (e.g. \"\\n\") are allowed."
},
"ipv6": {
"default": false,
"required": false,
"validator": "checkbox",
"shortdesc": "Connect over IPv6",
"type": "checkbox",
"desc": "Attempt to send/receive protocol data via IPv6"
},
"connect_timeout": {
"default": 5,
"required": false,
"validator": "number",
"shortdesc": "Connection Timeout",
"type": "number",
"desc": "Timeout (in seconds) sending query to wait for output."
},
"authorization": {
"default": null,
"required": false,
"validator": "text",
"shortdesc": "Authorization Header",
"type": "string",
"desc": "You can provide a bearer token or api key using this header. String escapes (e.g. \"\\n\") are allowed."
}
},
"results": {
"body": {
"default": "",
"type": "string",
"metric": false,
"validator": "string",
"shortdesc": "HTTP Response Body",
"comparators": [
"contains"
],
"desc": "String match over the response body."
},
"status_code": {
"comparators": [
"<",
">",
"<=",
">=",
"==",
"!="
],
"metric": false,
"validator": "number",
"shortdesc": "HTTP Status Code",
"type": "integer",
"desc": "HTTP Response Status Code comparison"
}
},
"desc": "Do an HTTP request against a webserver."
},
"ping": {
"shortdesc": "Ping (ICMP)",
"config": {
"count": {
"default": 4,
"required": false,
"validator": "number",
"shortdesc": "Number of packets to send",
"type": "number",
"desc": "Number of ICMP echo packets to send. More take longer, but provide better RTT and packet loss statistics."
},
"host": {
"shortdesc": "IP address or hostname to ping",
"desc": "IP address or hostname to test using ICMP echo packets.",
"required": true,
"type": "string",
"validator": "text"
},
"interval": {
"default": 0,
"required": false,
"validator": "number",
"shortdesc": "Time between packets",
"type": "number",
"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."
},
"timeout": {
"default": 2000,
"required": false,
"validator": "number",
"shortdesc": "Ping timeout",
"type": "number",
"desc": "Timeout (in ms) before we mark host failed."
},
"ipv6": {
"default": false,
"required": false,
"validator": "checkbox",
"shortdesc": "Connect over IPv6",
"type": "checkbox",
"desc": "Attempt to send/receive protocol data via IPv6"
}
},
"results": {
"rtt": {
"comparators": [
"<",
">",
"<=",
">=",
"==",
"!="
],
"metric": false,
"validator": "number",
"shortdesc": "Round trip time",
"type": "number",
"desc": "Average round trip time (in ms) of returned pings."
},
"loss": {
"comparators": [
"<",
">",
"<=",
">=",
"==",
"!="
],
"metric": false,
"validator": "number",
"shortdesc": "Percent packet loss",
"type": "number",
"desc": "Percentage of ICMP echo packets with no response (timed out)."
}
},
"desc": "Ping a host using ICMP packets."
},
"tcp": {
"shortdesc": "TCP",
"config": {
"response_timeout": {
"default": 1000,
"required": false,
"validator": "number",
"shortdesc": "Response timeout",
"type": "number",
"desc": "Timeout (in ms) after connecting to wait for output."
},
"send": {
"default": null,
"required": false,
"validator": "text",
"shortdesc": "String to send",
"type": "string",
"desc": "A string to send to the host upon connecting. String escapes (e.g. \"\\n\") are allowed."
},
"port": {
"shortdesc": "TCP port",
"desc": "TCP port to connect to on host.",
"required": true,
"type": "number",
"validator": "number"
},
"ssl": {
"default": false,
"required": false,
"validator": "checkbox",
"shortdesc": "Connect with SSL",
"type": "checkbox",
"desc": "Attempt to negotiate an SSL connection before sending/receiving protocol data."
},
"host": {
"shortdesc": "IP address or hostname",
"desc": "IP address or hostname to connect to.",
"required": true,
"type": "string",
"validator": "text"
},
"ipv6": {
"default": false,
"required": false,
"validator": "checkbox",
"shortdesc": "Connect over IPv6",
"type": "checkbox",
"desc": "Attempt to send/receive protocol data via IPv6"
},
"connect_timeout": {
"default": 2000,
"required": false,
"validator": "number",
"shortdesc": "Connect timeout",
"type": "number",
"desc": "Timeout (in ms) before we give up trying to connect."
}
},
"results": {
"output": {
"comparators": [
"contains"
],
"metric": false,
"validator": "string",
"shortdesc": "Output (if any)",
"type": "string",
"desc": "Output received from the connection, if any."
},
"connect": {
"comparators": [
"<",
">",
"<=",
">=",
"==",
"!="
],
"metric": false,
"validator": "number",
"shortdesc": "Time to connect",
"type": "number",
"desc": "Time (in ms) for the connection to open."
}
},
"desc": "Connect to a TCP port on a host."
},
"dns": {
"shortdesc": "DNS",
"config": {
"response_timeout": {
"default": 2000,
"required": false,
"validator": "number",
"shortdesc": "Response timeout",
"type": "number",
"desc": "Timeout (in ms) after sending query to wait for output."
},
"domain": {
"shortdesc": "Query domain",
"desc": "The domain name to query.",
"required": true,
"type": "string",
"validator": "text"
},
"host": {
"shortdesc": "Nameserver IP or hostname",
"desc": "IP address or hostname of the nameserver to query, e.g. 8.8.8.8.",
"required": true,
"type": "string",
"validator": "text"
},
"ipv6": {
"default": false,
"required": false,
"validator": "checkbox",
"shortdesc": "Connect over IPv6",
"type": "checkbox",
"desc": "Attempt to send/receive protocol data via IPv6"
},
"type": {
"default": "A",
"required": false,
"validator": "rectype",
"shortdesc": "Query type",
"type": "string",
"desc": "DNS record type to query."
},
"port": {
"default": 53,
"required": false,
"validator": "number",
"shortdesc": "DNS port",
"type": "number",
"desc": "DNS port to query on host."
}
},
"results": {
"rtt": {
"comparators": [
"<",
">",
"<=",
">=",
"==",
"!="
],
"metric": false,
"validator": "number",
"shortdesc": "Response time",
"type": "number",
"desc": "Average response time (in ms) of DNS responses."
},
"num_records": {
"comparators": [
"<",
">",
"<=",
">=",
"==",
"!="
],
"metric": false,
"validator": "number",
"shortdesc": "Number of records",
"type": "number",
"desc": "Number of records in the ANSWER section of the DNS response."
},
"rdata": {
"comparators": [
"contains"
],
"metric": false,
"validator": "string",
"shortdesc": "Record RDATA",
"type": "string",
"desc": "RDATA of records in the DNS response."
}
},
"desc": "Do a DNS lookup against a nameserver host."
}
}
GET /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.
Copy CodeReturns a list of all available monitoring regions for the account
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/monitoring/regions
Request URL:
https://api.nsone.net/v1/monitoring/regions
Example Response:
[
{
"name": "Dallas",
"code": "dal",
"subnets": [
"192.0.2.40/29",
"2001:db8:4009:3::/64"
]
},
{
"name": "Singapore",
"code": "sin",
"subnets": [
"198.51.100.224/29",
"2001:db8:1000:3::/64"
]
},
{
"name": "San Jose",
"code": "sjc",
"subnets": [
"192.0.2.152/29",
"2001:db8:400c:3::/64"
]
},
{
"name": "New York",
"code": "lga",
"subnets": [
"203.0.113.16/29",
"2001:db8:4004:3::/64"
]
},
{
"name": "Amsterdam",
"code": "ams",
"subnets": [
"203.0.113.48/29",
"2001:db8:e:3::/64"
]
}
]
Notification lists
GET https://api.nsone.net/v1/lists
GETList all notification lists
Returns all configured notification lists. Each list consists of a name, an id for use in connecting notification lists in monitoring jobs, and a notify_list of configured notifiers.
Request URL:
https://api.nsone.net/v1/lists
Example Response:
[
{
"id": "52b49af12f21574b0e0bffe7",
"name": "Awesome List",
"notify_list": [
{
"type": "email",
"config": {
"email": "[email protected]"
}
},
{
"type": "datafeed",
"config": {
"sourceid": "5872814cc08b23c697e88c054d032780"
}
},
{
"type": "user",
"config": {
"user": "myuser"
}
}
]
},
...
]
GET https://api.nsone.net/v1/lists/:listid
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 protected]"
}
},
{
"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":"[email protected]"}}, {"type":"datafeed", "config":{"sourceid":"b85579edee904f0f204a6eb07b3f8a1f"}} ]}' https://api.nsone.net/v1/lists
We create a new list to receive monitoring notifications. Notifications will be sent to both an email address ([email protected]) and to an NSONE Data Source for use with NSONE's DNS metadata. To connect a datafeed notifier, the sourceid must be a nsone_monitoring Data Source. Status changes for monitors connected to this notification list will be delivered to the Data Source, and if a Data Feed is configured under the source for the monitor, then the changes will be pushed to all metadata tables connected to the Data Feed.
Request URL:
https://api.nsone.net/v1/lists
Example Request:
{
"name": "My Notification List",
"notify_list": [
{
"config": {
"email": "[email protected]"
},
"type": "email"
},
{
"config": {
"user": "myuser"
},
"type": "user"
},
{
"config": {
"sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
},
"type": "datafeed"
}
]
}
Example Response:
{
"id": "52b49af12f21574b0e0bffe8",
"name": "My Notification List",
"notify_list": [
{
"config": {
"email": "[email protected]"
},
"type": "email"
},
{
"config": {
"user": "myuser"
},
"type": "user"
},
{
"config": {
"sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
},
"type": "datafeed"
}
]
}
POST https://api.nsone.net/v1/lists/:listid
POSTUpdate a notification list
Add or remove entries or otherwise update a notification list.
Request URL:
https://api.nsone.net/v1/lists/:listid
Example URL:
https://api.nsone.net/v1/lists/52b49af12f21574b0e0bffe8
Example Request:
{
"id": "52b49af12f21574b0e0bffe8",
"name": "My Notification List",
"notify_list": [
{
"config": {
"email": "[email protected]"
},
"type": "email"
},
{
"config": {
"user": "myuser"
},
"type": "user"
},
{
"config": {
"sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
},
"type": "datafeed"
},
{
"config": {
"email": "[email protected]"
},
"type": "email"
}
]
}
Example Response:
{
"id": "52b49af12f21574b0e0bffe8",
"name": "My Notification List",
"notify_list": [
{
"config": {
"email": "[email protected]"
},
"type": "email"
},
{
"config": {
"user": "myuser"
},
"type": "user"
},
{
"config": {
"sourceid": "01f6495ba8eb9d3ac40963db97ab5604"
},
"type": "datafeed"
},
{
"config": {
"email": "[email protected]"
},
"type": "email"
}
]
}
| 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"
},
...
}
Reporting & Statistics
QPS
GET /v1/stats/qps
GET View account-wide QPS
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 /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/...’]), 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.
Query parameters
| Parameter | Type | Description |
| period | enum(string) | (Optional) Relative time. Possible values: ‘1h’, ‘24h’, ‘30d’ (default: ‘24h’) |
| expand | boolean | (Optional) 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 will include a standard HTTP Link header that will include after and limit query parameters. The URI in the link header may be used to fetch the next page of results. |
| networks | string | (Optional) Identifier of the network for which you want to return usage statistics. Default is * which returns the number of DNS queries for all networks combined (e.g. Managed and Dedicated networks). Other supported values include the network ID, such as 0 for NS1 Managed DNS. Note that network IDs for DDI networks are defined during initial configuration, and those for Dedicated DNS are provided to you by the NS1 support team during implementation. |
| after | string | (Optional) Appears in paginated responses as part of the URI-reference component of the Link header. The value is the zone after which the next page should begin. If expand is not set to true, this param is ignored. |
| limit | integer | (Optional) Appears in paginated responses as part of the URI-reference component of the Link header. The value indicates the maximum number of expanded zones that should appear in the response (Default: 1000; Max value: 1000). If expand is not set to true, this parameter is ignored. |
Copy CodeGet account-wide zone usage for last 24 hours for all networks
curl -X GET -H 'X-NSONE-Key: $API_KEY' "https://api.nsone.net/v1/stats/usage?period=24h&networks=*"
Request URL:
https://api.nsone.net/v1/stats/usage?period=24h&expand=true&networks=0,9
GET /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.
Parameter | Type | Description | Required? |
zone | string | Name of the zone | yes |
period | enum(string) | Relative time. Possible values: '1h', '24h', '30d' (Default: '24h') | no |
| expand | boolean | Used to set return aggregated stats across all zones. Possible values true or false (default: false). Default value is “true.” If set to true, the response includes aggregated statistics across all records. Note about pagination: If you have more than 1,000 records expanded, the response will include a standard HTTP Link header that will include after and limit query parameters. The URI in the link header may be used to fetch the next page of the results. | no |
networks | string | Identifier of the network for which you want to return usage statistics. Default is * which returns the number of DNS queries for all networks combined (e.g. Managed and Dedicated networks). Other supported values include the network ID, such as 0 for NS1 Managed DNS. Note that network IDs for DDI networks are defined during initial configuration, and those for Dedicated DNS are provided to you by the NS1 support team during implementation. | no |
| after | string | Appears in paginated responses as part of the URI-reference component of the Link header. The value is the zone after which the next page should begin. If expand is not set to true, this param is ignored. | no |
| limit | integer | Appears in paginated responses as part of the URI-reference component of the Link header. The value indicates the maximum number of expanded zones that should appear in the response (Default: 1000; Max value: 1000). If expand is not set to true, this param is ignored. | no |
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&expand=false&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. 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 /v1/stats/usage/:zone/:domain/:type
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.
| Parameter | Type | Description |
| zone | string | (Required) Name of the zone (usually the FQDN). |
| domain | string | (Required) Domain name. |
| type | string | (Required) Type of record for which you are requesting usage statistics. |
| period | string (enum) | Relative amount of time. Enum: '1h', '24h', '30d' (Default: '24h') |
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
],
...
]
}
]
Lease stats
GET /v1/stats/leases
GETView account-wide lease statistics
Returns the sum of all leases — new and renewals — for the entire account. You can export this report with the export path parameter.
Query Parameters:
| Parameter | Type | Description |
| period | string (enum) | Filters the results to include only lease information related to a specified period of time prior to the current timestamp. Supported values: 24h (default) or 30d. |
| export | string | The file type of the report that should be generated. Can be one of the following file types: json, xml, csv, pdf, xslx, or html. |
Copy CodeReturns lease statistics for the past 24 hours
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/stats/leases?period=24h
Copy CodeExports lease report in PDF format
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/stats/leases?export=pdf
Returns a sum of all leases — new and renewals — and graphs for the specified scope group. You can export this report with the export path parameter.
Example Response:
[
{
"graph": [
[
1600086600,
0
],
[
1600088400,
0
],
[
1600090200,
0
],
[
1600092000,
0
],
[
1600093800,
0
],
[
1600095600,
0
],
[
1600097400,
0
],
[
1600099200,
0
],
[
1600101000,
0
],
[
1600102800,
0
],
[
1600104600,
0
],
[
1600106400,
0
],
[
1600108200,
0
],
[
1600110000,
0
],
[
1600111800,
0
],
[
1600113600,
0
],
[
1600115400,
0
],
[
1600117200,
0
],
[
1600119000,
0
],
[
1600120800,
0
],
[
1600122600,
0
],
[
1600124400,
0
],
[
1600126200,
0
],
[
1600128000,
0
],
[
1600129800,
0
],
[
1600131600,
0
],
[
1600133400,
0
],
[
1600135200,
0
],
[
1600137000,
0
],
[
1600138800,
0
],
[
1600140600,
0
],
[
1600142400,
0
],
[
1600144200,
0
],
[
1600146000,
0
],
[
1600147800,
0
],
[
1600149600,
0
],
[
1600151400,
0
],
[
1600153200,
0
],
[
1600155000,
0
],
[
1600156800,
0
],
[
1600158600,
0
],
[
1600160400,
0
],
[
1600162200,
0
],
[
1600164000,
0
],
[
1600165800,
0
],
[
1600167600,
0
],
[
1600169400,
0
],
[
1600171200,
4
],
[
1600173000,
1
]
],
"period": "24h",
"leases": 5
}
]
GET /v1/stats/leases/:scopeGroupID
GETView lease statistics by scope group
Returns a sum of all leases — new and renewals — and graphs for the specified scope group. You can export this report with the export path parameter.
Path Parameters:
| Parameter | Type | Description |
| scopeGroupID | integer | (Required) Unique identifier for the scope group. |
Query Parameters:
| Parameter | Type | Description |
| period | string (enum) | Filters the results to include only lease information related to a specified period of time prior to the current timestamp. Supported values: 24h (default) or 30d. |
| export | string | The file type of the report that should be generated. Can be one of the following file types: json, xml, csv, pdf, xslx, or html. |
Copy CodeReturns lease statistics within a scope group for the past 24 hours
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/stats/leases/:scopeGroupID?period=24h
Copy CodeExports a lease statistics report in PDF format
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/stats/leases?export={type}
Example Response:
[
{
"graph": [
[
1600086600,
0
],
[
1600088400,
0
],
[
1600090200,
0
],
[
1600092000,
0
],
[
1600093800,
0
],
[
1600095600,
0
],
[
1600097400,
0
],
[
1600099200,
0
],
[
1600101000,
0
],
[
1600102800,
0
],
[
1600104600,
0
],
[
1600106400,
0
],
[
1600108200,
0
],
[
1600110000,
0
],
[
1600111800,
0
],
[
1600113600,
0
],
[
1600115400,
0
],
[
1600117200,
0
],
[
1600119000,
0
],
[
1600120800,
0
],
[
1600122600,
0
],
[
1600124400,
0
],
[
1600126200,
0
],
[
1600128000,
0
],
[
1600129800,
0
],
[
1600131600,
0
],
[
1600133400,
0
],
[
1600135200,
0
],
[
1600137000,
0
],
[
1600138800,
0
],
[
1600140600,
0
],
[
1600142400,
0
],
[
1600144200,
0
],
[
1600146000,
0
],
[
1600147800,
0
],
[
1600149600,
0
],
[
1600151400,
0
],
[
1600153200,
0
],
[
1600155000,
0
],
[
1600156800,
0
],
[
1600158600,
0
],
[
1600160400,
0
],
[
1600162200,
0
],
[
1600164000,
0
],
[
1600165800,
0
],
[
1600167600,
0
],
[
1600169400,
0
],
[
1600171200,
4
],
[
1600173000,
1
]
],
"period": "24h",
"scope_group_id": 1,
"leases": 5
}
]
GET /v1/stats/lps
GETView account-wide peak LPS
Returns current leases per second (LPS) for all scope groups. Optionally, you can specify a period of time by which to filter results.
Peak LPS is the maximum number of average leases calculated at 30-minute intervals in a 24-hour period and at 12-hour intervals in a 30-day period.
- 90th percentile markers: shows 90% of the time, the usage is below this amount
- 95th percentile markers: shows 95% of the time, the usage is below this amount
You can export this report with the export path parameter.
Query Parameters:
| Parameter | Type | Description |
| period | string (enum) | Filters the results to include only lease information related to a specified period of time prior to the current timestamp. Supported values: 24h (default) or 30d. |
| export | string | The file type of the report that should be generated. Can be one of the following file types: json, xml, csv, pdf, xslx, or html. |
Copy CodeReturns LPS statistics for the past 24 hours
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/stats/lps?period=24h
Copy CodeExports LPS statistics report in PDF format
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/stats/lps?export=PDF
Example Response:
[
{
"graph": [
[
1600086600,
0
],
[
1600088400,
0
],
[
1600090200,
0
],
[
1600092000,
0
],
[
1600093800,
0
],
[
1600095600,
0
],
[
1600097400,
0
],
[
1600099200,
0
],
[
1600101000,
0
],
[
1600102800,
0
],
[
1600104600,
0
],
[
1600106400,
0
],
[
1600108200,
0
],
[
1600110000,
0
],
[
1600111800,
0
],
[
1600113600,
0
],
[
1600115400,
0
],
[
1600117200,
0
],
[
1600119000,
0
],
[
1600120800,
0
],
[
1600122600,
0
],
[
1600124400,
0
],
[
1600126200,
0
],
[
1600128000,
0
],
[
1600129800,
0
],
[
1600131600,
0
],
[
1600133400,
0
],
[
1600135200,
0
],
[
1600137000,
0
],
[
1600138800,
0
],
[
1600140600,
0
],
[
1600142400,
0
],
[
1600144200,
0
],
[
1600146000,
0
],
[
1600147800,
0
],
[
1600149600,
0
],
[
1600151400,
0
],
[
1600153200,
0
],
[
1600155000,
0
],
[
1600156800,
0
],
[
1600158600,
0
],
[
1600160400,
0
],
[
1600162200,
0
],
[
1600164000,
0
],
[
1600165800,
0
],
[
1600167600,
0
],
[
1600169400,
0
],
[
1600171200,
4
],
[
1600173000,
1
]
],
"period": "24h",
"aggregation": "peak"
}
]
GET /v1/stats/lps/:scopeGroupID
GETView peak LPS by scope group
Returns current leases per second (LPS) for the specified scope group — optionally, within the specified time range.
Peak LPS is the maximum number of average leases calculated at 30 minute intervals in a 24h period and at 12h intervals in a 30 day period for a specified scope group.
- 90th percentile markers: shows 90% of the time, the usage is below this amount.
- 95th percentile markers: shows 95% of the time, the usage is below this amount.
You can export this report with the export path parameter.
Path Parameters:
| Parameter | Type | Description |
| scopeGroupID | integer | (Required) Unique identifier for the scope group. |
| export | string | The file type of the report that should be generated. Can be one of the following file types: json, xml, csv, pdf, xslx, or html. |
Copy CodeExports report for peak LPS by scope group in PDF format
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/stats/lps/:scopeGroupID?export=pdf
Scheduled Reports
GET /v1/reporter/scheduled-reports
GETView all scheduled reports
Retrieves a list of all scheduled reports and their details.
Copy CodeReturns details about scheduled reports
$ curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/reporter/scheduled-reports
PUT /v1/reporter/scheduled-reports
PUTCreate a new scheduled report
Creates a new scheduled report. The parameters available to you will depend on the report_type that you specify.
Request Body Parameters:
| Parameter | Type | Description | ||||||||||||||||
| report_type | string | (Required) Type of scheduled report. Select from the following types:
| ||||||||||||||||
| report_name | string | Name of the scheduled report | ||||||||||||||||
| export_type | string | The file type in which reports are generated and emailed. Must be one of the following:json,csv,xml,html,xslx,pdf | ||||||||||||||||
| start_datetime | string | The ISO 8601-format date and time that the report was added to a schedule | ||||||||||||||||
| repeat | object | How often the scheduled report should be repeated, formatted as a cron expression (minutes, hours, day_of_month, month, and day_of_week are the available cron properties) | ||||||||||||||||
| end | object | When the report should stop running
| ||||||||||||||||
| emails | array of strings | The list of email addresses to which the reports should be emailed | ||||||||||||||||
| parameters | object | Parameters that are specific to certain reports. For example, for an activity log report, use this object to filter by userId, resourceType, and other supported parameters. You must include the report_type as the key for the object. For example:
”parameters”: {
“activity_log”: {
“userId”: “myuser”,
“action”: “delete”
}
}
|
Copy CodeCreates a new scheduled report
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"report_type": "network_utilization","repeat": {"minutes": 16,"hours": 11},"end": {"type": "never"},"start_datetime": "2016-10-22T08:12:01Z","report_name": "Network Utilization","emails": ["[email protected]"],"export_type": "pdf","parameters": {"network_utilization": {"networkId": 1}} } https://{api.mycompany.net}/v1/reporter/scheduled-reports
Example Request:
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{
"report_type": "network_utilization",
"repeat": {
"minutes": 16,
"hours": 11
},
"end": {
"type": "never"
},
"start_datetime": "2016-10-22T08:12:01Z",
"report_name": "Network Utilization",
"emails": ["[email protected]"],
"export_type": "pdf",
"parameters": {
"network_utilization": {
"networkId": 1
}
}
} https://{api.mycompany.net}/v1/reporter/scheduled-reports
GET /v1/reporter/scheduled-reports/:reportID
GETRetrieve a scheduled report by ID
Retrieves the details about a specific report whose ID you include. You can learn more about the report, like its name, when it was created, when it last ran, and other important data.
Path Parameters:
| Parameter | Type | Description |
| reportID | integer | Report ID number; this number is automatically generated by the system, starting at `1`. |
Copy CodeReturns details for the specified report
$ curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/reporter/scheduled-reports/:reportID
POST /v1/reporter/scheduled-reports/:reportID
POSTModify a scheduled report
Modifies the details of a scheduled report. The parameters that are required vary depending on the type of report you want to generate.
Path Parameters:
| Parameter | Type | Description |
| reportID | integer | Report ID number |
Request Body Parameters:
| Parameter | Type | Description | ||||||||||||||||
| report_type | string | (Required) Type of scheduled report. Select from the following types:
| ||||||||||||||||
| report_name | string | Name of the scheduled report | ||||||||||||||||
| export_type | string | The file type in which reports are generated and emailed. Must be one of the following:json,csv,xml,html,xslx,pdf | ||||||||||||||||
| created | string | The ISO 8601-format date and time when the report was created | ||||||||||||||||
| last_run | string | The ISO 8601-format date and time that the report last ran | ||||||||||||||||
| next_run | string | The ISO 8601-format date and time that the report is next scheduled to run | ||||||||||||||||
| start_datetime | string | The ISO 8601-format date and time that the report was added to a schedule | ||||||||||||||||
| last_status | string | Status of the last run (none, success, or fail) | ||||||||||||||||
| repeat | object | How often the scheduled report should be repeated, formatted as a cron expression (minutes, hours, day_of_month, month, and day_of_week are the available cron properties) | ||||||||||||||||
| end | object | When the report should stop running
| ||||||||||||||||
| emails | array of strings | The list of email addresses to which the reports should be emailed | ||||||||||||||||
| parameters | object | Parameters that are specific to certain reports. For example, for an activity log report, use this object to filter by userId, resourceType, and other supported parameters. You must include the report_type as the key for the object. For example:
”parameters”: {
“activity_log”: {
“userId”: “myuser”,
“action”: “delete”
}
}
|
Copy CodeEdits the specified scheduled report
curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '{"report_name": "Weekly Network Utilization Report"}' https://{api.mycompany.net}/v1/reporter/scheduled-reports/2
DELETE /v1/reporter/scheduled-reports/:reportID
DELETEDelete a scheduled report
Deletes a scheduled report based on the specified report ID. The report is deleted immediately.
Path Parameters:
| Parameter | Type | Description |
| reportID | integer | (Required) Report ID number of the report you want to delete |
Copy CodeDeletes the specified scheduled report
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/reporter/scheduled-reports/:reportID
Pulsar
Applications
A Pulsar application is a collection of jobs (resources being measured). Pulsar references the application ID (appID) to determines which jobs should record a measurement upon each impression.
GET /v1/pulsar/apps
GET List Pulsar applications
Returns all Pulsar applications in your account.
Copy CodeReturns a list of all Pulsar applications
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps
GET /v1/pulsar/apps/:appID
GET View application details
Returns details for a single Pulsar application. Specify the appID (auto-generated during app creation) in the request URL.
| Parameter | Type | Description | Required? |
| appID | String | ID of the Pulsar app | Yes |
Copy CodeReturns details for the specified Pulsar application
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/<appID>
PUT /v1/pulsar/apps
PUT Create a Pulsar application
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 a Pulsar application
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{ "name": "<string>", "active": <boo>, "browser_wait_millis": <int>, "jobs_per_transaction": <int>, "default_config": { "http": <boo>, "https": <boo>, "request_timeout_millis": <int>, "job_timeout_millis": <int>, "use_xhr": <boo>, "static_values": <boo> } }' https://api.nsone.net/v1/pulsar/apps
Example Request:
{
"name": "string",
"active": true,
"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,
"static_values": true
}
}
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 | Type | Description |
|---|---|---|
| name | string | name of the Pulsar application (ex. ACME Pulsar tag) |
| active | boolean | Indicates whether or not this application is currently active and usable for routing |
| browser_wait_millis | integer | Indicates the amount of time a browser should wait before running measurements |
| jobs_per_transaction | integer | Number of jobs to measure per user impression |
| default_config | object | Default job configuration suboptions |
| http | boolean | Indicates whether or not to use HTTP in measurements |
| https | boolean | Indicates whether or not to use HTTPS in measurements |
| request_timeout_millis | integer | Maximum timeout per request |
| job_timeoutt_millis | integer | Maximum timeout per job |
| use_xhr | boolean | Indicates whether or not to use XmlHttpRequest (XHR) when taking measurements |
| static_values | boolean | Indicates whether or not to skip aggregation for this job's measurements |
POST /v1/pulsar/apps/{appID}
POST Modify an application
Modifies the specified Pulsar application.
| Parameter | Type | Description |
| appID | string | Unique identifier for the Pulsar application |
| name | string | Descriptive name for this Pulsar app |
| active | boolean | Indicates whether or not this application is currently active and usable for traffic steering |
| browser_wait_millis | integer | The amount of time (in milliseconds) the browser should wait before running measurements |
| jobs_per_transaction | integer | Number of jobs to measure per user impression |
| default_config | object | Default job configuration. If a field is present here and not on a specific job associated with this application, the default value specified here is used. |
| http | boolean | Indicates whether or not to use HTTP in measurements |
| https | boolean | Indicates whether or not to use HTTPS in measurements |
| request_timeout_millis | integer | Maximum timeout per request |
| job_timeout_millis | integer | Maximum timeout per job |
| use_xhr | boolean | Whether to use XMLHttpRequest (XHR) when taking measurements |
| static_values | boolean | Indicates whether or not to skip aggregation for this job's measurements |
Copy CodeEdits the Pulsar application
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "name": "<string>", "active": <boo>, "browser_wait_millis": <int>, "jobs_per_transaction": <int>, "default_config": { "http": <boo>, "https": <boo>, "request_timeout_millis": <int>, "job_timeout_millis": <int>, "use_xhr": <boo>, "static_values": <boo> } } ' https://my.nsone.net/v1/pulsar/apps/{appID}
Example Request:
{
"name": "string",
"active": true,
"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,
"static_values": true
}
}
Example Response:
{
"customer": 0,
"appid": "string",
"name": "string",
"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,
"static_values": true,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
},
"community": true
}
| Parameter | Type | Description |
| appID | string | Unique identifier for the Pulsar application |
| name | string | Descriptive name for this Pulsar app |
| active | boolean | Indicates whether or not this application is currently active and usable for traffic steering |
| browser_wait_millis | integer | The amount of time (in milliseconds) the browser should wait before running measurements |
| jobs_per_transaction | integer | Number of jobs to measure per user impression |
| default_config | object | Default job configuration. If a field is present here and not on a specific job associated with this application, the default value specified here is used. |
| http | boolean | Indicates whether or not to use HTTP in measurements |
| https | boolean | Indicates whether or not to use HTTPS in measurements |
| request_timeout_millis | integer | Maximum timeout per request |
| job_timeout_millis | integer | Maximum timeout per job |
| use_xhr | boolean | Whether to use XMLHttpRequest (XHR) when taking measurements |
| static_values | boolean | Indicates whether or not to skip aggregation for this job's measurements |
DELETE /v1/pulsar/apps/{appID}
DELETE Delete a Pulsar application
Deletes a Pulsar application specified in the request URL (via appID).
Copy CodeDeletes a Pulsar application
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/{appID}
Jobs
A pulsar job measures a specific metric (e.g. latency) from a particular resource (e.g. CDN, data center, cloud, etc).
GET /v1/pulsar/apps/:appID/jobs
GETList jobs within an app
Returns a list of all Pulsar jobs in an app. A job corresponds to a resource (CDN, data center, cloud, etc.) being measured. The resource hosts an asset used to measure availability and latency. The jobID is applied to an answer within the DNS resource record.
| Parameter | Type | Description | Required? |
| appID | String | ID of the Pulsar App | Yes |
Copy CodeReturns a list of all jobs within the specified Pulsar application.
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/:appID/jobs
GET /v1/pulsar/apps/:appID/jobs/:jobID
GETView job details
Returns configuration details for the specified job via the unique jobID. You must also specify the application with which this job is associated (using the unique appID) in the request URL.
| Parameter | Type | Description | Required? |
| appID | String | ID of the Pulsar app | Yes |
| jobID | String | IF of the Pulsar job | Yes |
Copy CodeReturns details about the specified Pulsar job
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/:appID/jobs/:jobID
Example Response:
{
"customer": 0,
"appid": "string",
"jobid": "string",
"name": "string",
"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,
"static_values": true,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
}
}
| Parameter | Type | Description | Required? |
| appID | String | ID of the Pulsar app | Yes |
| jobID | String | IF of the Pulsar job | Yes |
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": "<string>", "typeid": "<string>", "active": <boo>, "shared": <boo>, "config": {"host": "<string>", "url_path": "<string>", "http": <boo>, "https": <boo>, "request_timeout_millis": <int>, "job_timeout_millis": <int>, "use_xhr": <boo>, "static_values": <boo>} }' https://api.nsone.net/v1/pulsar/apps/{appId}/jobs
Example Request:
{
"name": "string",
"typeid": "latency",
"active": true,
"shared": true,
"config": {
"host": "string",
"url_path": "string",
"http": true,
"https": true,
"request_timeout_millis": 0,
"job_timeout_millis": 0,
"use_xhr": true,
"static_values": true
}
}
Example Response:
{
"customer": 0,
"appid": "string",
"jobid": "string",
"name": "string",
"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,
"static_values": true,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
}
}
| Parameter | Type | Description |
|---|---|---|
| name | string | Name of the Pulsar job. Typically, this is the name of the CDN or endpoint |
| typeid | string | Specifies the type of Pulsar job — either latency or custom |
| active | boolean | Indicates whether or not the Pulsar job is currently active and usable for routing |
| shared | boolean | Indicates whether or not this job is visible and usable to other customers |
| config | object | Includes several sub-options related to job configuration |
| host | string | Hostname where the resource is located |
| url_path | string | URL path to be appended to the host |
| http | boolean | Indicates whether or not to use HTTP in measurements |
| https | boolean | Indicates whether or not to use HTTPS in measurements |
| request_timeout_millis | integer | Maximum timeout per request |
| job_timeout_millis | integer | Maximum timeout per request |
| use_xhr | boolean | Indicates whether or not to use XmlHttpRequest (XHR) when taking measurements |
| static_values | boolean | Indicates whether or not to skip aggregation for this job's measurements |
POST /v1/pulsar/apps/{appID}/jobs/{jobID}
POSTModify a Pulsar job
Modifies an existing Pulsar job configuration. Note that you must specify the unique jobID and the associated appID in the URL path.
Copy CodeEdits a Pulsar job
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "name": "<string>", "typeid": "<string>", "active": <boo>, "shared": <boo>, "config": {"host": "<string>", "url_path": "<string>", "http": <boo>, "https": <boo>, "request_timeout_millis": <int>, "job_timeout_millis": <int>, "use_xhr": <boo>, "static_values": <boo>} }' https://api.nsone.net/v1/pulsar/apps/{appID}/jobs/{jobID}
Example Request:
{
"name": "string",
"typeid": "latency",
"active": true,
"shared": true,
"config": {
"host": "string",
"url_path": "string",
"http": true,
"https": true,
"request_timeout_millis": 0,
"job_timeout_millis": 0,
"use_xhr": true,
"static_values": true
}
}
Example Response:
{
"customer": 0,
"appid": "string",
"jobid": "string",
"name": "string",
"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,
"static_values": true,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
}
}
| Parameter | Type | Description |
| appID | string | Unique identifier for the Pulsar application |
| jobID | string | Unique identifier for the Pulsar job (typically, this is the name of the target CDN/endpoint) |
| name | string | Descriptive name for the Pulsar job |
| typeid | string | Indicates the type of Pulsar job—either "latency" or "custom" |
| active | boolean | Indicates whether or not this Pulsar job is currently active and usable for routing |
| shared | boolean | Indicates whether or not this job is visible and usable to other customers |
| config | object | Contains several configuration options for this Pulsar job |
| host | string | Hostname where the resource being measured is located |
| url_path | string | URL path to be appended to the host |
| http | boolean | Indicates whether or not to use HTTP in measurements |
| https | boolean | Indicates whether or not to use HTTPS in measurements |
| request_timeout_millis | integer | Maximum timeout per request |
| job_timeout_millis | integer | Maximum timeout per job |
| use_xhr | boolean | Indicates whether or not to use XmlHttpRequest (XHR) in measurements |
| static_values | boolean | Indicates whether or not to skip aggregation for this job's measurements |
DELETE /v1/pulsar/apps/{appID}/jobs/{jobID}
DELETEDelete a Pulsar job
Deletes the specified Pulsar job. Note that you must include the jobID and the associated appID in the URL path.
Copy CodeDeletes the specified Pulsar job
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/{appID}/jobs/{jobID}
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
Returns historical and live data.
Note: If you receive a "400" response, ensure the start and end times do not overlap and/or that the time range is greater than 30 days.
Path Parameters:
| Parameter | Type | Description |
| appID | string | The unique ID of the Pulsar application that you are running |
| jobID | string | The unique ID of the Pulsar job that you use to collect latency or custom data |
Query Parameters:
Parameter | Type | Description |
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to a two-letter ISO code for the geographic location for which you want to filter (for example, US). |
| asn | integer | Filters results by an autonomous system number (ASN). |
| agg | string | Specifies which aggregation method to use. Possible values are: avg, max, min, p50, p75, p90, p95, and p99. Default is p50. |
Copy CodeReturns aggregated performance data
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/:appID/jobs/:jobID/data
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/1j17urd/jobs/816kab/data?start=1430032020000&end=1451433600000&period=24h&geo=US&asn=12345&agg=p95
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/1j17urd/jobs/816kab/data?start=1617670314&end=1620428400&geo=CA&asn=12345&agg=p50
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.
Path Parameters:
| Parameter | Type | Description |
| appID | string | The unique ID of the Pulsar application that you are running |
| jobID | string | The unique ID of the Pulsar job that you use to collect latency or custom data |
Query Parameters:
Parameter | Type | Description |
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to a two-letter ISO code for the geographic location for which you want to filter (for example, US). |
| asn | integer | Filters results by an autonomous system number (ASN). |
| agg | string | Specifies which aggregation method to use. Possible values are: avg, max, min, p50, p75, p90, p95, and p99. Default is p50. |
Copy CodeReturns availability data
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/:appID/jobs/:jobID/availability
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/1j17urd/jobs/816kab/availability?start=1430032020000&end=1451433600000&period=24h&geo=US&asn=12345&agg=p95
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/apps/1j17urd/jobs/816kab/availability?period=1h&geo=CA&asn=12345&agg=p50
Decisions
Allowed parameters: start, end, period, geo, asn
GET /v1/pulsar/query/decision/customer
GETView decisions for account
NOTE
As of 13 May 2021, the Pulsar team has introduced a simplified way to access decision data. See the new endpoint to learn more about the changes.
Returns total count of Pulsar decisions for the account — optionally, within a specified time range or other filter specified in the query.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both.
Query Parameters:
Parameter | Type | Description |
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to a two-letter ISO code for the geographic location for which you want to filter (for example, US). |
| asn | integer | Filters results by an autonomous system number (ASN). |
Copy CodeQueries account decisions
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer?start={start_time}&end={end_time}&geo={geography}&asn={asn}
Narrows results by start and end dates, geographical location, and ASN
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer?start={start_time}&end={end_time}&geo={geography}&asn={asn}
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer?start=1523000000&end=1523500000&geo=US&asn=12345
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer?period=1h&geo=US&asn=12345
GET /v1/pulsar/query/decision/customer/undetermined
GETView insufficient decision data for account
NOTE
As of 13 May 2021, the Pulsar team has introduced a simplified way to access decision data. See the new endpoint to learn more about the changes.
Returns total count of insufficient data where Pulsar could not make a decision — optionally, within a specified time range or other filter.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both.
Query Parameters:
Parameter | Type | Description |
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to a two-letter ISO code for the geographic location for which you want to filter (for example, US). |
| asn | integer | Filters results by an autonomous system number (ASN). |
Copy CodeReturns total count of instances of insufficient Pulsar data
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer/undetermined?start={start_time}&end={end_time}&geo={geography}&asn={asn}
Narrowed down by a start and end time, geographic region, and ASN.
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer/undetermined?start={start_time}&end={end_time}&geo={geography}&asn={asn}
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer/undetermined?start=1523000000&end=1523500000&geo=US&asn=12345
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/customer/undetermined?period=1h&geo=US&asn=12345
GET /v1/pulsar/query/decision/record/:domain/:record
GETView decisions for record
NOTE
As of 13 May 2021, the Pulsar team has introduced a simplified way to access decision data. See the new endpoint to learn more about the changes.
Returns count of Pulsar decisions per resource for a specific record.
Path Parameters:
| Parameter | Type | Description |
| domain | string | Required. Specifies the domain to which the record belongs. |
| record | string | Required. Specifies the record associated with the decision. |
Query Parameters:
Parameter | Type | Description |
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to a two-letter ISO code for the geographic location for which you want to filter (for example, US). |
| asn | integer | Filters results by an autonomous system number (ASN). |
Copy CodeRetrieves decisions for a specified record
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/record/:domain/:record?start={start_time}&end={end_time}&geo={geography}&asn={asn}
Narrows results by a start and end time, geographical location, and autonomous system number (ASN)
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/record/:domain/:record?start={start_time}&end={end_time}&geo={geography}&asn={asn}
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/www.example.com/A?start=1523000000&end=1523500000&geo=US&asn=12345
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/www.example.com/A?period=1h&geo=US&asn=12345
GET /v1/pulsar/query/decision/record/undetermined/:domain/:record
GETView insufficient decision data for record
NOTE
As of 13 May 2021, the Pulsar team has introduced a simplified way to access decision data. See the new endpoint to learn more about the changes.
Returns count of insufficient data where Pulsar could not make a decision for a specific record — optionally, within a specified time range or other filter.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both.
Path Parameters:
| domain | string | Required. Specifies the domain to which the record belongs. |
| record | string | Required. Specifies the record associated with the decision. |
Query Parameters:
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to a two-letter ISO code for the geographic location for which you want to filter (for example, US). |
| asn | integer | Filters results by an autonomous system number (ASN). |
Copy CodeReturns insufficient decision data
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/{domain}/{record}?start={start_time}&end={end_time}&geo={geography}&asn={asn}
Narrowed down to a start and end time, geographic area, and ASN.
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/www.example.com/A?start=1523000000&end=1523500000&geo=US&asn=12345
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decision/record/undetermined/www.example.com/A?period=1h&geo=US&asn=12345
GET /v1/pulsar/query/decisions
GETView Pulsar decision data
NOTE
As of 13 May 2021, the Pulsar team has introduced this endpoint as a simplified way to access decision data. The existing endpoints still function as they always have; this endpoint provides the same functionality in a single endpoint.
Returns total count of Pulsar decisions — optionally, within a specified time range or other filter specified in the query.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both. Optionally, you can filter further by using the query parameters in the list below.
Query Parameters:
| Parameter | Type | Description |
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to a two-letter ISO code for the geographic location for which you want to filter (for example, US). If filtering by asn, you must select a geographic location first. |
| area | string | Filters results according to the geographic location. You can supply one of the following types of filters:
|
| asn | string | Filters results by an autonomous system number (ASN). You can provide a single ASN or comma-separated list. You must specify a geographic location (geo) before you can filter by ASN. |
| record | string | Filters results by associated records (either a single record or a comma-separated list). Record type must also be included, in this format: www.test.com_CNAME |
| result | string | Filters results by result code (for example, return only OK decisions). |
| agg | string | List of other fields to group results (for example, "area,jobid") |
| graph | boolean | If set to true, returns results in a list grouped by timestamp. This list tells you how many decisions were made per timestamp. If set to false, returns a list of totals. |
Copy CodeSample request that includes some of the query parameters
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decisions?start={start_time}&end={end_time}&area={geography}&asn={asn}
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decisions?start=1523000000&end=1523500000&geo=US&asn=12345&graph=true
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/decisions?period=1h&geo=CA&asn=12345&record=www.example.com_A
Route Maps
GET /v1/pulsar/routemaps/create
GETCreate a route map
Creates a new route map in the database for processing.
NOTE: This operation only creates the route map metadata. The response to this GET request contains a temporary pre-signed URL where you must upload the route map file. Even though invocation of this endpoint creates a record in the database, it is defined as a GET request because it returns a URL. Note that the initial status for the route map will appear as "uploading" until the route map is uploaded via the PUT request.
Query Parameters:
| name | string | Name for the route map you are creating (e.g. "West Coast") |
Copy CodeCreates a new route map (using the specified name)
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps/create?name={name}
This command creates a new route map with the name specified in the query. The response includes a URL to which you must upload the route map file to complete the process.
Example Response:
{
"customer": 0,
"status": "uploading",
"name": "example",
"created": 0,
"url": "https://s3.amazonaws.com/pulsar-routemap-uploads/example.json?...",
"mapid": 0,
"modified": 0
}
PUT {aws_url}
PUTUpload a route map
After executing the GET command to create the route map metadata, the response includes an AWS URL (e.g. https://s3.amazonaws.com/pulsar-routemap-uploads/example.json?...) to which you must upload the route map file. Copy and paste that URL into the PUT command to upload the route map file.
Copy CodeUploads the route map file to the specified URL
curl -X PUT -L -H "Content-Length: {file_size}" -H "Client-Encoding: UTF-8" -T "{file}" "{aws_url}"
GET /v1/pulsar/routemaps
GETList all route maps
Returns a list of all current route maps — including metadata such as each route map's mapID —associated with the account.
Copy CodeReturns all route maps associated with the account
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps
Example Response:
[
{
"customer": 0,
"mapid": 0,
"name": "string",
"status": "uploading",
"created": 0,
"modified": 0
}
]
GET /v1/pulsar/routemaps/:mapID
GETView route map details
Returns metadata for the route map specified in the path by its unique map ID.
Path Parameters:
| mapID | integer | (Required) Unique identifier for the route map. |
Copy CodeReturns metadata for the specified route map
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps/:mapID
Example Response:
{
"customer": 0,
"mapid": 0,
"name": "string",
"status": "uploading",
"created": 0,
"modified": 0
}
GET /v1/pulsar/routemaps/:mapID/replace
GETReplace a route map
Replaces the data for the associated route map and returns an S3 pre-signed URL. You must perform a second step to this process by uploading the new map file to the URL returned in the response to this request. Note that you can only replace data for a route map that is in the ready state.
Copy CodeReplaces route map data
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps/:mapID/replace
POST /v1/pulsar/routemaps/:mapID/meta
POSTUpdate route map metadata
Modifies the metadata for the specified route map. Currently, users can modify only the name of the route map.
Copy CodeUpdates the name of the route map
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"name": "stringt"}'https://api.nsone.net/v1/pulsar/routemaps/:mapID/meta
Example Response:
{
"customer": 0,
"mapid": 0,
"name": "string",
"status": "uploading",
"created": 0,
"modified": 0
}
DELETE /v1/pulsar/routemaps/:mapID
DELETEDelete a route map
Deletes the route map metadata for the given mapid. The status of the route map changes to delete pending. Once the Route Map status has been changed, it's no longer considered for decisions.
Copy CodeDeletes route map metadata
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps/:mapID
GET /v1/pulsar/query/routemap/hit/customer
GETView all route map hits
Returns the total count of Pulsar route map hits for the entire account — optionally, within a specified time range. In response to a client request, the route map looks up the requester's IP address in the map file. A "hit" represents an instance in which the IP address is found within the map (as opposed to a "miss" where the IP address is not found). A high ratio of hits to misses indicates that the route map provides sufficient coverage of IP addresses querying it.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both.
Query Parameters:
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to the geographic location (ex. US) |
| mapID | integer | Unique identifier for a specific route map by which to filter results. |
Copy CodeReturns all route map hits for the account
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/routemap/hit/customer
Copy CodeReturns route map hits for a single route map
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps/hit/customer?mapID={mapID}
Copy CodeReturns all route map hits for the last 24 hours
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/routemaps/hit/customer?period=24h
GET /v1/pulsar/query/routemap/miss/customer
GETView all route map misses
Returns the total count of Pulsar route map misses for the entire account — optionally, within a specified time range. In response to a client request, the route map looks up the requester's IP address in the map file. A "miss" represents an instance in which the IP address is not found within the map (as opposed to a "hit" where the IP address is found). A high ratio of hits to misses indicates that the route map provides sufficient coverage of IP addresses querying it.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both.
Query Parameters:
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to the geographic location (ex. US) |
| mapID | integer | Unique identifier for a specific route map by which to filter results. |
Copy CodeReturns all route map misses for the account
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/routemap/miss/customer
GET /v1/pulsar/query/routemap/hit/record/:domain/:record
GETView route map hits by record
Returns the total count of Pulsar route map hits for the specified record (within the specified domain) — optionally, within a specified time range. In response to a client request, the route map looks up the requester's IP address in the map file. A "hit" represents an instance in which the IP address is found within the map (as opposed to a "miss" where the IP address is not found). A high ratio of hits to misses indicates that the route map provides sufficient coverage of IP addresses querying it.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both.
Path Parameters:
| domain | string | (Required) Specifies the domain to which the record belongs. |
| record | string | (Required) Name of the record associated with the decision. |
Query Parameters:
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to the geographic location (ex. US) |
| mapID | integer | Unique identifier for a specific route map by which to filter results. |
Copy CodeReturns route map hits for the specified record
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/routemap/hit/record/:domain/:record
GET /v1/pulsar/query/routemap/miss/record/:domain/:record
GETView route map misses by record
Returns the total count of Pulsar route map misses for the specified record (within the specified domain) — optionally, within a specified time range. In response to a client request, the route map looks up the requester's IP address in the map file. A "miss" represents an instance in which the IP address is not found within the map (as opposed to a "hit" where the IP address is found). A high ratio of hits to misses indicates that the route map provides sufficient coverage of IP addresses querying it.
The time range is specified using start and end parameters. Alternatively, you can provide a period of time (from the current timestamp) by which you want to filter results. Note that you can either specify a start/end or a period — but not both.
Path Parameters:
| domain | string | (Required) Specifies the domain to which the record belongs. |
| record | string | (Required) Name of the record associated with the decision. |
Query Parameters:
| start | integer | Datetime expression (absolute or relative) for the beginning of the time range by which to filter results. |
| end | integer | Datetime expression (absolute or relative) for the end of the time range by which to filter results. |
| period | string | Indicates a period of time from the current timestamp by which to filter results. For example, a value of 24h will return results for the last 24 hours from the current time. |
| geo | string | Filters results according to the geographic location (ex. US) |
| mapID | integer | Unique identifier for a specific route map by which to filter results. |
Copy CodeReturns route map misses for the specified record
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/pulsar/query/routemap/miss/record/:domain/:record
DHCP
Scopes
A scope contains a set of addresses, along with certain configuration parameters called DHCP options. DHCP options include IP addresses where a client can find DNS servers or a hostname which the client should use.
GET /v1/dhcp/scope
GET List scopes
Returns a list of active scopes with an option to filter by scope group.
Query Parameters:
| Parameter | Type | Description |
| scope_group_id | integer | Unique identifier for a scope group by which to filter results. If set to -1, returns unassigned scopes. |
| expand | boolean | Option to expand address details. |
Copy CodeReturns list of all active scopes
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/scope
Example Response:
[
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"address_details": {
"name": "string",
"prefix": "string"
},
"template": "string",
"valid_lifetime_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"match_client_id": null,
"relays": [
"string"
],
"ping_check_enabled": true,
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"stateless": false,
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
]
GET /v1/dhcp/scope/:scopeID
GET View scope details
Returns details about the scope specified in the URL path by its unique scope ID.
Path Parameters:
| Parameter | Type | Description |
| scopeID | integer | Required. Unique identifier for the scope you are requesting. |
Copy CodeReturns scope configuration details
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/scope/:scopeID
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"address_details": {
"name": "string",
"prefix": "string"
},
"template": "string",
"valid_lifetime_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"match_client_id": null,
"relays": [
"string"
],
"ping_check_enabled": true,
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"stateless": false,
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
PUT /v1/dhcp/scope
PUT Create a scope
Creates a new DHCP 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.
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
| address_id | integer | Required. Unique identifier of the scope address or subnet. This subnet must be in an assigned state. |
|||||||||||||||
| scope_group_id | integer | Unique identifier of the scope group to which this scope is associated. If this value is set and the scope group is active, the scope is used for leases. | |||||||||||||||
| address_details | object | Object including name (string) and prefix (string) pairs associated with this scope. | |||||||||||||||
| template | string | Name of the DHCP template to apply to the current scope. | |||||||||||||||
| valid_lifetime_secs | integer | Required if the enabled parameter is set to true for the scope group. The amount of time (in seconds) for which a lease is valid.Applies to DHCPv4 and/or DHCPv6 configurations. |
|||||||||||||||
| options | array of objects | Required. Set of DHCP options assigned to this scope.
|
|||||||||||||||
| client_class | string | Name of the client class to assign to this scope. | |||||||||||||||
| require_client_classes | array of strings | Array of required client class names. | |||||||||||||||
| match_client_id | any | Indicates that the server will use the client identifier for lease lookups and chaddr if the first lookup returns no results. If this value is set to false, the server will only use the chaddr to search for the client's lease. Default is true. |
|||||||||||||||
| relays | array of strings | Array of relay agent IP addresses. A relay must have an interface connected to the link on which the clients are being configured. Typically the relay has an IPv4 address configured on that interface which belongs to the subnet from which the server will assign addresses. Normally, the server is able to use the IPv4 address inserted by the relay (in the giaddr field of the DHCPv4 packet) to select the appropriate subnet. However, that is not always the case. In certain uncommon — but valid — deployments, the relay address may not match the subnet. This usually means that there is more than one subnet allocated for a given link. |
|||||||||||||||
| ping_check_enabled | boolean | Indicates whether or not to enable ping check on this scope. This parameter should only be used if the enabled value within the parent scope's ping_check parameter is set to false. |
|||||||||||||||
| next_server | string | IP address of the TFTP server where the configuration is stored. | |||||||||||||||
| server_hostname | string | Host name of the TFTP server where the configuration is stored. | |||||||||||||||
| boot_file_name | string | File name where the configuration is stored. | |||||||||||||||
| stateless | boolean | Set to true to enable stateless configuration, when only configuration parameters are sent and IP addresses are not assigned. Default is false. |
|||||||||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets or addresses. |
|||||||||||||||
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeCreates a new scope
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "address_id": 1, "scope_group_id": 2, "options": [] }'https://{api.mycompany.net}/v1/dhcp/scope
Example Request:
{
"address_id": 1,
"options": [],
"tags": {
"example": "tag"
}
}
Example Request:
{
"address_id": 1,
"options": [],
"tags": {
"auth:example": "tag"
}
}
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"address_details": {
"name": "string",
"prefix": "string"
},
"template": "string",
"valid_lifetime_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"match_client_id": null,
"relays": [
"string"
],
"ping_check_enabled": true,
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"stateless": false,
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
POST /v1/dhcp/scope/:scopeID
POST Edit a scope
Modifies an existing DHCP scope. If you are removing the template associated with this scope, you have the option to specify the retain query parameter to indicate that the settings associated with that template should remain intact for this individual 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
Note: A scope group must only contain reservations and scope from a single network.
options should be supported for the address' protocol.
Path Parameters:
| Parameter | Type | Description |
| scopeID | integer | Unique identifier for the scope you are editing. |
Query Parameters:
| Parameter | Type | Description |
| retain | boolean | If removing a DHCP template, indicates whether or not to retain the configuration settings for this individual scope. |
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
| address_id | integer | Required. Unique identifier of the scope address or subnet. This subnet must be in an assigned state. |
|||||||||||||||
| scope_group_id | integer | Unique identifier of the scope group to which this scope is associated. If this value is set and the scope group is active, the scope is used for leases. | |||||||||||||||
| address_details | object | Object including name (string) and prefix (string) pairs associated with this scope. | |||||||||||||||
| template | string | Name of the DHCP template to apply to the current scope. | |||||||||||||||
| valid_lifetime_secs | integer | Required if the enabled parameter is set to true for the scope group. The amount of time (in seconds) for which a lease is valid.Applies to DHCPv4 and/or DHCPv6 configurations. |
|||||||||||||||
| options | array of objects | Required. Set of DHCP options assigned to this scope.
|
|||||||||||||||
| client_class | string | Name of the client class to assign to this scope. | |||||||||||||||
| require_client_classes | array of strings | Array of required client class names. | |||||||||||||||
| match_client_id | any | Indicates that the server will use the client identifier for lease lookups and chaddr if the first lookup returns no results. If this value is set to false, the server will only use the chaddr to search for the client's lease. Default is true. |
|||||||||||||||
| relays | array of strings | Array of relay agent IP addresses. A relay must have an interface connected to the link on which the clients are being configured. Typically the relay has an IPv4 address configured on that interface which belongs to the subnet from which the server will assign addresses. Normally, the server is able to use the IPv4 address inserted by the relay (in the giaddr field of the DHCPv4 packet) to select the appropriate subnet. However, that is not always the case. In certain uncommon — but valid — deployments, the relay address may not match the subnet. This usually means that there is more than one subnet allocated for a given link. |
|||||||||||||||
| ping_check_enabled | boolean | Indicates whether or not to enable ping check on this scope. This parameter should only be used if the enabled value within the parent scope's ping_check parameter is set to false. |
|||||||||||||||
| next_server | string | IP address of the TFTP server where the configuration is stored. | |||||||||||||||
| server_hostname | string | Host name of the TFTP server where the configuration is stored. | |||||||||||||||
| boot_file_name | string | File name where the configuration is stored. | |||||||||||||||
| stateless | boolean | Set to true to enable stateless configuration, when only configuration parameters are sent and IP addresses are not assigned. Default is false. |
|||||||||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets or addresses. |
|||||||||||||||
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeUpdates the scope configuration
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "address_id": 1, "scope_group_id": 2, "options": [] }'https://{api.mycompany.net}/v1/dhcp/scope
Example Request:
{
"address_id": 1,
"scope_group_id": 2,
"options": []
}
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"address_details": {
"name": "string",
"prefix": "string"
},
"template": "string",
"valid_lifetime_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"match_client_id": null,
"relays": [
"string"
],
"ping_check_enabled": true,
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"stateless": false,
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
DELETE /v1/dhcp/scope/:scopeID
DELETE Delete a scope
Deletes the specified scope. Once removed, the address is longer used for leases and any current leases will be reclaimed.
Path Parameters:
| Parameter | Type | Description |
| scopeID | integer | (Required) Unique identifier for the scope you are deleting. |
Copy CodeDeletes a scope
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/scope/:scopeID
Scope Groups
GET /dhcp/scopegroup
GETList scope groups
Returns a list of all scope groups associated with the account.
Copy CodeReturns a list of all available scope groups
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/scopegroup
Example Response:
[
{
"name": "string",
"dhcp_service_id": 0,
"template": "string",
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"dhcpv4": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"echo_client_id": true,
"synthesize_dns_records": {
"enabled": true
},
"match_client_id": true,
"next_server": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc"
},
"dhcpv6": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"preferred_lifetime_secs": 0,
"synthesize_dns_records": {
"enabled": true
}
},
"reverse_dns": true,
"client_class_ids": [
0
],
"ping_check": {
"enabled": true,
"type": "icmp",
"wait_time": 500,
"num_pings": 1,
"probation_period": 60
},
"device_filtering": {
"enabled": true,
"filters": [
{
"type": "device_group",
"value": [
0
],
"policy": "allow"
}
]
},
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"id": 0,
"network_id": 0,
"dns_zone_handles": [
"string"
],
"template_config": [
"string"
]
}
]
GET /dhcp/scopegroup/:scopegroupID
GETView scope group details
Returns details about the specified scope group (using its unique scope group ID).
Example URL:
http://api.mycompany.net/v1/dhcp/scopegroup/:scopegroupID
Example Response:
{
"name": "string",
"dhcp_service_id": 0,
"template": "string",
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"dhcpv4": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"echo_client_id": true,
"synthesize_dns_records": {
"enabled": true
},
"match_client_id": true,
"next_server": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc"
},
"dhcpv6": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"preferred_lifetime_secs": 0,
"synthesize_dns_records": {
"enabled": true
}
},
"reverse_dns": true,
"client_class_ids": [
0
],
"ping_check": {
"enabled": true,
"type": "icmp",
"wait_time": 500,
"num_pings": 1,
"probation_period": 60
},
"device_filtering": {
"enabled": true,
"filters": [
{
"type": "device_group",
"value": [
0
],
"policy": "allow"
}
]
},
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"id": 0,
"network_id": 0,
"dns_zone_handles": [
"string"
],
"template_config": [
"string"
],
"scopes": [
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"address_details": {
"name": "string",
"prefix": "string"
},
"template": "string",
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"valid_lifetime_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"match_client_id": null,
"relays": [
"string"
],
"ping_check_enabled": true,
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"stateless": false,
"reservation_mode": "all",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
],
"reservations": [
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"mac": "a1:b2:c3:d4:e5:f6",
"address_details": {
"name": "string",
"prefix": "string"
},
"identifier": {
"type": "hw-address",
"value": "string"
},
"template": "string",
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"dhcpv6": true,
"client_classes": [
"string"
],
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"is_global": false,
"hostname": "string",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
]
}
GET /v1/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)
Query Parameters:
| Parameter | Type | Description |
| export | string | The file type of the report that should be generated. Can be one of the following file types: json, xml, csv, pdf, xslx, or html. |
Copy CodeExports a scope group report in PDF format
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dhcp/scopegroup/{scopeGroupId}/report?export=pdf
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 /v1/dhcp/scopegroup
PUTCreate a scope group
Creates a DHCP 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"] |
Request Body Parameters:
| Parameter | Type | Description | |||||||||
| name | string | (Required) Name of the scope group. | |||||||||
| dhcp_service_id | integer | If set, the service to which to assign this scope group. Pass a value of 0 to break this assignment. | |||||||||
| template | string | Name of the template to apply to the current scope group. | |||||||||
| dhcpv4 | object | Set of DHCPv4 configuration settings. | |||||||||
| enabled | boolean | (Within DHCPv4 or DHCPv6 object) Indicates the state of the scope group. If set to "false," the scope group is disabled. | |||||||||
| valid_lifetime_secs | integer | (Within DHCPv4 or DHCPv6 object) Number of seconds for which a lease is valid. Must be provided if enabled is set to "true." Pass a value of null to clear. | |||||||||
| renew_timer_secs | integer | (Within DHCPv4 or DHCPv6 object) Time (in seconds) before the lease on an IP address is renewed. Pass a value of null to clear. | |||||||||
| rebind_timer_secs | integer | (Within DHCPv4 or DHCPv6 object) Time (in seconds) before the lease on an IP address is rebind. Pass a value of null to clear. | |||||||||
| options | array of objects | (Within DHCPv4 or DHCPv6 object) Set of DHCP client options. | |||||||||
| name | string | (Required; Within options within DHCPv4 or DHCPv6 object) Namespaced DHCP option name. | |||||||||
| value | any | (Required; Within options within DHCPv4 or DHCPv6 object) DHCP option value matching the schema for the specified option definition. | |||||||||
| always_send | boolean | (Within options within DHCPv4 or DHCPv6 object) Indicates whether or not to include the defined DHCP option in the response to the client request. | |||||||||
| encapsulate | string | (Within options within DHCPv4 or DHCPv6 object) Name of the encapsulated option space. Only 124 and 125 options can use this field to encapsulate an option space. | |||||||||
| qualifying_suffix | string | (Within DHCPv4 or DHCPv6 object) Related qualifying suffix (domain name). Pass a value of null to clear. | |||||||||
| generated_prefix | string | (Within DHCPv4 or DHCPv6 object) Custom hostname prefix used if no hostname option is provided by the host. Pass a value of null to clear. | |||||||||
| decline_probation_period | integer | (Within DHCPv4 or DHCPv6 object) The amount of time until a lease is recovered and made available after an address is marked as "declined." Default is 24 hours after which the lease is recovered and the address is made available again. Pass a value of null to clear. | |||||||||
| reclaim_timer_wait_time | integer | (Within DHCPv4 or DHCPv6 object) The interval (in seconds) between the completion of the previous reclamation cycle and the start of the next one. Pass a value of null to clear. | |||||||||
| flush_reclaimed_timer_wait_time | integer | (Within DHCPv4 or DHCPv6 object) The amount of time (in seconds) before the server initiates the lease reclamation procedure. Pass a value of null to clear. | |||||||||
| hold_reclaimed_time | integer | (Within DHCPv4 or DHCPv6 object) The amount of time (in seconds) the lease should be kept after it is reclaimed. A value of 0 indicates that lease affinity is disabled. Pass a value of null to clear. | |||||||||
| max_reclaim_leases | integer | (Within DHCPv4 or DHCPv6 object) The maximum number of reclaimed leases that can be processed at one time. A value of 0 means all leases will be processed. Pass a value of null to clear. | |||||||||
| max_reclaim_time | integer | (Within DHCPv4 or DHCPv6 object) The upper limit (in milliseconds) to the length of time a lease reclamation procedure can take. A value of 0 means there is no time limit. Pass a value of null to clear. | |||||||||
| unwarned_reclaim_cycles | integer | (Within DHCPv4 or DHCPv6 object) Number of consecutive clean-up cycles that must end with unprocessed leases before a warning is printed. A value of 0 means there is no time limit. Pass a value of null to clear. | |||||||||
| preferred_lifetime_secs | integer | (Within DHCPv6 object only) Amount of time (in seconds) that the prefix is preferred and free for unrestricted use. Pass a value of null to clear. | |||||||||
| echo_client_id | boolean | (Within DHCPv4 object only) If set to "true," returns the client identifier in a response to the client request. Pass a value of null to clear. | |||||||||
| synthesize_dns_records | object | (Within DHCPv4 or DHCPv6 object) Set of configuration options related to NS1 DDNS synthesis | |||||||||
| enabled | boolean | (Within synthesize_dns_records object within DHCPv4 or DHCPv6 object) Set of configuration options related to NS1 DDNS synthesis. | |||||||||
| match_client_ID | boolean | (Within DHCPv4 object only) Indicates whether or not the server will use the class identifier for lease lookups and chaddr if the first lookup returns no results. If set to "false," the server will only use the chaddr to search for the client's leases. Default is true. Pass a value of null to clear. | |||||||||
| next_server | string | (Within DHCPv4 object only) The IP address of the TFTP server where the configuration is stored. Pass a value of null to clear. | |||||||||
| boot_file_name | string | (Within DHCPv4 object only) Filename where the configuration is stored. | |||||||||
| reverse_dns | boolean | Indicates whether to enable reverse DNS in the scope group. | |||||||||
| client_class_ids | array of integers | IDs of the client classes that are used by the current scope group | |||||||||
| ping_check | object | Set of configuration options related to DHCP ping check. | |||||||||
| enabled | boolean | (within ping_check object) Indicates whether ping check is enabled in the scope group. | |||||||||
| type | string | (within ping_check object) Specifies the type of ping check to perform. Enum: icmp or arp. | |||||||||
| wait_time | integer | (within ping_check object) Timeout period (in milliseconds) for ping requests. Default is 500. | |||||||||
| num_pings | integer | (within ping_check object) Number of pings to perform before issuing a lease offer. Default is 1. | |||||||||
| probation_period | integer | (within ping_check object) Amount of time (in minutes) that an address will be declined if it is in use. Default is 60. | |||||||||
| device_filtering | object | The configuration options to filter for devices for a scope group.
| |||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets/addresses. | |||||||||
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeCreate a scope group with DDNS synthesis enabled
curl -L -X PUT 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.
Copy CodeCreates a scope group with DHCPv4 and DHCPv6 enabled
curl -L -X PUT https://api.mycompany.net/v1/dhcp/scopegroup -H "X-NSONE-Key: $API_KEY" -d '{ "name": "my-scope-group", "dhcpv4": { "enabled": true, "valid_lifetime_secs": 3600 }, "dhcpv6": { "enabled": true, "valid_lifetime_secs": 3600 }, "service_group_id": 17, "network_id": 1, "client_class_ids": [ 1, 2, 3 ] }'
Copy CodeCreates a scope group with a device group attached
{ "name": "my-scope-group", "dhcpv4": { "enabled": true, "valid_lifetime_secs": 3600 }, "dhcpv6": { "enabled": false }, "service_group_id": 17, "network_id": 1, "device-filtering": { "enabled": true, "filters": [ { "type": "device_group", "value": [ 1, 2, 3 ], "policy": "allow" } ] } }
Example Request:
{
"name": "my-scope-group",
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 3600
},
"dhcpv6": {
"enabled": true,
"valid_lifetime_secs": 3600
},
"service_group_id": 17,
"network_id": 1,
"client_class_ids": [
1,
2,
3
]
}
Example Request:
{
"name": "my-scope-group",
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 3600
},
"dhcpv6": {
"enabled": false
},
"service_group_id": 17,
"network_id": 1,
"device-filtering": {
"enable": true,
"filters": [
{
"type": "device_group",
"value": [
1,
2,
3
],
"policy": "allow"
}
]
}
}
POST /v1/dhcp/scopegroup/:scopeGroupID
POSTEdit a scope group
Updates the scope group configuration using its unique ID. Options must be valid for the address's IP protocol. If the option has already been set, this request will overwrite it. If you are removing a template, you have the option to include the retain query parameter to ensure configuration values from that template are retained in this scope group configuration.
Path Parameters:
| Parameter | Type | Description |
| scopeGroupID | integer | (Required) Unique identifier for the scope group you are editing. |
Query Parameters:
| Parameter | Type | Description |
| retain | boolean | If set to "true," and a template is removed, then all values from the template will be retained as part of the individual scope group configuration. |
Request Body Parameters:
| Parameter | Type | Description | |||||||||
| name | string | Name of the scope group. | |||||||||
| dhcp_service_id | integer | If set, the service to which to assign this scope group. Pass a value of 0 to break this assignment. | |||||||||
| template | string | Name of the template to apply to the current scope group. | |||||||||
| dhcpv4 | object | Set of DHCPv4 configuration settings. | |||||||||
| enabled | boolean | (Within DHCPv4 or DHCPv6 object) Indicates the state of the scope group. If set to "false," the scope group is disabled. | |||||||||
| valid_lifetime_secs | integer | (Within DHCPv4 or DHCPv6 object) Number of seconds for which a lease is valid. Must be provided if enabled is set to "true." Pass a value of null to clear. | |||||||||
| renew_timer_secs | integer | (Within DHCPv4 or DHCPv6 object) Time (in seconds) before the lease on an IP address is renewed. Pass a value of null to clear. | |||||||||
| rebind_timer_secs | integer | (Within DHCPv4 or DHCPv6 object) Time (in seconds) before the lease on an IP address is rebind. Pass a value of null to clear. | |||||||||
| options | array of objects | (Within DHCPv4 or DHCPv6 object) Set of DHCP client options. | |||||||||
| name | string | (Required; Within options within DHCPv4 or DHCPv6 object) Namespaced DHCP option name. | |||||||||
| value | any | (Required; Within options within DHCPv4 or DHCPv6 object) DHCP option value matching the schema for the specified option definition. | |||||||||
| always_send | boolean | (Within options within DHCPv4 or DHCPv6 object) Indicates whether or not to include the defined DHCP option in the response to the client request. | |||||||||
| encapsulate | string | (Within options within DHCPv4 or DHCPv6 object) Name of the encapsulated option space. Only 124 and 125 options can use this field to encapsulate an option space. | |||||||||
| qualifying_suffix | string | (Within DHCPv4 or DHCPv6 object) Related qualifying suffix (domain name). Pass a value of null to clear. | |||||||||
| generated_prefix | string | (Within DHCPv4 or DHCPv6 object) Custom hostname prefix used if no hostname option is provided by the host. Pass a value of null to clear. | |||||||||
| decline_probation_period | integer | (Within DHCPv4 or DHCPv6 object) The amount of time until a lease is recovered and made available after an address is marked as "declined." Default is 24 hours after which the lease is recovered and the address is made available again. Pass a value of null to clear. | |||||||||
| reclaim_timer_wait_time | integer | (Within DHCPv4 or DHCPv6 object) The interval (in seconds) between the completion of the previous reclamation cycle and the start of the next one. Pass a value of null to clear. | |||||||||
| flush_reclaimed_timer_wait_time | integer | (Within DHCPv4 or DHCPv6 object) The amount of time (in seconds) before the server initiates the lease reclamation procedure. Pass a value of null to clear. | |||||||||
| hold_reclaimed_time | integer | (Within DHCPv4 or DHCPv6 object) The amount of time (in seconds) the lease should be kept after it is reclaimed. A value of 0 indicates that lease affinity is disabled. Pass a value of null to clear. | |||||||||
| max_reclaim_leases | integer | (Within DHCPv4 or DHCPv6 object) The maximum number of reclaimed leases that can be processed at one time. A value of 0 means all leases will be processed. Pass a value of null to clear. | |||||||||
| max_reclaim_time | integer | (Within DHCPv4 or DHCPv6 object) The upper limit (in milliseconds) to the length of time a lease reclamation procedure can take. A value of 0 means there is no time limit. Pass a value of null to clear. | |||||||||
| unwarned_reclaim_cycles | integer | (Within DHCPv4 or DHCPv6 object) Number of consecutive clean-up cycles that must end with unprocessed leases before a warning is printed. A value of 0 means there is no time limit. Pass a value of null to clear. | |||||||||
| preferred_lifetime_secs | integer | (Within DHCPv6 object only) Amount of time (in seconds) that the prefix is preferred and free for unrestricted use. Pass a value of null to clear. | |||||||||
| echo_client_id | boolean | (Within DHCPv4 object only) If set to "true," returns the client identifier in a response to the client request. Pass a value of null to clear. | |||||||||
| synthesize_dns_records | object | (Within DHCPv4 or DHCPv6 object) Set of configuration options related to NS1 DDNS synthesis | |||||||||
| enabled | boolean | (Within synthesize_dns_records object within DHCPv4 or DHCPv6 object) Set of configuration options related to NS1 DDNS synthesis. | |||||||||
| match_client_ID | boolean | (Within DHCPv4 object only) Indicates whether or not the server will use the class identifier for lease lookups and chaddr if the first lookup returns no results. If set to "false," the server will only use the chaddr to search for the client's leases. Default is true. Pass a value of null to clear. | |||||||||
| next_server | string | (Within DHCPv4 object only) The IP address of the TFTP server where the configuration is stored. Pass a value of null to clear. | |||||||||
| boot_file_name | string | (Within DHCPv4 object only) Filename where the configuration is stored. | |||||||||
| reverse_dns | boolean | Indicates whether to enable reverse DNS in the scope group. | |||||||||
| client_class_ids | array of integers | IDs of the client classes that are used by the current scope group | |||||||||
| ping_check | object | Set of configuration options related to DHCP ping check. | |||||||||
| enabled | boolean | (within ping_check object) Indicates whether ping check is enabled in the scope group. | |||||||||
| type | string | (within ping_check object) Specifies the type of ping check to perform. Enum: icmp or arp. | |||||||||
| wait_time | integer | (within ping_check object) Timeout period (in milliseconds) for ping requests. Default is 500. | |||||||||
| num_pings | integer | (within ping_check object) Number of pings to perform before issuing a lease offer. Default is 1. | |||||||||
| probation_period | integer | (within ping_check object) Amount of time (in minutes) that an address will be declined if it is in use. Default is 60. | |||||||||
| device_filtering | object | The configuration options to filter for devices for a scope group.
| |||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets/addresses. | |||||||||
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeEdits a scope group configuration
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "name": "my-scope-group", "dhcpv4": { "enabled": true, "valid_lifetime_secs": 3600 }, "dhcpv6": { }, "client_class_ids": [ 1, 2, 3 ] }'https://{api.mycompany.net}/v1/dhcp/scopegroup/{scopegroup_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.
Copy CodeAdd a client class to a scope group
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "client_class_ids":[ {client_class_id] ] }' https://{api.mycompany.net}/v1/dhcp/scopegroup/{scopegroup_id}
Copy CodeEnables access for a device group
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '{"device_filtering":{"enabled":{value},"filters":[{"type":"device_group","value":[{x}],"policy":"allow"}]}}' https://{api.mycompany.net}/v1/dhcp/scopegroup/{scopeGroupId}
If the enabled parameter of device_filtering is set to allow, only devices from specific groups are allowed to receive a lease. When a device expires from the device group, clients under that device ID are not able to renew their current lease and will not be able to acquire a new one.
Copy CodeDenies access for a device group
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '{"device_filtering":{"enabled":true,"filters":[{"type":"device_group","value":[1],"policy":"deny"}]}}' https://{api.mycompany.net}/v1/dhcp/scopegroup/2
If the enabled parameter of device_filtering is set to deny, only devices from specific device groups are prohibited to receive a lease. Upon expiration of the devices from the device group, its identifier is no longer denied, and any clients under that device group can obtain a lease.
Example Request:
{
"name": "my-scope-group",
"dhcpv4": {
"enabled": true,
"valid_lifetime_secs": 3600
},
"dhcpv6": {},
"client_class_ids": [
1,
2,
3
]
}
Example Response:
{
"name": "string",
"dhcp_service_id": 0,
"template": "string",
"dhcpv4": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"echo_client_id": true,
"synthesize_dns_records": {
"enabled": true
},
"match_client_id": true,
"next_server": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc"
},
"dhcpv6": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"preferred_lifetime_secs": 0,
"synthesize_dns_records": {
"enabled": true
}
},
"reverse_dns": true,
"client_class_ids": [
0
],
"ping_check": {
"enabled": true,
"type": "icmp",
"wait_time": 500,
"num_pings": 1,
"probation_period": 60
},
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"id": 0,
"network_id": 0,
"template_config": [
"string"
]
}
Example Request:
{
"device_filtering": {
"enabled":true,
"filters":[
{
"type":"device_group",
"value":[2],
"policy":"allow"
}
]
}
}
Example Request:
{
"device_filtering": {
"enabled":true,
"filters":[
{
"type":"device_group",
"value":[2,4],
"policy":"deny"
}
]
}
}
Example Response:
{
"device_filtering": {
"enabled": true,
"filters": [
{
"type": "device_group",
"value": [3,4],
"policy": "allow"
}
]
}
}
Example Response:
{
"device_filtering": {
"enabled": true,
"filters": [
{
"type": "device_group",
"value": [1],
"policy": "deny"
}
]
}
}
DELETE /v1/dhcp/scopegroup/:scopegroupID
DELETEDelete a scope group
Deletes the scope group specified in the URL path by its unique scopegroupID.
| Parameter | Type | Description |
| scopegroupID | string | (Required) Unique identifier for the scope group you are deleting. |
Copy CodeDeletes a scope group
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/scopegroup/:scopegroupID
Reservations
GET /v1/dhcp/reservation
GETList reservations
Returns a list of all active DHCP host reservations. Optionally, you can filter by scope group or choose to expand the results to view details.
Query Parameters:
| Parameter | Type | Description |
| scope_group_id | integer | Unique identifier of the scope group by which you want to filter the results. If set to -1, returns unassigned scopes. |
| expand | boolean | Indicates whether or not to include address details in the response. |
Copy CodeLists all DHCP reservations
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/dhcp/reservation
Example Response:
[
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"mac": "a1:b2:c3:d4:e5:f6",
"address_details": {
"name": "string",
"prefix": "string"
},
"identifier": {
"type": "hw-address",
"value": "string"
},
"template": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"dhcpv6": true,
"client_classes": [
"string"
],
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
]
GET /v1/dhcp/reservation/:reservationID
GETView reservation details
Returns details for the reservation specified in the URL path by its unique reservation ID.
Path Parameters:
| Parameter | Type | Description |
| reservationID | integer | (Required) Unique identifier for the reservation for which you are requesting details. |
Copy CodeReturns details for the reservation
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/dhcp/reservation/:reservationID
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"mac": "a1:b2:c3:d4:e5:f6",
"address_details": {
"name": "string",
"prefix": "string"
},
"identifier": {
"type": "hw-address",
"value": "string"
},
"template": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"dhcpv6": true,
"client_classes": [
"string"
],
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
PUT dhcp/reservation
PUTCreate a reservation
Creates a new host reservation. Currently, the reservation must be associated with an address. The address and scope group must each meet certain invariants or else the request will result in a 422 error.
The address must:
- Be of
type = host. - 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.
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
| address_id | integer | Unique identifier of the address (subnet) being reserved. This subnet must be in an assigned state and must be of size /32. | |||||||||||||||
| scope_group_id | integer | Unique identifier of the scope group. If present, the reservation is published. | |||||||||||||||
| address_details | object | Object containing the name (string) and prefix (string) for the associated address. | |||||||||||||||
| identifier | object | Object containing the type (enum: "hw-address", "circuit-id", "duid", or "client-id") and value (string) for the associated identifier. | |||||||||||||||
| template | string | Name of the DHCP template to apply to this reservation | |||||||||||||||
| options | array of objects | Required. Set of DHCP options assigned to this reservation.
|
|||||||||||||||
| dhcpv6 | boolean | Indicates which protocol to use to serve the reservation. If set to false, DHCPv4 is used. If set to true, DHCPv6 is used. | |||||||||||||||
| client_classes | array of strings | Array of client class names associated with this reservation. | |||||||||||||||
| next_server | string | IP address of the TFTP server where the configuration is stored. | |||||||||||||||
| server_hostname | string | Host name of the TFTP server where the configuration is stored. | |||||||||||||||
| boot_file_name | string | File name where the configuration is stored. | |||||||||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets/addresses. | |||||||||||||||
| blocked_tags | array of strings | List of tags that are blocked by this network. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeCreates a new reservation with tags
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"address_id": 1, "scope_group_id": 2, "identifier": {"type": "hw-address", "value": "a1:b2:c3:d4:e5:f6"}, "options": [ {"name": "dhcpv4/routers", "value":[ "127.0.0.2" ] } ], "tags": {"example": "tag"} }' https://{api.mycompany.net}/v1/dhcp/reservation
Example Request:
{
"address_id": 1,
"scope_group_id": 2,
"identifier": {
"type": "hw-address",
"value": "a1:b2:c3:d4:e5:f6"
},
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
]
}
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"mac": "a1:b2:c3:d4:e5:f6",
"address_details": {
"name": "string",
"prefix": "string"
},
"identifier": {
"type": "hw-address",
"value": "string"
},
"template": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"dhcpv6": true,
"client_classes": [
"string"
],
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
POST /v1/dhcp/reservation/:reservationID
POSTEdit a reservation
Updates an existing reservation. Currently, the reservation must be associated with an address. The address and scope group must each meet certain invariants or else the request will result in a 422 error.
The address must:
- Be of
type = host. - 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.
Path Parameters:
| reservationID | integer | (Required) Unique identifier for the reservation you are updating. |
Query Parameters:
| retain | boolean | If set to true and a template is removed, all values from the template will be retained for this reservation. |
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
| address_id | integer | Unique identifier of the address (subnet) being reserved. This subnet must be in an assigned state and be of size /32. | |||||||||||||||
| scope_group_id | integer | Unique identifier of the scope group. If present, the reservation is published. | |||||||||||||||
| address_details | object | Object containing the name (string) and prefix (string) for the associated address. | |||||||||||||||
| identifier | object | Object containing the type (enum: "hw-address", "circuit-id", "duid", or "client-id") and value (string) for the associated identifier. | |||||||||||||||
| template | string | Name of the DHCP template to apply to this reservation | |||||||||||||||
| options | array of objects | Required. Set of DHCP options assigned to this reservation.
|
|||||||||||||||
| dhcpv6 | boolean | Indicates which protocol to use to serve the reservation. If set to false, DHCPv4 is used. If set to true, DHCPv6 is used. | |||||||||||||||
| client_classes | array of strings | Array of client class names associated with this reservation. | |||||||||||||||
| next_server | string | IP address of the TFTP server where the configuration is stored. | |||||||||||||||
| server_hostname | string | Hostname of the TFTP server where the configuration is stored. | |||||||||||||||
| boot_file_name | string | Filename where the configuration is stored. | |||||||||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets/addresses. | |||||||||||||||
| blocked_tags | array of strings | List of tags that are blocked by this network. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeUpdates the reservation configuration
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{"address_id": 1, "scope_group_id": 2, "identifier": {"type": "hw-address", "value": "a1:b2:c3:d4:e5:f6"}, "options": [ {"name": "dhcpv4/routers", "value":[ "127.0.0.2" ] } ], "tags": {"example": "tag"} }' https://{api.mycompany.net}/v1/dhcp/reservation
Example Request:
{
"address_id": 1,
"scope_group_id": 2,
"identifier": {
"type": "hw-address",
"value": "a1:b2:c3:d4:e5:f6"
},
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
]
}
Example Response:
{
"id": 0,
"address_id": 0,
"scope_group_id": 0,
"mac": "a1:b2:c3:d4:e5:f6",
"address_details": {
"name": "string",
"prefix": "string"
},
"identifier": {
"type": "hw-address",
"value": "string"
},
"template": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"dhcpv6": true,
"client_classes": [
"string"
],
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"template_config": [
"string"
]
}
DELETE /v1/dhcp/reservation/:reservationid
DELETEDelete a reservation
Deletes a reservation.
Path Parameters:
| reservationID | string | (Required) Unique identifier for the reservation you are deleting. |
Copy CodeDeletes a reservation
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/dhcp/reservation/:reservationID
GET /v1/dhcp/lease
GETList leases
Lists any active leases — including new and renewals — with the option to filter results using one or more query parameters.
Note about lease persistence: In Cloud-Managed DDI, the DHCP service does not require a volume to retain the lease state. That is, if you remove the DHCP service component or it loses connection, the service will attempt to pull the current leases associated with the scope group from the NS1 control plane upon reconnection.
Query Parameters:
| scopegroupID | integer | Unique identifier for the scope group by which to filter. |
| scopeID | integer | Unique identifier for the scope by which to filter. |
| includeInvalid | boolean | Indicates whether or not to include historical lease records. Default is false. |
| limit | integer | Maximum number of records to return. |
| offset | integer | Offset within the records list. |
| period | string (enum) | Specifies a time range through which to filter results. Supported values: 24h (default) or 30d. |
Copy CodeReturns a list of active leases
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/dhcp/lease
Copy CodeReturns a list of active leases filtered by scope group ID
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/dhcp/lease?scopegroupID=4
Example Response:
[
{
"prefix": "string",
"scope_group_id": 0,
"dhcid": "string",
"fqdn": "string",
"expiration": "2020-12-22T16:08:34Z",
"created": "2020-12-22T16:08:34Z",
"scope_id": 0,
"renewals": 0,
"renewed_ts": "2020-12-22T16:08:34Z",
"invalid": "2020-12-22T16:08:34Z"
}
]
DHCP options
GET /v1/dhcp/optionspace
GETList option spaces
View a list of DHCP option spaces. Optionally, you can filter the list by option space type (i.e., standard = true or false).
Query parameters:
| standard | boolean | (Optional) Filters the list by option space type. Set to true for immutable, predefined spaces. Set to false for customer, user-defined spaces. If left blank, all option spaces are returned. |
Copy Codecurl -X GET -H "X-NSONE-Key: $API_KEY" https://$API_HOST/v1/dhcp/optionspace
Returns a list of all DHCP option spaces
Copy Codecurl -X GET -H "X-NSONE-Key: $API_KEY" https://$API_HOST/v1/dhcp/optionspace?standard=true
Returns a list of standard DHCP option spaces only
Copy Codecurl -X GET -H "X-NSONE-Key: $API_KEY" https://$API_HOST/v1/dhcp/optionspace?standard=false
Returns a list of custom DHCP option spaces only
Example Response:
[
{
"name": "custom_option_space",
"standard": false
}
]
GET /v1/dhcp/optionspace/{name}
GETView option space details
Returns DHCP option space configuration details using the name of the option space specified in the request URL.
Path parameters:
| space | string | (Required) Name of the option space |
Copy CodeReturns details for the specified option space
curl -X GET -H "X-NSONE-Key: $API_KEY" https://$API_HOST/v1/dhcp/optionspace/{space}
Example URL:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/optionspace/custom_option_space
Example Response:
{
"value": {
"name": "custom_option_space",
"standard": false
}
}
PUT /v1/dhcp/optionspace
PUTCreate an option space
Creates a custom DHCP option space.
Note: After creating a custom option space, you must create a custom option definition. Optionally, you can encapsulate the option space (not required if using code 43).
Request body parameters:
| name | string | Required. Name for the option space. |
Copy CodeCreates a new custom DHCP option space
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "name": "{option_space_name}" }' https://{api.mycompany.net}/v1/dhcp/optionspace
Example Request:
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{
"name": "example"
}' https://api.mycompany.net/v1/dhcp/optionspace
DELETE /v1/dhcp/optionspace/{name}
DELETEDelete an option space
Removes the custom option space specified (by its name) in the request URL.
Path parameters:
| name | string | (Required) Name of the option space you are deleting |
Example URL:
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/optionspace/custom_option_space
GET /v1/dhcp/optiondef
GETList option definitions
View a list of all DHCP custom option spaces. Optionally, you can filter by option space type (standard=true/false).
Query parameters:
| code | integer | Filter by option code (e.g., code=6). |
| space | string | Filter by option space (e.g., space="dhcpv4") |
| key | string | Filter list by key (e.g., key="domain-name-servers") |
| standard | boolean | Filter by whether or not the option definition is a standard option and not a user-defined custom option (e.g., standard=true or standard=false) |
Copy CodeList all custom DHCP option definitions
curl -X GET -H "X-NSONE-Key: $API_KEY" https://$API_HOST/v1/dhcp/optiondef
Example URL:
https://api.mycompany.net/v1/dhcp/optiondef
Example Response:
[
{
"space": "dhcpv4",
"key": "domain-name",
"friendly_name": "Single Data Type Option Definition",
"description": "Example of Single Data Type Option Definition",
"code": 15,
"standard": true,
"schema": {
"type": "fqdn"
}
},
{
"space": "dhcpv4",
"key": "domain-name-servers",
"friendly_name": "Array Data Type Option Definition",
"description": "Example of Array Data Type Option Definition",
"standard": true,
"code": 6,
"schema": {
"type": "array",
"items": "ipv4_address"
}
},
{
"space": "dhcpv4",
"key": "shortel-server",
"friendly_name": "Compound Option Definition",
"description": "Example of Compound Option Definition",
"code": 156,
"standard": false,
"schema": {
"type": "record",
"fields": [
{
"name": "Layer2Tagging",
"type": "int8"
},
{
"name": "ftpservers",
"type": "ipv4_address"
}
]
}
}
]
GET /v1/dhcp/optiondef/{space}/{key}
GETView option definition details
View configuration details for an option definition specified by the name of the corresponding option space and unique key.
Path parameters:
| space | string | (Required) Name of the option space associated with the option definition (e.g., dhcpv4). |
| key | string | (Required) Unique key of the option definition (e.g., domain-name-servers). |
Copy CodeView details for the specific DHCP option definition
curl -X GET -H "X-NSONE-Key: $API_KEY" https://$API_HOST/v1/dhcp/optiondef/{space}/{key}
Example URL:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/optiondef/dhcpv4/domain-name
Example Response:
{
"space": "dhcpv4",
"key": "domain-name",
"friendly_name": "Single Data Type Option Definition",
"description": "Example of Single Data Type Option Definition",
"code": 15,
"standard": true,
"schema": {
"type": "fqdn"
}
}
PUT /v1/dhcp/optiondef/{space}/{key}
PUTCreate (or replace) an option definition
Create or replace an option definition with a unique code and key in its space. Only non-standard definitions can be replaced. 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 the record schema selected:
- The record must consist of at least two fields.
- The
stringorbinaryfields must be last in the order of primitive types. - You can only enter one
stringfield or onebinaryfield per record. - The
emptytype is not allowed in a complex record. - You cannot create an array of
stringorbinaryfield 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 the array schema selected:
- You cannot create an array of
string,binary, oremptyfield types.
Path parameters:
| Parameter | Type | Description |
| space | string | Required. Name of the option space with which the definition is associated (e.g., dhcpv4) |
| key | string | Required. Unique key or label for the option definition (e.g., domain-name-servers) |
Request body parameters:
| Parameter | Type | Description | |||||||||||||||||||||
| friendly_name | string | Required. Human-friendly name for the DHCP option definition | |||||||||||||||||||||
| description | string | Required. Brief description for the option definition | |||||||||||||||||||||
| code | integer | Required. DHCP option code (0-255) | |||||||||||||||||||||
| schema | object | Required. Configuration scheme for the option definition. Note: If the schema is an array, the items field is required. If the schema is an object, the fields field is required and multiple values may be provided.
| |||||||||||||||||||||
| multiple_final_value | boolean | Indicates whether or not the last field supports multiple values. Only valid if the type field is set to object) |
|||||||||||||||||||||
| encapsulate | string | Encapsulated options space name. Use only if space is set to a standard option space. |
Copy CodeCreates or replaces a custom option definition
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "friendly_name": "friendly_name", "description": "description", "code": 6, "schema": { "type": "array", "items": "boolean", "fields": [ { "name": "string", "type": "boolean" } ], "multiple_final_value": true }, "encapsulate": "custom-options-space" }' 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": "Domain Name Servers",
"description": "IPv4 DNS servers",
"code": 6,
"schema": {
"type": "array",
"items": "boolean",
"fields": [
{
"name": "string",
"type": "boolean"
}
],
"multiple_final_value": true
},
"encapsulate": "custom-options-space"
}
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"
}
}
DELETE /v1/dhcp/optiondef/{space}/{key}
DELETEDelete an option definition
Deletes the custom DHCP option definition specified in the request URL by its space and key. Note that only non-standard option definitions and those that are not associated with any scopes or scope groups can be removed.
Path parameters:
| space | string | (Required) Name of the option space |
| key | string | (Required) Unique key of the option definition |
Copy CodeDeletes a custom option definition
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://$API_HOST/v1/dhcp/optiondef/{space}/{key}
Example URL:
https://api.mycompany.net/v1/dhcp/optiondef/dhcpv4/simple-example
Client Classes
GET /v1/dhcp/clientclass
GETList all client classes
View a list of DHCP client classes within your organization. Optionally, you can specify the scope_group_id query parameter to view a list of client classes within a scope group.
Query Parameters:
| scope_group_id | integer | Unique identifier for the scope group by which to filter. |
Copy CodeReturns a list of DHCP client classes
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dhcp/clientclass
Example Response:
[
{
"id": 0,
"scope_group_ids": [
0
],
"name": "Client_foo",
"test": "substring(option[61].hex,0,3) == 'foo'",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"only_if_required": false
}
]
GET /v1/dhcp/clientclass/:clientclassID
GETView client class details
Returns configuration details for the client class specified in the URL path by its unique client class ID.
Path Parameters:
| clientclassID | integer | (Required) Unique identifier for the client class. |
Copy CodeReturns details for the specified client class
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/clientclass/:clientclassID
Example Response:
EXAMPLE: NORMAL CLIENT CLASS
{
"id": 2,
"scope_group_id": 2,
"scope_group_ids": [
2
],
"name": "Client_foo",
"test": "substring(option[61].hex,0,3) == 'foo'",
"options": [
{
"name": "domain-name-servers",
"value": [
"192.0.2.1",
"192.0.2.2"
]
}
]
}
Example Response:
EXAMPLE: VENDOR CLIENT CLASS
{
"id": 1,
"scope_group_id": 1,
"scope_group_ids": [
1
],
"name": "VENDOR_CLASS_foo",
"options": [
{
"name": "domain-name-servers",
"value": [
"192.0.2.1",
"192.0.2.2"
]
}
]
}
PUT /v1/dhcp/clientclass
PUTCreate a client class
Creates a client class in a scope group with given ID. The name of the clients class can have VENDOR_CLASS_ prefix. In this case, test parameter is required. If the name does not contain such prefix, test parameter is optional.
Note: After creating a client class, you must associate it with a scope group.
Request Body Parameters:
| Parameter | Type | Description |
|---|---|---|
| clientclassID | integer | Unique identifier for the client class you are updating. |
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name | string | Required. Name of the client class that you are creating. Note: If the client class name has the VENDOR_CLASS_ prefix, the test field is required. Otherwise, the test field is optional. | |||||||||||||||
| test | string | String containing the logical expression used to determine membership in the class | |||||||||||||||
| options | array of objects | Required. Set of DHCP options assigned to this reservation.
| |||||||||||||||
| next_server | string | IP address of the TFTP server where the configuration is stored. | |||||||||||||||
| server_hostname | string | Host name of the TFTP server where the configuration is stored. | |||||||||||||||
| boot_file_name | string | File name where the configuration is stored. |
Copy CodeCreates a new DHCP client class
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "scope_group_id": 1, "scope_group_ids": [1], "name": "{class_name}", "options": [{"name": "{dhcp_option_name}", "value": ["{dhcp_option_value}", "{dhcp_option_value}", "always_send":"true", "encapsulate":"{encapsulated_option_space_name}"]}]}' https://api.mycompany.net/v1/dhcp/clientclass
Example Request:
EXAMPLE: VENDOR CLIENT CLASS
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{
"scope_group_id": 1,
"scope_group_ids": [
1
],
"name": "VENDOR_CLASS_foo",
"options": [
{
"name": "domain-name-servers",
"value": [
"192.0.2.1",
"192.0.2.2"
]
}
]
}' https://api.mycompany.net/v1/dhcp/clientclass
Example Request:
EXAMPLE: NORMAL CLIENT CLASS
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{
{
"scope_group_id": 1,
"name": "Client_foo",
"test": "substring(option[61].hex,0,3) == 'foo'",
"options": [
{
"name": "domain-name-servers",
"value": [
"192.0.2.1",
"192.0.2.2"
]
}
]
}' https://api.mycompany.net/v1/dhcp/clientclass
Example Response:
EXAMPLE: VENDOR CLIENT CLASS
{
"id": 1,
"scope_group_id": 1,
"scope_group_ids": [
1
],
"name": "VENDOR_CLASS_foo",
"options": [
{
"name": "domain-name-servers",
"value": [
"192.0.2.1",
"192.0.2.2"
]
}
]
}
Example Response:
EXAMPLE: NORMAL CLIENT CLASS
{
"id": 2,
"scope_group_id": 2,
"scope_group_ids": [
2
],
"name": "Client_foo",
"test": "substring(option[61].hex,0,3) == 'foo'",
"options": [
{
"name": "domain-name-servers",
"value": [
"192.0.2.1",
"192.0.2.2"
]
}
]
}
POST /v1/dhcp/clientclass/:clientclassID
POSTEdit a client class
Updates the client class specified in the URL path by its unique clientclassID. The name of the clients class can have VENDOR_CLASS_ prefix. In this case, test parameter is required. If the name does not contain such prefix, test parameter is optional.
Note: After creating a client class, you must associate it with a scope group.
Path Parameters:
| Parameter | Type | Description |
|---|---|---|
| clientclassID | integer | Unique identifier for the client class you are updating. |
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name | string | Required. Name of the client class that you are updating. Note: If the client class name has the VENDOR_CLASS_ prefix, the test field is required. Otherwise, the test field is optional. | |||||||||||||||
| test | string | String containing the logical expression used to determine membership in the class | |||||||||||||||
| options | array of objects | Required. Set of DHCP options assigned to this reservation.
| |||||||||||||||
| next_server | string | IP address of the TFTP server where the configuration is stored. | |||||||||||||||
| server_hostname | string | Host name of the TFTP server where the configuration is stored. | |||||||||||||||
| boot_file_name | string | File name where the configuration is stored. |
Copy CodeModifies the configuration for the specified DHCP client class
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{"name": "{client_class_name}","test": "{string}'","options": [{"name": "{dhcp_option_name}","value": "{any}/"}],"only_if_required": {boolean} }' https://{api.mycompany.net}/v1/dhcp/clientclass
Example Request:
{
"name": "Client_foobar",
"test": "substring(option[61].hex,0,3) == 'foo'",
"options": [
{
"name": "domain-name-servers",
"value": "192.0.2.2, 192.0.2.3"
}
],
"only_if_required": true
}
Example Response:
{
"id": 2,
"scope_group_id": 2,
"scope_group_ids": [
2
],
"name": "Client_foo",
"test": "substring(option[61].hex,0,3) == 'foo'",
"options": [
{
"name": "domain-name-servers",
"value": [
"192.0.2.1",
"192.0.2.2"
]
}
]
}
DELETE /v1/dhcp/clientclass/:clientclassID
DELETEDelete a client class
Deletes the client class specified in the URL path by its unique client class ID.
Path Parameter:
| clientclassID | integer | (Required) Unique identifier for the DHCP client class. |
Copy CodeDeletes a client class
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dhcp/clientclass/:clientclassID
Templates
GET /v1/dhcp/template
GETList DHCP templates
List all templates for the current organization/account. Optionally, you can include a query parameter type to filter by template type (enum: scopegroup, scope, or reservation).
Query Parameters:
| Parameter | Type | Description |
| type | string (enum) | Option to filter by template type. Enum: scopegroup, scope, or reservation |
Copy CodeReturns unfiltered list of DHCP templates
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/dhcp/template
Example Response:
[
{
"name": "string",
"type": "scopegroup",
"locked": false,
"scope_group_config": {
"dhcpv4": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"echo_client_id": true,
"synthesize_dns_records": {
"enabled": true
},
"match_client_id": true,
"next_server": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc"
},
"dhcpv6": {
"enabled": false,
"valid_lifetime_secs": 0,
"renew_timer_secs": 0,
"rebind_timer_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"qualifying_suffix": "string",
"generated_prefix": "string",
"decline_probation_period": 0,
"reclaim_timer_wait_time": 0,
"flush_reclaimed_timer_wait_time": 0,
"hold_reclaimed_time": 0,
"max_reclaim_leases": 0,
"max_reclaim_time": 0,
"unwarned_reclaim_cycles": 0,
"preferred_lifetime_secs": 0,
"synthesize_dns_records": {
"enabled": true
}
},
"reverse_dns": true,
"client_class_ids": [
0
],
"ping_check": {
"enabled": true,
"type": "icmp",
"wait_time": 500,
"num_pings": 1,
"probation_period": 60
},
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
]
},
"scope_config": {
"valid_lifetime_secs": 0,
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"match_client_id": null,
"relays": [
"string"
],
"ping_check_enabled": true,
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
]
},
"reservation_config": {
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"dhcpv6": true,
"client_classes": [
"string"
],
"next_server": "string",
"server_hostname": "string",
"boot_file_name": "\"/dev/null\" or \"/tmp/bootfile.efi\" etc",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
]
},
"used_by_ids": [
0
]
}
]
GET /v1/dhcp/template/:name
GETView template details
Returns configuration details for the template specified in the URL path by its name. Optionally, you can include a query parameter 'type' to filter by template type (i.e. scopegroup, scope, or reservation).
Copy CodeReturns details for the DHCP template
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/template/:name
Example Response:
{
"type": "scopegroup",
"locked": false,
"name": "foo",
"scope_group_config": {
"dhcpv4": {
"valid_lifetime_secs": 7000,
"options": [
{
"name": "dhcpv4/routers",
"value": [
"1.1.1.1"
]
},
{
"name": "dhcpv4/time-offset",
"value": "15"
}
],
"client_class_ids": [
1,
2,
3
]
}
}
}
Example Response:
{
"type": "scope",
"locked": false,
"name": "foo",
"scope_config": {
"address_id": 1,
"options": [
{
"name": "dhcpv4/routers",
"value": [
"1.1.1.1"
]
},
{
"name": "dhcpv4/time-offset",
"value": "15"
}
]
}
}
PUT /v1/dhcp/template/:name
PUTCreate a DHCP template
Creates a new DHCP template for one of the permitted objects (scope groups, scope, or reservation) in the system. Configuration options vary based on the type of template you are creating. Depending on the template type, one of the nested configuration fields is required:
| Template type | Required config |
| scopegroup | scope_group_config |
| scope | scope_config |
| reservation | reservation_config |
Path Parameters:
| Parameter | Type | Description |
| name | string | (Required) Name of the DHCP template |
Request Body Parameters:
| Parameter | Type | Description |
| type | string (enum) | (Required) Type of template you are creating. Enum: scopegroup, scope, reservation. |
| locked | boolean | Indicates whether or not to lock the template to prevent changes to the object (scope group, scope, or reservation) to which this template is attached. |
| scope_group_config | object | If you are configuring a scope group template, include the configuration options here. Refer to the "Create a scope group" endpoint for details. |
| scope_config | object | If you are configuring a scope template, include the configuration options here. Refer to the "Create a scope" endpoint for details. |
| reservation_config | object | If you are configuring a reservation template, include the configuration options here. Refer to the "Create a reservation" endpoint for details. |
Copy CodeCreates a scope group template
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "type": "{enum}", "locked": {boolean}, "name": "{string}", "scope_group_config": [{ }] }' https://api.mycompany.net/v1/dhcp/template/:name
Example Request:
{
"type": "scopegroup",
"locked": false,
"name": "foo",
"scope_group_config": {
"dhcpv4": {
"valid_lifetime_secs": 7000,
"options": [
{
"name": "dhcpv4/routers",
"value": [
"1.1.1.1"
]
},
{
"name": "dhcpv4/time-offset",
"value": "15"
}
],
"client_class_ids": [
1,
2,
3
]
}
}
}
Example Request:
{
"type": "scope",
"locked": false,
"name": "foo",
"scope_config": {
"address_id": 1,
"options": [
{
"name": "dhcpv4/routers",
"value": [
"1.1.1.1"
]
},
{
"name": "dhcpv4/time-offset",
"value": "15"
}
]
}
}
Example Request:
{
"type": "reservation",
"locked": false,
"name": "foo",
"reservation_config": {
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
]
}
}
POST /v1/dhcp/template/:name
POSTEdit DHCP template
Edits the DHCP template specified in the URL path by its unique name. Configuration options vary based on the type of template you are creating. Depending on the template type, one of the nested configuration fields is required:
| Template type | Required config |
| scopegroup | scope_group_config |
| scope | scope_config |
| reservation | reservation_config |
Path Parameters:
| Parameter | Type | Description |
| name | string | (Required) Name of the DHCP template |
Request Body Parameters:
| Parameter | Type | Description |
| type | string (enum) | (Required) Type of template you are creating. Enum: scopegroup, scope, reservation. |
| locked | boolean | Indicates whether or not to lock the template to prevent changes to the object (scope group, scope, or reservation) to which this template is attached. |
| scope_group_config | object | If you are configuring a scope group template, include the configuration options here. Refer to the "Create a scope group" endpoint for details. |
| scope_config | object | If you are configuring a scope template, include the configuration options here. Refer to the "Create a scope" endpoint for details. |
| reservation_config | object | If you are configuring a reservation template, include the configuration options here. Refer to the "Create a reservation" endpoint for details. |
Copy CodeEdits details for a DHCP template
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "type": "{enum}", "locked": {boolean}, "name": "{string}", "{config_options}": { } }' https://api.mycompany.net/v1/dhcp/template/:name
Example Request:
{
"type": "scopegroup",
"locked": false,
"name": "foo",
"scope_group_config": {
"dhcpv4": {
"valid_lifetime_secs": 7000,
"options": [
{
"name": "dhcpv4/routers",
"value": [
"1.1.1.1"
]
},
{
"name": "dhcpv4/time-offset",
"value": "15"
}
],
"client_class_ids": [
1,
2,
3
]
}
}
}
Example Request:
{
"type": "scope",
"locked": false,
"name": "foo",
"scope_config": {
"address_id": 1,
"options": [
{
"name": "dhcpv4/routers",
"value": [
"1.1.1.1"
]
},
{
"name": "dhcpv4/time-offset",
"value": "15"
}
]
}
}
Example Request:
{
"type": "reservation",
"locked": false,
"name": "foo",
"reservation_config": {
"mac": "a1:b2:c3:d4:e5:f6",
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
]
}
}
DELETE /v1/dhcp/template/:name
DELETEDelete a DHCP template
Deletes the DHCP template specified in the URL path by its unique name. Note that you cannot delete a template that is currently in use.
Path Parameters:
| Parameter | Type | Description |
| name | string | (Required) Name of the template you are deleting. |
Query Parameters:
| Parameter | Type | Description |
| type | string (enum) | Type of template you are deleting. Enum: scopegroup, scope, or reservation. |
Copy CodeDeletes the specified template
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.mycompany.net/v1/dhcp/template/:name
Device Groups
Device groups are collections of devices, and you can use these groups to allow or deny access to DHCP services based on the MAC address of a device. For example, if you want to require explicitly registered devices on your network and control how long these devices can remain on the network, you can use a device group to restrict access to those explicitly registered devices.
GET /v1/dhcp/devicegroup
GETView all device groups
Retrieves a list of all device groups.
Copy CodeReturns a list of all device groups
$ curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dhcp/devicegroup
Example Response:
[
{
"id": 0,
"scope_group_ids": [
0
],
"devices": [
{
"identifier": "string",
"identifier_type": "hw-address",
"metadata": null,
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string"
}
],
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"name": "string",
"expiration_period_seconds": 0
}
]
PUT /v1/dhcp/devicegroup
PUTCreate a device group
Creates a new device group.
Request Body Parameters:
| Parameter | Type | Description | ||||||
| devices | array of objects | A list of devices
| ||||||
| name | string | The name of the device group that you are creating. This parameter cannot be empty and should be unique within an organization. | ||||||
| expiration_period_seconds | integer greater than or equal to 0 | The time (in seconds) after which a device in this device group is considered expired and is removed from the device group. If you do not modify the expiry time, or if the expiry time is set to 0, devices in the device group never expire. |
Copy CodeCreates a new device group with the specified devices
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ \"devices": [ \ {"identifier": "00:00:0A:BB:28:FC", \"identifier_type": "hw-address", \"metadata": { "type": "mobile" } }], \"name": "NY-Office", \"expiration_period_seconds": "0" \ }' https://{api.mycompany.net}/v1/dhcp/devicegroup
Example Request:
$ curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ \
"devices": [ \
{
"identifier": "00:00:0A:BB:28:FC", \
"identifier_type": "hw-address", \
"metadata": {
"type": "mobile"
}
}
], \
"name": "NY-Office", \
"expiration_period_seconds": "0" \
}' https://{api.mycompany.net}/v1/dhcp/devicegroup
Example Response:
{
"id": 0,
"scope_group_ids": [
0
],
"devices": [
{
"identifier": "string",
"identifier_type": "hw-address",
"metadata": null,
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string"
}
],
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"name": "string",
"expiration_period_seconds": 0
}
GET /v1/dhcp/devicegroup/:deviceGroupId
GETView the details of a device group
Retrieves a specific device group.
Path o
Parameter | Type | Description |
| deviceGroupId | integer | The ID of the device group. You can obtain this value by viewing all device groups. |
Copy CodeReturns details for the specified device group
$ curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dhcp/devicegroup/{deviceGroupId}
Example Response:
{
"id": 0,
"scope_group_ids": [
0
],
"devices": [
{
"identifier": "string",
"identifier_type": "hw-address",
"metadata": null,
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string"
}
],
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"name": "string",
"expiration_period_seconds": 0
}
POST /v1/dhcp/devicegroup/:deviceGroupId
POSTModify a device group
Modifies a specific device group to replace it with a completely new list of devices or to update the name or expiration_period_seconds of the device group.
Path Parameters:
| Parameter | Type | Description |
| deviceGroupID | integer | Required. The ID of the device group that you want to modify. You can find this value by viewing all device groups. |
Request Body Parameters:
| Parameter | Type | Description | ||||||
| devices | array of objects | A list of devices
| ||||||
| name | string | The name of the device group that you are creating. This parameter cannot be empty and should be unique within an organization. | ||||||
| expiration_period_seconds | integer | The time (in seconds) after which a device in this device group is considered expired and is removed from the device group. If you do not modify the expiry time, or if the expiry time is set to 0, devices in the device group never expire. |
Copy CodeEdits the specified device group
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '{ \"devices": [ \{ \"identifier": "aa:bb:cc:dd:ee:ff", \"identifier_type": "hw-address", \"metadata": { \"comments": "first device in a pool" \} \} \] \"name": "LHR-2" \}' https://{api.mycompany.net}/v1/dhcp/devicegroup/2
Example Request:
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '{ \
"devices": [ \
{ \
"identifier": "aa:bb:cc:dd:ee:ff", \
"identifier_type": "hw-address", \
"metadata": { \
"comments": "first device in a pool" \
} \
} \
] \
"name": "LHR-2" \
}' https://{api.mycompany.net}/v1/dhcp/devicegroup/2
Example Response:
{
"id": 0,
"scope_group_ids": [
0
],
"devices": [
{
"identifier": "string",
"identifier_type": "hw-address",
"metadata": null,
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string"
}
],
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"name": "string",
"expiration_period_seconds": 0
}
DELETE /v1/dhcp/devicegroup/:deviceGroupId
DELETEDelete a device group
Deletes a specific device group.
Path Parameter:
| Parameter | Type | Description |
| deviceGroupID | integer | Required. The ID of the device group that you want to delete. You can find this value by viewing all device groups. |
Copy CodeDeletes the specified device group
$ curl -X DELETE https://{api.mycompany.net}/v1/dhcp/devicegroup/{deviceGroupId}
POST /v1/dhcp/devicegroup/:deviceGroupId/add
POSTAdd devices to a device group
Adds devices to a specific device group.
Path Parameters:
| Parameter | Type | Description |
| deviceGroupId | integer | Required. The ID of the device group that you want to modify. You can find this value by viewing all device groups. |
Request Body Parameters:
The payload should be sent as an array of JSON objects that use the following fields:
Parameter | Type | Description |
| identifier | string | Required. The hardware address (MAC address) of the device. |
| identifier_type | string | Required. The type of identifier. Can be hw-address. |
| metadata | any | A JSON object of arbitrary data about the device. |
Copy CodeAdds a new device to a device group
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '[{"identifier": "aa:bb:cc:dd:ee:f2","identifier_type": "hw-address","metadata": {"comments": "second device in a pool"}}]' https://{api.mycompany.net}/v1/dhcp/devicegroup/2/add
Example Request:
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '[ \
{ \
"identifier": "aa:bb:cc:dd:ee:f2", \
"identifier_type": "hw-address", \
"metadata": { \
"comments": "second device in a pool" \
} \
} \
]' https://{api.mycompany.net}/v1/dhcp/devicegroup/2/add
Example Response:
{
"id": 0,
"scope_group_ids": [
0
],
"devices": [
{
"identifier": "string",
"identifier_type": "hw-address",
"metadata": null,
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string"
}
],
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"name": "string",
"expiration_period_seconds": 0
}
POST /v1/dhcp/devicegroup/:deviceGroupId/update
POSTUpdate devices in a device group
Updates the details of devices in a specific device group.
Path Parameters:
| Parameter | Type | Description |
| deviceGroupId | integer | Required. The ID of the device group that you want to modify. You can find this value by viewing all device groups. |
Request Body Parameters:
The payload should be sent as an array of JSON objects that use the following fields:
Parameter | Type | Description |
| identifier | string | Required. The hardware address (MAC address) of the device. |
| identifier_type | string | Required. The type of identifier. Can be hw-address. |
| metadata | any | A JSON object of arbitrary data about the device. |
Copy CodeUpdates a device in a device group
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '[{"identifier": "aa:bb:cc:dd:ee:f2","identifier_type": "hw-address","metadata": {"comments": "second updated device in a pool"}}]' https://{api.mycompany.net}/v1/dhcp/devicegroup/2/update
Example Request:
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '[ \
{ \
"value": [ \
{ \
"identifier": "aa:bb:cc:dd:ee:ff", \
"identifier_type": "hw-address", \
"metadata": { \
"comments": "new device in a pool" \
}
}
]
} \
]' https://{api.mycompany.net}/v1/dhcp/devicegroup/2/update
Example Response:
{
"id": 0,
"scope_group_ids": [
0
],
"devices": [
{
"identifier": "string",
"identifier_type": "hw-address",
"metadata": null,
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string"
}
],
"created_at": 0,
"updated_at": 0,
"created_by": "string",
"updated_by": "string",
"name": "string",
"expiration_period_seconds": 0
}
POST /v1/dhcp/devicegroup/{deviceGroupId}/remove
POSTRemove devices from a device group
Removes devices from a specific device group using the MAC address or DHCP unique ID (DUID) of a device.
Path Parameters:
| Parameter | Type | Description |
| deviceGroupId | integer | Required. The ID of the device group that you want to remove. You can find this value by viewing all device groups. |
Body Parameters:
The payload should be sent as a JSON array of MAC addresses or DUIDs.
Copy CodeRemoves a specific device from a device group
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '[ "aa:bb:cc:dd:ee:f2" ]' https://{api.mycompany.net}/v1/dhcp/devicegroup/3/remove
Example Request:
$ curl -X POST -H 'X-NSONE-Key: $API_KEY' -d '[ "aa:bb:cc:dd:ee:f2" ]' \ https://{api.mycompany.net}/v1/dhcp/devicegroup/{value}/remove
GET /v1/dhcp/devicegroup/:deviceGroupId/exists
GETVerify whether a device exists within a device group
Determines whether a specific device exists within a specific device group using the identifier of the device (MAC address).
Path Parameters:
| Parameter | Type | Description |
| deviceGroupId | integer | Required. The ID of the device group that you want to remove. You can find this value by viewing all device groups. |
Body Parameters:
The payload should be sent as a JSON object that contains the identifier and a MAC address.
Copy CodeVerifies whether a device exists in the specified device group
$ curl -X GET -H 'X-NSONE-Key: $API_KEY' -d '{"identifier": "aa:bb:cc:dd:ee:ff"}' https://{api.mycompany.net}/v1/dhcp/devicegroup/2/exists
Example Request:
$ curl -X GET -H 'X-NSONE-Key: $API_KEY' -d '{ \
"identifier": "aa:bb:cc:dd:ee:ff", \
}' https://{api.mycompany.net}/v1/dhcp/devicegroup/2/exists
IPAM
Networks
GET /v1/ipam/network
GET View a list of networks
Returns a list of available IPAM networks.
Copy CodeReturns a list of IPAM networks
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.nsone.net}/v1/ipam/network
Example URL:
https://api.mycompany.net/v1/ipam/network
Example Response:
[
{
"desc": "Created for demonstration purposes.",
"name": "Global (Default)",
"blocked_tags": [],
"local_tags": [],
"tags": {},
"free_addresses_v4": "0",
"free_addresses_v6": "0",
"id": 1,
"num_prefixes_v4": "1",
"num_prefixes_v6": "0",
"total_addresses_v4": "0",
"total_addresses_v6": "0",
"used_addresses_v4": "0",
"used_addresses_v6": "0"
},
{
"desc": "Created for demonstration purposes.",
"name": "Private (Default)",
"rt": "1:2",
"blocked_tags": [],
"local_tags": [
"Network",
"Use Case"
],
"tags": {
"Network": "0",
"Use Case": "Demos"
},
"free_addresses_v4": "0",
"free_addresses_v6": "0",
"id": 3,
"num_prefixes_v4": "29",
"num_prefixes_v6": "0",
"total_addresses_v4": "0",
"total_addresses_v6": "0",
"used_addresses_v4": "0",
"used_addresses_v6": "0"
},
{
"desc": "Updated text description",
"name": "Corporate HQ Network",
"rt": "123:456",
"blocked_tags": [],
"local_tags": [
"Use Case",
"auth:Security Level"
],
"tags": {
"Use Case": "API Examples",
"auth:Security Level": "2"
},
"free_addresses_v4": "0",
"free_addresses_v6": "0",
"id": 4,
"num_prefixes_v4": "0",
"num_prefixes_v6": "0",
"total_addresses_v4": "0",
"total_addresses_v6": "0",
"used_addresses_v4": "0",
"used_addresses_v6": "0"
}
]
GET /v1/ipam/network/:networkID
GET View network details
Returns configuration details for the IPAM network specified in the URL path by its unique networkID.
Path Parameters:
| Parameter | Type | Description |
| networkID | integer | (Required) Unique identifier of the network. |
Query Parameters:
| Parameter | Type | Description |
| expand | boolean | (Optional) Indicates whether or not to include a list of child addresses/subnets in the response. |
Copy CodeReturns details for the specified IPAM network
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.nsone.net}/v1/ipam/network/:networkid
Example URL:
https://api.mycompany.net/v1/ipam/network/{networkId}
Example Response:
{
"name": "string",
"desc": "string",
"rt": "string",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"id": 0,
"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"
}
GET /v1/ipam/network/:networkID/report
GET View a network report
Returns a usage report for the network specified in the URL path by its unique networkID.
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
Path Parameters:
| Parameter | Type | Description |
| networkID | integer | (Required) Unique identifier of the IPAM network. |
Query Parameters:
| Parameter | Type | Description |
| export | string | The file type of the report that should be generated. Can be one of the following file types: json, xml, csv, pdf, xslx, or html. |
Copy CodeReturns a network usage report
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.nsone.net}/v1/ipam/network/{networkID}/report
Copy CodeExports a network report in PDF format
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/ipam/network/{networkId}/report?export=PDF
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 /v1/ipam/network
PUT Create a network
Creates a new IPAM network.
Request body parameters:
| Parameter | Type | Description |
| name | string | Required. A unique name for the IPAM network. |
| desc | string | Description of the IPAM network for internal reference. |
| rt | string | Indicates the routing table. Can be in the ASN:id (123:456) or the IP:id (1.3.3.7:456) format. |
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets or addresses. |
| blocked_tags | array of strings | List of tags that are blocked by this network. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeCreates a new IPAM network
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "name":"{string}", "desc":"{string}", "rt":"{string}", "tags": { "key": "value" "key": "value" } }' https://{api.mycompany.net}/v1/ipam/network
Example URL:
https://api.mycompany.net/v1/ipam/network
Example Request:
{
"name": "Corporate HQ Network",
"rt": "123:456"
"desc": "Optional text description",
"tags": {
"auth:Security Level": "1",
"Use Case": "API Examples"
}
}
Example Response:
{
"desc": "Optional text description",
"name": "Corporate HQ Network",
"rt": "123:456",
"blocked_tags": [],
"local_tags": [
"Use Case",
"auth:Security Level"
],
"tags": {
"Use Case": "API Examples",
"auth:Security Level": "1"
},
"free_addresses_v4": "0",
"free_addresses_v6": "0",
"id": 4,
"num_prefixes_v4": "0",
"num_prefixes_v6": "0",
"total_addresses_v4": "0",
"total_addresses_v6": "0",
"used_addresses_v4": "0",
"used_addresses_v6": "0"
}
POST /v1/ipam/network/:networkID
POST Update a network
Updates an existing IPAM network specified in the URL path by its unique networkID.
Path parameters:
| Parameter | Type | Description |
| networkID | integer | Required. Unique identifier for the network. |
Request body parameters:
| Parameter | Type | Description |
| name | string | Required. A unique name for the IPAM network. |
| desc | string | Description of the IPAM network for internal reference. |
| rt | string | Indicates the routing table. Can be in either ASN:id (123:456) or IP:id (1.3.3.7:456) format. |
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets/addresses. |
| blocked_tags | array of strings | List of tags that are blocked by this network. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeUpdates an existing IPAM network
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "name":"{string}", "desc":"{string}", "rt":"{string}", "tags": { "key": "value" "key": "value" } }' https://{api.mycompany.net}/v1/ipam/network/:networkID
Example URL:
https://api.mycompany.net/v1/ipam/network/{networkId}
Request URL:
Example Request:
{
"name": "US-East-22",
"desc": "US East Region"
}
Example Response:
{
"name": "string",
"desc": "string",
"rt": "string",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"id": 0,
"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"
}
DELETE /v1/ipam/network/:networkID
DELETE Remove a network
Deletes the IPAM network specified in the URL path by its unique networkID.
Path parameters:
| Parameter | Type | Description |
| networkID | integer | (Required) Unique identifier for the IPAM network. |
Copy CodeDeletes an IPAM network
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/network/{networkID}
Example URL:
https://api.mycompany.net/v1/ipam/network/{networkId}
Subnets (Addresses)
GET /ipam/address
GETView a list of root addresses
Returns a list of all root addresses (i.e. parent_id == 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,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true
}
]
GET /v1/ipam/address/:addressID
GETView subnet details
Returns the configuration details for the IP address specified in the URL path by its unique addressID. You can find the address ID by viewing a list of root addresses and reviewing the id parameter.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) Unique identifier for the subnet. |
Copy CodeReturns details for the specified subnet
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressid
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true,
"parent": {
"prefix": "10.0.0.0/16",
"network_id": 12,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true
}
}
GET /v1/ipam/address/:addressID/children
GETView address children
Returns a list of all direct child addresses/subnets (i.e. addresses with parent_id=<address_id>) for the specified IP address.
Path parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) Unique identifier for the subnet |
Example Response:
[
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true
}
]
GET /v1/ipam/address/search
GETSearch for an address object by filter
Returns a filtered list of addresses based on parameters specified in the query.
Query Parameters:
| Parameter | Type | Description |
| network_id | integer | Unique identifier for the network. If set, returns addresses within the specified network. |
| asc_desc | string | Indicates the sort order (ascending or descending) of results in the response. Enum: "ASC" or "DESC" |
| mask | array of integers | Specifies a mask for the query by which to filter. |
| max | integer | Indicates the maximum number of results to display in the response. |
| name | string | Name of the subnet to search. Search for an exact name by including the full string (e.g. name) or with a partial pattern search (e.g. na*). |
| order_by | string | Sorts the results by one of the fields. Default is id. Enum: "children", "free_addresses", "mask", "name", "network_id", "parent_id", "prefix", "total_addresses", or "used_addresses". |
| prefix | string | The address of the prefix to search for (e.g. '10.0.0.0') |
| tag | array of strings | Filter search by one or more tags. |
| status | string | Filter search by the type of subnet. Enum: "assigned" or "planned" |
Copy CodeReturns a filtered list of address objects
https://api.mycompany.net/v1/ipam/address/search?network_id=1&asc_desc=ASC&max=5&status=assigned&tag=NA&order_by=name&mask=24
Example URL:
https://api.mycompany.net/v1/ipam/address/search?network_id=1
Example Response:
[
{
"free_addresses": "65536",
"parent_id": 0,
"blocked_tags": [],
"local_tags": [],
"tags": {},
"network_id": 1,
"children": 0,
"prefix": "10.0.0.0/16",
"used_addresses": "0",
"total_addresses": "65536",
"status": "assigned",
"id": 1
}
]
GET /v1/ipam/address/:addressID/parent
GETView address parent
Returns the parent address for the address (subnet) specified in the URL path by its unique addressID.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) Unique identifier for the address (subnet) |
Example URL:
https://api.mycompany.net/v1/ipam/address/{addressId}/parent
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true
}
GET /v1/ipam/address/:addressID/adjacent
GETReturn next (or previous) available prefix
Retrieves next or previous (adjacent) unallocated prefix of the selected address' size.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) ID of the address requested for which you want the next (or previous) prefix |
Query Parameters:
| Parameter | Type | Description |
| previous | boolean | If set to "true," the previous free prefix is returned (instead of the next). |
Copy CodeRetrieves the next available IP address
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressID/adjacent
Copy CodeRetrieves previously available IP address
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressID/adjacent?previous=true
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 /v1/ipam/address/:addressId/next
GETReturn the next available prefix (/32 or /128)
Returns the next available /32 prefix (for IPv4) or /128 prefix (for IPv6) within a subnet.
The addressId refers to the unique identifier for the container of the address whose next available prefix you are requesting.
The next endpoint for any address (subnets or hosts) returns the prefix of the next available subnet of the given size. The available prefix is only returned, not reserved. If the subnet has children, each child is recursively searched until an `assigned` subnet is found, and the next free address or subnet is retrieved. If the targeted address is set to `planned` status and has no children that are set to `assigned`, a `GET` request returns an error.
If the size of the desired subnet is not specified, the default is `/32` for IPv4 addresses and `/128` for IPv6 addresses.
Copy CodeReturns the next available /32 or /128 prefix within the specified address
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressId/next
Example Response:
{
"prefix": "10.0.0.13/32"
}
GET /v1/ipam/address/:addressId/next/:size
GETReturn the next available prefix (by size)
Returns the next available prefix for the specified address `size` within a subnet. This command does not reserve the prefix.
The addressId refers to the unique identifier for the container of the address whose next available prefix you are requesting. size refers to the size of the next available subnet to find.
The next endpoint for any address (subnet or hosts) returns the prefix of the next available subnet of the given size. The available prefix is only returned, not reserved. If the subnet has children, each child is recursively searched until an assigned subnet is found, and the next free address or subnet is retrieved. If the target address is set to planned status and has no children that are set to assigned, a GET request returns an error.
Copy CodeReturns the next available prefix for the specified address and size within a subnet.
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressId/next/:size
Example Response:
{
"prefix": "10.0.0.13/16"
}
PUT /v1/ipam/address
PUTCreate a subnet
Creates a new subnet (an object containing one or more IP addresses).
Query Parameters:
| Parameter | Type | Description |
| parent | boolean | Optional. Indicates whether or not to include the parent in the parent field. |
Request body parameters:
| Parameter | Type | Description |
| prefix | string | Required. An IPv4 or IPv6 subnet in CIDR notation |
| network_id | integer | Required. Unique identifier of the containing network |
| parent_id | integer | Unique identifier of the parent address. A value of 0 indicates a root address (i.e. no parent). |
| name | string | Name for the new subnet for internal reference. |
| desc | string | Description of the new subnet for internal reference. |
| status | string | Current status of the subnet. Enum: "assigned" or "planned" (default is "planned"). Within a subnet with a status of "assigned", you can only create /32 (for IPv4) or /128 addresses (for IPv6). |
| hostname | string | Host name associated with this address or subnet. |
| forward_zone_handle | string | Handle for the zone in which the A/AAAA record will be created or updated. |
| reverse_zone_handle | string | Handle for the zone in which the PTR record will be created. |
| tags | array of strings | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets or addresses. |
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. For each blocked tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). |
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,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true,
"parent": {
"prefix": "10.0.0.0/16",
"network_id": 12,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true
}
}
Example Request:
{
"prefix": "192.168.0.0/24",
"status": "assigned",
"desc": "Optional text description",
"tags" : {
"Usage":"VOIP"
},
"network_id": 9
}
Example Response:
{
"network_id": 9,
"parent_id": 0,
"prefix": "192.168.0.0/24",
"desc": "Optional text description",
"status": "assigned",
"blocked_tags": [],
"local_tags": [
"Usage"
],
"tags": {
"Usage": "VOIP",
"Use Case": "API Examples",
"auth:Security Level": "1"
},
"children": 0,
"free_addresses": "256",
"id": 46,
"total_addresses": "256",
"used_addresses": "0"
}
POST /v1/ipam/address/:addressID
POSTEdit a subnet
Modifies the configuration of the subnet specified in the URL path by its unique addressID.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | Required. Unique identifier of the subnet you are updating. |
Query Parameters:
| Parameter | Type | Description |
| parent | boolean | Optional. Indicates whether or not to include the parent in the parent field. |
Request body parameters:
| Parameter | Type | Description |
| name | string | Name for the new subnet for internal reference. |
| desc | string | Description of the new subnet for internal reference. |
| status | string | Current status of the subnet. Enum: "assigned" or "planned" (default is "planned"). Within a subnet with a status of "assigned", you can only create /32 (for IPv4) or /128 addresses (for IPv6). |
| hostname | string | Host name associated with this address or subnet. |
| forward_zone_handle | string | Handle for the zone in which the A/AAAA record will be created or updated. |
| reverse_zone_handle | string | Handle for the zone in which the PTR record will be created. |
| tags | array of strings | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets or addresses. |
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. For each blocked tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). |
Copy CodeUpdates a subnet
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "prefix":"{string}", "network_id":"{integer}", "parent_id":"{integer}", "name":"{string}", "desc":"{string}", "status":"{enum}", "tags": { "key": "value" "key": "value" } }' https://{api.mycompany.net}/v1/ipam/address
Example URL:
https://api.mycompany.net/v1/ipam/address/:addressID
Example Request:
{
"name": "New Branch Office",
"status": "addigned",
"desc": "9999 King Street West, Suite 9999: City, State"
}
Example Response:
{
"network_id": 9,
"parent_id": 0,
"prefix": "192.168.0.0/24",
"desc": "9999 King Street West, Suite 9999: City, State",
"name": "New Branch Office",
"status": "assigned",
"blocked_tags": [],
"local_tags": [
"Usage"
],
"tags": {
"Usage": "VOIP",
"Use Case": "API Examples",
"auth:Security Level": "1"
},
"children": 0,
"free_addresses": "256",
"id": 46,
"total_addresses": "256",
"used_addresses": "0"
}
Example Request:
{
"status": "assigned"
}
Example Response:
{
"prefix": "10.0.0.0/16",
"network_id": 12,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true,
"parent": {
"prefix": "10.0.0.0/16",
"network_id": 12,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true
}
}
POST /v1/ipam/address/:addressID/split
POSTSplit a subnet
Splits an entire block of unassigned IP space into equal pieces. This will not function with ranges or individual hosts.
Note: Normal breaking out of a subnet is done with the standard PUT route (e.g. If the root address is a /24, the request for /29s will split it into 32 /29s).
- Only
plannedsubnets can be split - Name and description will be unset on children
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | Required. Unique identifier for the address (subnet) you are splitting. |
Request Body Parameters:
| Parameter | Type | Description |
| prefix | integer | Required. |
Copy CodeSplits the address (subnet)
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "prefix":0 }' https://{api.mycompany.net}/v1/ipam/address/:addressID/split
Example URL:
https://api.mycompany.net/v1/ipam/address/{addressId}/split
Example Request:
{
"prefix": 0
}
Example Response:
{
"root_address_id": 0,
"prefix_ids": [
0
]
}
POST /v1/ipam/address/merge
POSTMerge addresses
Merges two contiguous address spaces.
Request Body Parameters:
| Parameter | Type | Description |
| root_address_id | integer | Required. Unique identifier for the root address |
| merged_address_id | integer | Required. Unique identifier for the address you are merging with the root address |
Copy CodeMerges two addresses (subnets)
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "root_address_id": {int}, "merged_address_id": {int}}' https://{api.mycompany.net}/v1/ipam/address/merge
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,
"parent_id": 1,
"desc": "Main subnet for US-EAST-1",
"name": "US-EAST-1 Main",
"status": "assigned",
"hostname": "happytree",
"forward_zone_handle": "internal-example.com",
"reverse_zone_handle": "internal-0.0.10.in-addr.arpa",
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
],
"total_addresses": "65536",
"children": 2,
"free_addresses": "12321",
"id": 1209,
"used_addresses": "53215",
"dhcp_scoped": true
}
DELETE /v1/ipam/address/:addressID
DELETEDelete a subnet
Deletes the subnet specified in the URL path by its unique addressID.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) Unique identifier for the subnet |
Query Parameters:
| Parameter | Type | Description |
| cascade_records | boolean | Indicates whether or not to delete DNS records linked to this address. |
Copy CodeDeletes the subnet
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressID
Pools
GET /v1//ipam/address/:addressID/pool
GETList pools (IP range) within a subnet
Returns a list of pools (ranges of IP addresses) within the subnet specified in the URL path by its unique addressID.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) Unique identifier for the subnet |
Copy CodeReturns a list of pools within a subnet
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/:addressID/pool
Example Response:
[
{
"id": 0,
"range": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
]
}
]
GET /v1/ipam/address/:addressID/pool/:poolID
GETView pool details
Returns details about the specified IP pool.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) Unique identifier for the subnet with which this pool is associated. |
| poolID | integer | (Required) Unique identifier for the IP pool for which you are requesting details |
Copy CodeReturns details for the specified IP pool
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressID/pool/:poolID
Example Response:
{
"id": 0,
"range": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
]
}
PUT /v1/ipam/address/:addressID/pool
PUTCreate an IP pool
Creates a new IP pool within the subnet specified in the URL path by its addressID. The pool must be from the network.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | Required. Unique identifier for the subnet within which the new pool will be contained. |
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
| range | string | Required. Indicates the IP range of the pool using one of the following formats: CIDR, "IP-IP," or "IP,count" | |||||||||||||||
| options | array of objects | Required. Set of DHCP options to apply to this pool. Each option must include a name and value. Ex. "options": [{"name": "dhcpv4/routers", "value": ["127.0.0.2"]}].
| |||||||||||||||
| client_class | string | Name of the client class associated with this pool. | |||||||||||||||
| required_client_class | array of strings | Array of required client class names. | |||||||||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets or addresses. | |||||||||||||||
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeCreates an IP pool
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"range": "192.168.0.1-192.168.0.50", "options": [{ "name": "dhcpv4/routers", "value": ["127.0.0.2"] }], }], "tags": { "Vendor": "Shortel", "Model": "IP480" } }' https://{api.mycompany.net}/v1/ipam/address/:addressID/pool
Example Request:
{
"range": "192.168.0.1-192.168.0.50",
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}],
}],
"tags": {
"Vendor": "Shortel",
"Model": "IP480"
}
}
Example Response:
{
"id": 1,
"range": "192.168.0.1-192.168.0.50",
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}],
"require_client_classes": [],
"blocked_tags": [],
"local_tags": [
"Model",
"Vendor"
],
"tags": {
"Model": "IP480",
"Usage": "VOIP",
"Use Case": "API Examples",
"Vendor": "Shortel",
"auth:Security Level": "1"
}
}
Example Request:
{
"range": "1.1.1.12/30",
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
],
"tags": {
"key": "value"
}
}
Example Request:
{
"range": "192.168.0.20,10",
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
],
"tags": {
"key": "value"
}
}
POST /v1/ipam/address/:addressID/pool/:poolID
POSTUpdate an IP pool
Modifies the configuration for the pool (IP range) specified in the URL path by its unique poolID. The pool must be from the network.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | Required. Unique identifier for the subnet within which the new pool will be contained. |
| poolID | integer | Required. Unique identifier for the IP pool to edit. |
Request Body Parameters:
| Parameter | Type | Description | |||||||||||||||
| options | array of objects | Required. Set of DHCP options to apply to this pool. Each option must include a name and value. Ex. "options": [{"name": "dhcpv4/routers", "value": ["127.0.0.2"]}].
| |||||||||||||||
| client_class | string | Name of the client class associated with this pool. | |||||||||||||||
| required_client_class | array of strings | Array of required client class names. | |||||||||||||||
| tags | object | All local and inherited tags. Local tags are tags set directly on objects. Inherited tags are inherited from parent objects. For each tag, you must indicate the property name and (optionally) specify a corresponding value (i.e. "{property_name}":"{value}"). Tags specified here are inherited by any child subnets or addresses. | |||||||||||||||
| blocked_tags | array of strings | List of tags that are blocked by this node. Blocked tags are tags that you suppress or prevent from being applied to child objects. |
Copy CodeEdits the IP pool configuration
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "options": [ { "name": "dhcpv4/routers", "value": ["127.0.0.2"] }], "tags": {"property_name": "value"} }' https://{api.mycompany.net}/v1/ipam/address/:addressID/pool
Example Request:
{
"options": [
{
"name": "dhcpv4/routers",
"value": [
"127.0.0.2"
]
}
],
"tags": {
"key": "value"
}
}
Example Response:
{
"id": 0,
"range": "string",
"options": [
{
"name": "dhcpv4/boot-file-name",
"value": "/boot.img"
}
],
"client_class": "string",
"require_client_classes": [
"string"
],
"tags": {
"property1": "string",
"property2": "string"
},
"local_tags": [
"string"
],
"blocked_tags": [
"string"
]
}
DELETE /v1/ipam/address/:addressID/pool/:poolID
DELETEDelete an IP pool
Deletes an IP pool from the associated address/subnet.
Path Parameters:
| Parameter | Type | Description |
| addressID | integer | (Required) Unique identifier for the subnet within which the pool is located. |
| poolID | integer | (Required) Unique identifier for the IP pool you are deleting. |
Copy CodeDeletes the IP pool
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/address/:addressID/pool/:poolID
GET /v1/ipam/tags/values
GETView all tag values
Returns all unique existing tags and values (from all objects). This list of tags can be used to populate an autocomplete list in the portal.
Copy CodeReturns all existing tags and values from all objects
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.nsone.net/v1/ipam/tags/values
Example Response:
[
{
"key": "string",
"value": "string"
}
]
Dynamic DNS
NS1 DDI customers can create and manage remote zones and servers to configure dynamic DNS (DDNS).
Remote zones
GET /v1/dhcp/scopegroup/ddnszone
GET List DDNS (remote) zones for all scope groups
List DDNS (remote) zones configured for scope groups to which to send DDNS updates upon DHCP lease change events.
Copy CodeReturns all remote DDNS zones
curl -X GET -H 'X-NSONE-Key: $API_KEY' https://{api.mycompany.net}/v1/dhcp/scopegroup/ddnszone
Example Response:
[
{
"remote_server_ids": [
0
],
"remote_servers": [
{
"id": 0,
"update_security_level": "secure_only"
}
],
"update_strategy": "all",
"enabled": true,
"zone": "string",
"scope_group_id": 0,
"connected": true
}
]
GET /v1/dhcp/scopegroup/:scopegroupID/ddnszone
GET List DDNS (remote) zones for one scope group
Returns a list of remote zones configured for the specified scope group (using the scope group ID) to which to send DDNS updates upon DHCP lease change events.
Path Parameters:
| scopegroupID | integer | Unique identifier of the scope group associated with the list of DDNS (remote) zones you are requesting |
Copy CodeReturns all zones associated with the specified scope group
curl -X GET -H 'X-NSONE-Key: $API_KEY' https://{api.mycompany.net}/v1/dhcp/{scopegroupID}/ddnszone
Example Response:
[
{
"remote_server_ids": [
0
],
"remote_servers": [
{
"id": 0,
"update_security_level": "secure_only"
}
],
"update_strategy": "all",
"enabled": true,
"zone": "string",
"scope_group_id": 0,
"connected": true
}
]
GET /v1/dhcp/scopegroup/:scopegroupID/ddnszone/:ddnsZoneName
GET View DDNS (remote) zone details
Returns zone configuration details based on the specified scope group ID and DDNS zone name. This is the zone to which DDNS updates are sent upon lease change events.
Path Parameters:
| scopegroupID | integer | (Required) Unique identifier for the scope group associated with the remote zone |
| ddnsZoneName | string | (Required) Name of the DDNS zone |
Copy CodeReturns DDNS zone details
curl -X GET -H 'X-NSONE-Key: $API_KEY' https://{api.mycompany.net}/v1/dhcp/scopegroup/{scope_group_id}/ddnszone/{ddns_zone_name}
Example Response:
{
"remote_server_ids": [
0
],
"remote_servers": [
{
"id": 0,
"update_security_level": "secure_only"
}
],
"update_strategy": "all",
"enabled": true,
"zone": "string",
"scope_group_id": 0,
"connected": true
}
PUT /v1/dhcp/scopegroup/:scopegroupID/ddnszone
PUT Create a DDNS (remote) zone
Creates a remote zone for the specified scope group to which to send dynamic DNS (DDNS) updates upon DHCP lease change events.
Path Parameters:
| scopegroupID | integer | (Required) Unique identifier of the scope group associated with the new remote zone |
Request Body Parameters:
| zone | string | (Required) Name of the DDNS zone you are creating. |
| remote_servers | array of objects | Array of remote server objects. Each array contains id (integer) and update_security_level (string). |
| id | integer | (part of remote_servers array) Unique identifier of the remote server |
| update_security_level | string (enum) | (part of remote_servers array) Indicates the security level to use for DDNS updates. If empty, the security level from the corresponding DDNS remote server is used. Supported values: " " (default),"secure_only", "nonsecure_then_secure", "nonsecure_only", "gss_tsig_only", "tsig_only" |
| update_strategy | string | Indicates the strategy to use for multiple remote servers. Supported values: "all" (default) or "any". |
| enabled | boolean | Indicates the status of the DDNS zone. |
Copy CodeCreates a remote zone
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"zone": "example.com", "remote_servers": [{"id": 1,"update_security_level": "nonsecure_only"}],"update_strategy": "all", "enabled": true }' https://{api.mycompany.net}/v1/dhcp/scopegroup/:scopeGroupId/ddnszone
Example Request:
{
"zone": "example.com",
"remote_servers": [
{
"id": 1,
"update_security_level": "nonsecure_only"
}
],
"update_strategy": "all",
"enabled": true
}
Example Response:
{
"remote_server_ids": [
0
],
"remote_servers": [
{
"id": 0,
"update_security_level": "secure_only"
}
],
"update_strategy": "all",
"enabled": true,
"zone": "string",
"scope_group_id": 0,
"connected": true
}
POST /v1/dhcp/scopegroup/:scopegroupID/ddnszone/:ddnsZoneName
POST Edit a DDNS (remote) zone
Updates a DDNS (remote) zone configuration for the specified scope group using the zone name and scope group ID.
Path Parameters:
| scopegroupID | integer | (Required) Unique identifier of the scope group |
| ddnsZoneName | string | (Required) Name of the DDNS zone you are editing |
Request Body Parameters:
| remote_servers | array of objects | Array of remote server objects. Each array includes the server id and update_security_level |
| id | integer | (part of remote_servers array) Unique identifier for the remote server associated with this remote zone. |
| update_security_level | string (enum) | (part of remote_servers array) Indicates the security level to use for DDNS updates. If empty (default), the update security level from the corresponding remote server is used. Supported values: "secure_only", "nonsecure_then_secure", "nonsecure_only", "gss_tsig_only", "tsig_only", "" (default) |
| update_strategy | string (enum) | Indicates the strategy to use for multiple remote servers. Supported values: "all" (default) or "any" |
| enabled | boolean | Indicates the status of the DDNS zone |
Copy CodeUpdates a DDNS remote zone
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{"remote_servers": [{"id": 1,"update_security_level": "nonsecure_only"}], "enabled": true }' https://{api.mycompany.net}/v1/dhcp/scopegroup/{scope_group_id}/ddnszone/{ddns_zone_name}
Example Request:
{
"zone": "example.com",
"remote_servers": [
{
"id": 1,
"update_security_level": "nonsecure_only"
}
],
"update_strategy": "all",
"enabled": true
}
DELETE /v1/dhcp/scopegroup/:scopegroupID/ddnszone/:ddnsZoneName
DELETE Delete a DDNS (remote) zone
Removes a DDNS remote zone for the specified scope group.
Path Parameters:
| scopegroupID | integer | (Required) Unique identifier of the scope group with which the zone is associated. |
| ddnsZoneName | string | (Required) Name of the DDNS zone you are deleting. |
Remote servers
GET /v1/dhcp/ddns/remoteserver
GETList all DDNS (remote) servers
Returns a list of all DDNS remote server configurations.
Copy CodeLists all remote servers
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/dhcp/ddns/remoteserver
Example Response:
[
{
"id": 12,
"mname_server": "127.0.0.1",
"mname_port": 53,
"kdc_server": "127.0.0.1",
"kdc_port": 88,
"update_security_level": "secure_only",
"update_timeout": 0,
"disable_insecure_updates": false,
"principal_id": 8,
"tsig_key": "tsig.foo.org"
}
]
GET /v1/dhcp/ddns/remoteserver/:remote_server_id
GETView DDNS (remote) server details
Returns configuration details of the DDNS remote server specified in the URL path by its unique remote ID.
Copy CodeReturns remote server configuration details
curl -X GET -H 'X-NSONE-Key: $API_KEY' https://{api.mycompany.net}/v1/dhcp/ddns/remoteserver/{remoteId}
Example Response:
{
"id": 12,
"mname_server": "127.0.0.1",
"mname_port": 53,
"kdc_server": "127.0.0.1",
"kdc_port": 88,
"update_security_level": "secure_only",
"update_timeout": 0,
"disable_insecure_updates": false,
"principal_id": 8,
"tsig_key": "tsig.foo.org"
}
PUT /v1/dhcp/ddns/remoteserver
PUTAdd a DDNS (remote) server
Adds a DDNS remote server configuration. The only required field is mname_server. kdc_server and principal_id are used for GSS-TSIG authentication. If your primary name server or KDC are running on non-standard ports, you may also include mname_port or kdc_port.
Request Body Parameters:
| Parameter | Type | Description |
| mname_server | string | (Required) FQDN or IP address of the authoritative DNS server. |
| mname_port | integer | Port on which the authoritative DNS server is running. |
| kdc_server | string | FQDN or IP address of the Kerberos server |
| kdc_port | integer | Port on which the Kerberos server is running |
| update_security_level | string | Security level used for DDNS updates. Enum: "secure_only", "nonsecure_then_secure", "nonsecure_only", "gss_tsig_only", or "tsig_only". Default is "nonsecure_then_secure". |
| update_timeout | integer | Amount of time (in milliseconds) between updates sent to this server. |
| principal_id | integer | Unique identifier of the principal to use for authentication to the Kerberos server. |
| disable_insecure_updates | boolean | If set to "true," disables insecure updates to this server. |
| tsig_key | string | Existing TSIG key name that will be used for authentication. |
Copy CodeAdds a new remote server for DDNS updates
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "mname_server":"{mname_server}", "mname_port":{mname_port}, "kdc_server":"{kdc_server}", "kdc_port":{kdc_port}, "update_security_level":"{security_level}], "principal_id":{principal_id}, "tsig_key":"{string}" }' https://{api.mycompany.net}/v1/dhcp/ddns/remoteserver
Example Request:
{
"mname_server": "127.0.0.1",
"mname_port": 53,
"kdc_server": "127.0.0.1",
"kdc_port": 88,
"update_security_level": "secure_only",
"update_timeout": 0,
"disable_insecure_updates": false,
"principal_id": 8,
"tsig_key": "tsig.foo.org"
}
Example Response:
{
"id": 12,
"mname_server": "127.0.0.1",
"mname_port": 53,
"kdc_server": "127.0.0.1",
"kdc_port": 88,
"update_security_level": "secure_only",
"update_timeout": 0,
"disable_insecure_updates": false,
"principal_id": 8,
"tsig_key": "tsig.foo.org"
}
POST /v1/dhcp/ddns/remoteserver/:removeserverID
POSTUpdate a DDNS (remote) server
Updates the configuration details for the DDNS remote server specified in the URL path by its unique remoteID.
Path Parameters:
| Parameter | Type | Description |
| remoteserverID | integer | (Required) Unique identifier for the DDNS remote server configuration |
Request Body Parameters:
| Parameter | Type | Description |
| mname_server | string | (Required) FQDN or IP address of the authoritative DNS server. |
| mname_port | integer | Port on which the authoritative DNS server is running. |
| kdc_server | string | FQDN or IP address of the Kerberos server |
| kdc_port | integer | Port on which the Kerberos server is running |
| update_security_level | string | Security level used for DDNS updates. Enum: "secure_only", "nonsecure_then_secure", "nonsecure_only", "gss_tsig_only", or "tsig_only". Default is "nonsecure_then_secure". |
| principal_id | integer | Unique identifier of the principal to use for authentication to the Kerberos server. |
| update_timeout | integer | Timeout (in milliseconds) for updates sent to this server. |
| disable_insecure_updates | boolean | If set to "true," disables insecure updates to this server. |
| tsig_key | string | Existing TSIG key name that will be used for authentication. |
Copy CodeUpdates the remote server
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "mname_server":"{string}", "mname_port":{int}, "kdc_server":"{string}", "kdc_port":{int}, "update_security_level":"{enum}", "principal_id":{int}, "tsig_key": "{string}"}' https://{api.mycompany.net}/v1/dhcp/ddns/remoteserver/{remote_server_id}
Example Request:
{
"mname_server": "127.0.0.1",
"mname_port": 53,
"kdc_server": "127.0.0.1",
"kdc_port": 88,
"update_security_level": "secure_only",
"update_timeout": 0,
"disable_insecure_updates": false,
"principal_id": 8,
"tsig_key": "tsig.foo.org"
}
Example Response:
{
"id": 12,
"mname_server": "127.0.0.1",
"mname_port": 53,
"kdc_server": "127.0.0.1",
"kdc_port": 88,
"update_security_level": "secure_only",
"update_timeout": 0,
"disable_insecure_updates": false,
"principal_id": 8,
"tsig_key": "tsig.foo.org"
}
DELETE /v1/dhcp/ddns/remoteserver/:remoteserverID
DELETEDelete a DDNS (remote) server
Removes the DDNS remote server specified in the path by its unique remote server ID.
Path Parameter:
| remoteserverID | string | (Required) Unique identifier of the remote server you are deleting. |
Copy CodeRemoves a remote server configuration
curl -X DELETE -H 'X-NSONE-Key: $API_KEY' https://{api.mycompany.net}/v1/dhcp/ddns/remoteserver/{remote_server_id}
Kerberos
PUT /v1/gsstsig/keytab
PUTUpload Kerberos keytab file
Upload a Kerberos keytab file using content-type application/octet-stream with the binary keytab file as the content of the request body. The principals within the keytab are parsed and stored individually. Any principals that match an existing principal will overwrite the old principal with the new information from the keytab file upload.
Copy CodeUploads the keytab file
curl --request PUT "https://{local_host}/gsstsig/keytab" \ --header "X-NSONE-Key: $API_KEY" \ --header "Content-Type: application/octet-stream" \ --data-binary '{file_path}'
Example Request:
curl --request PUT "https://api.mycompany.net/v1/gsstsig/keytab" \ --header "X-NSONE-Key: $API_KEY" \ --header "Content-Type: application/octet-stream" \ --data-binary '@/Path/To/Example.keytab'
Example Response:
[
{
"principal_id": 12,
"num_components": 2,
"realm": "example.ns1.com",
"components": [
"DNS","user"
],
"name_type": 1,
"timestamp": 1567784394,
"kvno8": 1,
"kvno": 1,
"key_type": 18,
"networks": [
1
]
}
]
GET /v1/gsstsig/principal
GETRetrieve Kerberos principals
Returns all Kerberos principals
Copy CodeReturns a list of Kerberos principals
curl -X GET -H 'X-NSONE-Key: $API_KEY' https://{api.mycompany.net}/v1/gsstsig/principal
Example Response:
[
{
"principal_id": 12,
"num_components": 2,
"realm": "example.ns1.com",
"components": [
"user"
],
"name_type": 1,
"timestamp": 1567784394,
"kvno8": 1,
"kvno": 1,
"key_type": 18,
"networks": [
1
]
}
]
Delete Kerberos principal
Deletes the Kerberos principal specified in the request URL.
Copy CodeDeletes the specified Kerberos principal
curl -X DELETE -H 'X-NSONE-Key: $API_KEY' https://{api.mycompany.net}/v1/gsstsig/principal/{principal_id}
POST /v1/gsstsig/principal/network/{network_id}
POSTModify the principals attached to a network
Assign or modify which principals are attached to a network. Note that lists of multiple principal IDs are accepted.
Copy CodeModifies a Kerberos principal
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "principal_ids": [id] }' https://{api.mycompany.net}/v1/gsstsig/network/{network_id}
Example Request:
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{
"principal_ids": [1]
}' https://api.mycompany.net/v1/gsstsig/network/1
| Parameter | Type | Description |
| network_id | integer | network identifier |
| principal_ids | array of integers | Kerberos principal identifier(s) |
Fleet & service management
Fleet management
System administrators with Cloud-Managed DDI deployments can use the fleet management endpoints to manage their edge nodes and specify which service components (i.e., software modules) to deploy on the nodes.
GET /v1/fleet/node/deploy
GET View the intended configuration for all nodes
Returns a list of edge nodes and the intended configuration settings that will be applied after deployment. Optionally, you can include one or more tags in the query to filter the list.
Query parameters:
| tags | string | (Optional) One or more key-value pairs (e.g., {region=us,pop=ex01}) by which to filter the list of nodes returned in the response. |
Copy CodeReturns the intended configuration for all nodes
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/deploy
Copy CodeReturns the intended configuration for the specified tags
curl -X GET -H "x-nsone-key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/deploy?tags={key=value}
Example Request:
curl -X GET -H "x-nsone-key: $NSONE_API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/deploy?tags={region=us,pop=ex01}
Example Response:
{
"deployments": [
{
"node_id": "1z5a7blcBEtJEnc0GHD9B86LQj4",
"tags": {
"region": "us",
"pop": "ex01"
},
"config": {}
},
{
"node_id": "1z5a9u68taJtME1ocdmdO8peKHI",
"tags": {
"region": "us",
"pop": "ex01"
},
"config": {}
},
{
"node_id": "1z5aG7w7oClkjCjwJa6OM31YLi3",
"tags": {
"region": "us",
"pop": "ex01"
},
"config": {
"dns": {
"core_host": [
"65be78f9-630b-4a72-8156-f97c9df4dfa1.sync.platform.nsone.net"
],
"service_def_id": 3234,
"version": "3.4.0-build155"
}
}
}
]
}
GET /v1/fleet/node
GET View running configuration of all deployed nodes
Returns a list of all edge nodes upon which a service component has been deployed. The list includes the status of the node, its associated tags, and the node ID.
Query parameters:
| tags | array | (Optional) One or more key-value pairs by which to filter the list of nodes in the response. |
Copy CodeReturns details for all deployed edge nodes
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node
Copy CodeReturns details for all deployed edge nodes containing the specified tag(s)
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node?tags={key=value}
Example Response:
{
"nodes": [
{
"id": "1z5aG7w7oClkjCjwJa6OM31YLi3",
"tags": {
"hostname": "host01"
}
}
{
"id": "1z5a7blcBEtJEnc0GHD9B86LQj4",
"tags": {
"hostname": "host01",
"pop": "nyc01",
"region": "region_code",
"role": “some_cool_role"
}
}
]
}
GET /v1/fleet/node/{nodeID}
GET View running configuration details for a single node
Returns details about the specified edge node, including the node ID, any configured tags, and the status of the node. Possible statuses include:
PENDING which indicates the deployment process did not succeed and no components are running. For example, this could indicate that a firewall may have blocked the deployment. If this status appears for longer than 10 minutes, contact customer support.
REGISTERED which indicates the node is connected and all components deployed to this node are running properly.
UNHEALTHY which indicates the components running on this node are experiencing issues. Contact NS1 customer support.
UNKNOWN which indicates that NS1 is having trouble connecting with the node. Contact NS1 customer support.
Path parameters:
| nodeID | string | (Required) Unique identifier of the node |
Copy CodeReturns the details for the specified node (by node ID)
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/{nodeID}
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/1z5aG7w7oClkjCjwJa6OM31YLi3
Example Response:
{
"id": "1z5aG7w7oClkjCjwJa6OM31YLi3",
"tags": {
"hostname": "my.vm"
},
"status": "REGISTERED"
}
GET /v1/fleet/node/{nodeID}/deploy
GET View the intended configuration for a node
Returns the intended configuration details for the specified node.
Path parameters:
| nodeID | string | (Required) Unique identifier of the node |
Copy CodeReturns the details for the specified node (by nodeID)
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/{nodeID}/deploy
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/1z5aG7w7oClkjCjwJa6OM31YLi3/deploy
Example Response:
{
"node_id": "1z5aG7w7oClkjCjwJa6OM31YLi3",
"tags": {
"host": "1.hostname.example",
"pop": "lga09"
},
"config": {
"dns": {
"core_host": [
"65be78f9-630b-4a72-8156-f97c9df4dfa1.sync.platform.nsone.net"
],
"service_def_id": 3234,
"version": "3.4.0-build155"
}
}
}
PUT /v1/fleet/node/{nodeID}/deploy
PUT Deploy a single node
Deploys the intended configuration to the specified node so that it becomes the actual (or running) configuration.
Path parameters:
| nodeID | string | (Required) Unique identifier of the node |
Copy CodeDeploys the intended configuration on the specified node
curl -X PUT -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev /v1/fleet/node/{nodeID}/deploy
Example Request:
curl -X PUT -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev /v1/fleet/node/1z5aG7w7oClkjCjwJa6OM31YLi3/deploy
Example Response:
{
"node_id": "1z5aG7w7oClkjCjwJa6OM31YLi3",
"tags": {
"host": "1.hostname.example",
"pop": "lga09"
},
"config": {
"dns": {
"core_host": [
"65be78f9-630b-4a72-8156-f97c9df4dfa1.sync.platform.nsone.net"
],
"service_def_id": 3234,
"version": "3.4.0-build155"
}
}
}
PUT /v1/fleet/node/deploy?tags={key=value}
PUT Deploy multiple nodes
Deploys the intended configurations to all nodes containing the specified tag.
Query parameters:
| tags | array | (Required) One or more key-value pairs (e.g., {pop=ex01}) associated with the node(s). Services are deployed to nodes containing the specified tag(s). |
Copy CodeDeploys all nodes containing the specified tag(s)
curl -X PUT -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/deploy?tags={key=value}
Example Response:
{
"node_id": "1z5aG7w7oClkjCjwJa6OM31YLi3",
"tags": {
"host": "1.hostname.example",
"pop": "lga09"
},
"config": {
"dns": {
"core_host": [
"65be78f9-630b-4a72-8156-f97c9df4dfa1.sync.platform.nsone.net"
],
"service_def_id": 3234,
"version": "3.4.0-build155"
}
}
}
POST /v1/fleet/node/{nodeID}
POST Update node details
Creates or replaces tags associated with the specified node.
Path parameters:
| nodeID | string | (Required) Unique identifier of the node |
Request body parameters:
| tags | array | (Optional) One or more key-value pairs (e.g., {“region=us,pop=ex01”}) to apply to the specified node. |
Copy CodeUpdates the tags associated with the specified node
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/{nodeID} { "tags": {“key=value,key=value”}, }
Example Request:
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/{nodeID} {
"tags": {“region=us,pop=ex01”},
}
DELETE /v1/fleet/node/{nodeID}
DELETE Delete a node
Removes the specified edge node from your Cloud-Managed DDI configuration. You will not be able to deploy services to this node after deletion.
Path parameters:
| nodeID | string | (Required) Unique identifier of the node |
Copy CodeRemoves the specified node from your configuration
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/{nodeID}
Example Request:
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/fleet/node/1z5aG7w7oClkjCjwJa6OM31YLi3
Service management
System administrators with Cloud-Managed DDI deployments can use the service management endpoints to manage their services and service components. Refer to the NS1 Help Center for more information about these terms.
GET /v1/service
GETView all available services
Returns a list of all available services associated with your configuration.
Copy CodeLists all services in your configuration
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/service
Example Response:
{
"services": [
{
"name": "123",
"type": "dns"
},
{
"name": "456",
"type": "dns"
},
{
"name": "789",
"type": "dhcp"
}
]
}
GET /v1/service/{service_name}
GETView service details
Returns all service components and configuration details associated with the specified service (by service name).
Path parameters:
| service_name | string | (Required) Name of the service |
Copy CodeReturns details for the specified service
curl -X GET -H "X-NSONE-Key: $API_KEY" https://https://api.prod.svc.ns1.dev/v1/service/{service_name}
Example Response:
{
"type": "dns",
"name": "dns.test",
"properties": {
"core_host": [
"c6beb85c-8ad4-4783-b37d-d357c910fad7.sync.platform.nsone.net"
]
},
"components": [
{
"name": "dns",
"selector": "",
"version": "5.0.1",
"properties": {
"service_def_id": 542
},
"config": {}
}
]
}
POST /v1/service/{service_name}
POSTChange the name of the service
By default, the service name is set to a numerical value. You can change the name of the service to something more distinguishable based on your needs or preferences.
Path parameters:
| service_name | string | (Required) Existing name of the service |
Request body parameters:
| name | string | (Required) New name of the service |
Copy CodeUpdates the name of the service
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/service/{service_name} {"name": "dns01", }
GET /v1/service/{service_name}/component/{component_name}
GETView service component details
Returns configuration details related to the specified service component within the specified service. Refer to this article for more information on services and service components.
Path parameters:
| service_name | string | (Required) Name of the service with which the component is associated (e.g., DNS, DNS-01, DHCP, etc.). Note: By default, this is typically a numeric value, but you can change the name of a service to anything you want. |
Query parameters:
| component_name | string | (Required) Name of the service component for which you are requesting details (e.g., “dns” or “dhcp”). (Note: Currently, each service type only has one associated service component by the same name. For example, the DNS service offers the “dns” component, and the DHCP service offers the “dhcp” component. In the future, services will offer multiple types of components representing a specific capability related to that service.) |
Copy CodeReturns details for a service component (within the specified service)
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/service/{service_name}/component/{component_name}
Example Request:
curl -X GET -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/service/DNS01/component/dns
Example Response:
{
"name": "dns",
"selector": "",
"version": "5.0.1",
"properties": {
"service_def_id": 542
},
"config": {}
}
POST /v1/service/{service_name}/component/{component_name}
POSTUpdate the service component
Update details for the specified service component.
Path parameters:
| service_name | string | (Required) Name of the service with which the component is associated (e.g., DNS, DNS-01, DHCP, etc.). |
Query parameters:
| component_name | string | (Required) Name of the service component for which you are requesting details (e.g., “dns” or “dhcp”). (Note: Currently, each service type only has one associated service component by the same name. For example, the DNS service offers the “dns” component, and the DHCP service offers the “dhcp” component. In the future, services will offer multiple types of components representing a specific capability related to that service.) |
Request body parameters:
| selector | string | Specifies on which nodes to update the running service component. Enter a value of * to update all nodes or specify one or more tags (kvps) to push the update only to nodes containing those tags (e.g., selector: “pop=lga08”). Additionally, you can use the selector to define logical expressions (i.e., AND, OR, and NOT) to achieve a specific outcome based on your needs. For example,
You can combine multiple expressions to make an advanced statement, for example pop=lga08:pop=lga09:&!region=US would tell the system to evaluate pop=lga08:pop=lga09. If this OR returns true, the expression !region=US is evaluated at the end. If this last one also returns true, then the entire selector has a match. |
| version | string | Version number of the service component (i.e., software module) running on the node. Set to “latest” to maintain the latest software version. |
| config | object | Includes all configuration options specific to the deployed service/component. Refer to the Service Configuration Guide for details. |
Copy CodeUpdates the specified service components
curl -X POST -H "X-NSONE-Key: $API_KEY" https://api.prod.svc.ns1.dev/v1/service/{service_name}/component/{component_name} { "selector": "", "version": "latest", "config": {} }
Example Response:
{
"name": "dns",
"selector": "",
"version": "5.0.1",
"properties": {
"service_def_id": 542
},
"config": {}
}
Enterprise DDI (on-premises) configuration
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 /v1/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": "[email protected]",
"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": "[email protected]"
}
GET /v1/ops/operators
GETView all operator users
Returns a list of all operator users in the system.
GET /v1/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": "[email protected]"
}
PUT /v1/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": "[email protected]",
"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": "[email protected]"
}
POST /v1/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": "[email protected]"
}
DELETE /v1/ops/operators/:operator-id
DELETEDelete an operator
Removes another operator from the system. An operator cannot remove themselves.
GET /v1/ops/orgs
GETView a list of organizations
Returns a list of the tenant organizations.
GET /v1/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 /v1/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 /v1/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 /v1/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 /v1/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 /v1/ops/service/defs
GETView list of service definitions
Returns a list of all services of every type.
Example Response:
[
{
"name": "string",
"type": "DHCP",
"properties": {
"nameservers": [
"string"
],
"monitoring_region_code": "string",
"subnets": [
"string"
],
"domain": "string",
"key": "string"
},
"config_tree_id": 0,
"org_ids": [
0
],
"service_group_ids": [
0
],
"id": 0
}
]
GET /v1/ops/service/defs/:servicedefID
GETView service definition details
Returns the details of a service definition.
Path Parameters:
| servicedefID | integer | (Required) Unique identifier of the service definition |
Copy CodeReturns configuration details for the specified service definition
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/ops/service/defs/:servicedefID
Example Response:
{
"name": "string",
"type": "DHCP",
"properties": {
"nameservers": [
"string"
],
"monitoring_region_code": "string",
"subnets": [
"string"
],
"domain": "string",
"key": "string"
},
"config_tree_id": 0,
"org_ids": [
0
],
"service_group_ids": [
0
],
"id": 0
}
PUT /v1/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",
"properties": {"nameservers": [ "ns1.example.com", "ns2.example.com"] },
"service_group_id": 1
}
Example Response:
{
"config_tree_id": 0,
"properties": {
"nameservers": [
"ns1.example.com",
"ns2.example.com"
]
},
"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"
}
POST /v1/ops/service/defs/:servicedefID
POSTModify a service definition
Modify a service definition's information.
Path Parameters:
| servicedefID | integer | (Required) Unique identifier for the service definition |
Request Body Parameters:
| name | string | (Required) Name of the service definition | ||||||||||||
| type | string | (Required) Type of service definition. Supported values: "DHCP", "DNS", "monitoring", "CORE", "DATA", "DIST", "CONNECT" | ||||||||||||
| properties | object | Configuration options to apply to all nodes within this service definition. Note the specific configurable properties within this object depend on the type of service definition.
If type="DNS"
type="DHCP"
type="monitoring"
| ||||||||||||
| org_ids | array or integers | List of organizations (using their IDs) with which to associate this service definition | ||||||||||||
| service_group_ids | array of integers | List of service groups (using their IDs) with which to associate this service definition |
Copy CodeEdits an existing service definition
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "name": "string", "type": "DNS", "properties": { "nameservers": ["string"] }, "config_tree_id": 0, "org_ids": [0], "service_group_ids": [0] }' https://{api.mycompany.net}/v1/ops/service/defs/:servicedefID
Example Request:
{
"name": "string",
"type": "DNS",
"properties": {
"nameservers": [
"string"
]
},
"config_tree_id": 0,
"org_ids": [
0
],
"service_group_ids": [
0
]
}
DELETE /v1/ops/service/defs/:servicedefID
DELETEDelete a service definition
Delete a service definition.
Path Parameters:
| servicedefID | integer | (Required) Unique identifier of the service definition |
Copy CodeDeletes the service definition
curl -X DELETE -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/ops/service/defs/:servicedefID
Service Groups
GET /v1/ops/service/groups
GETView a list of service groups
Returns a list of all service groups.
Example Response:
[
{
"config_tree_id": 0,
"type": "",
"service_def_ids": [
0
],
"name": "string",
"require_unique_zones": true,
"properties": {},
"id": 0
}
]
GET /v1/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 /v1/ops/service/groups
PUTCreate a service group
Creates a new service group.
Request Body Parameters:
| name | string | (Required) Name of the service group |
| type | string | Type of service group. Supported values include core, edge, or an empty string. |
| service_def_ids | array of integers | List of service definitions (by ID) with which to associate this service group. |
| require_unique_zones | boolean | Option to enforce unique zone names within this service group |
| properties | object | Any additional properties to associate with this service group |
Copy CodeCreates a new service group
curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{ "name": "network0", "type": "core", "require_unique_zones": false, "properties": {} }' https://{api.mycompany.net}/v1/ops/service/groups
Example Request:
{
"name": "network0",
"type": "core",
"require_unique_zones": false,
"properties": {}
}
Example Response:
{
"config_tree_id": 0,
"type": "",
"service_def_ids": [
0
],
"name": "string",
"require_unique_zones": true,
"properties": {},
"id": 0
}
POST /v1/ops/service/groups/:servicegroupID
POSTModify a service group
Modify a service group's name.
Path Parameters:
| servicegroupID | integer | (Required) Unique identifier for the service group |
Request Body Parameters:
| name | string | (Required) Name of the service group |
| type | string | Type of service group. Supported values include core, edge, or an empty string. |
| service_def_ids | array of integers | List of service definitions (by ID) with which to associate this service group. |
| require_unique_zones | boolean | Option to enforce unique zone names within this service group |
| properties | object | Any additional properties to associate with this service group |
Copy CodeEdits an existing service group
curl -X POST -H "X-NSONE-Key: $API_KEY" -d '{ "name": "network0", "type": "core", "require_unique_zones": false, "properties": {} }' https://{api.mycompany.net}/v1/ops/service/groups
Example Request:
{
"name": "network0",
"type": "core",
"require_unique_zones": false,
"properties": {}
}
Example Response:
{
"config_tree_id": 0,
"type": "",
"service_def_ids": [
0
],
"name": "string",
"require_unique_zones": true,
"properties": {},
"id": 0
}
POST /v1/ops/service/groups/:servicegroupid/org/:orgid
POSTAssociate an organization with a service group
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.
Path Parameters:
| servicegroupID | integer | (Required) Unique identifier of the service group |
| orgID | integer | (Required) Unique identifier of the organization |
Copy CodeAssociates an organization with a service definition
curl -X POST -H "X-NSONE-Key: $API_KEY" https://{api.mycompany.net}/v1/ops/service/groups/:servicegroupid/org/:orgid
Example Response:
{
"service_group_id": 0,
"org_id": 0,
"status": "success"
}
DELETE /v1/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 /v1/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
}
]
Service Control Center
Container configuration and health monitoring platform for NS1 DDI deployments.
GET /v1/ops/service/defs/global/config/schema
GETView JSON schema for global configuration
Returns the schema for global service configuration settings.
Copy CodeReturns JSON schema for global service configuration settings
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{{ns1-api-fqdn}}/v1/ops/service/defs/global/config/schema
Example Response:
{
"schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://configspec.ns1.com/v1/global/schema.json",
"x-ns1-node": "global",
"type": "object",
"properties": {
"healthcheck_frequency_seconds": {
"title": "Health check timeout interval",
"description": "Defines timeout in health check sent (in seconds)",
"type": "integer",
"default": 5,
"x-ns1-tag": "Operational Details"
},
"healthcheck_valid_period_seconds": {
"title": "Health check valid period (in seconds)",
"description": "Defines valid period for health check after what it stops being valid",
"type": "integer",
"default": "300",
"minimum": 1,
"x-ns1-tag": "Operational Details"
},
"failure_threshold_count": {
"title": "Failure threshold count",
"description": "Defines threshold quantity of failures for health check",
"type": "integer",
"default": "2",
"x-ns1-tag": "Operational Details"
},
"healthy_threshold_count": {
"title": "Health threshold count",
"description": "Defines threshold quantity of successful for health check in case it wasn't",
"type": "integer",
"default": "2",
"x-ns1-tag": "Operational Details"
}
}
}
}
GET /v1/ops/service/defs/:servicedefID/config/schema
GETView JSON schema for service definition configuration
Returns the schema for service definition configuration settings. Path parameters include servicedefinitionID which is the unique identifier for the service definition.
Copy CodeReturns the JSON schema for service definition configuration
curl -X GET -H "X-NSONE-Key: $API_KEY" https://{{ns1-api-fqdn}}/v1/ops/service/defs/:servicedefid/config/schema
Example Response:
{
"schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://configspec.ns1.com/v1/monitor/schema.json",
"x-ns1-node": "monitor",
"type": "object",
"properties": {
"core_host": {
"title": "Core Host",
"description": "This is an array of IP addresses or hostnames of the data node cluster.",
"type": "array",
"default": [],
"x-ns1-tag": "Data Cluster Config"
},
"enable_ops_metrics": {
"title": "Enable Operational Metrics",
"description": "Enable Operational Metrics to send back to the data node.",
"type": "boolean",
"default": false,
"x-ns1-tag": "Operational Details"
},
"healthcheck_frequency_seconds": {
"title": "Health check timeout interval",
"description": "Defines timeout in health check sent (in seconds)",
"type": "integer",
"default": 5,
"x-ns1-tag": "Operational Details"
},
"inst_id": {
"title": "Instance ID",
"description": "This identifies a specific instance of monprobed running on a given POP.",
"type": "string",
"default": "1",
"x-ns1-tag": "Identifiers"
},
"jitter_seconds": {
"title": "Jitter seconds",
"description": "This configures the probe service to add jitter to the initial scheduling of monitoring jobs by a random number of seconds within the range of 0 to jitter_seconds",
"type": "string",
"default": "0",
"x-ns1-tag": "Application Configuration"
},
"log_level": {
"title": "Log Level",
"description": "Set log level for monprobed process",
"type": "string",
"default": "info",
"x-ns1-tag": "Application Configuration"
},
"management_enable_tls": {
"title": "Management TLS",
"description": "Enable or disable management TLS encryption, to use for communicating with other cluster members. Defaults to True.",
"type": "string",
"enum": [
"default_management_tls_settings",
"manual_management_tls_settings"
],
"x-ns1-scc": false
},
"manual_management_tls_cert_bundle": {
"title": "Certificate Bundle",
"description": "The combined certificate/key PEM file to present, when communicating between cluster members.",
"type": "string",
"x-ns1-file-reference": "management.bundle.pem",
"x-ns1-scc": false,
"x-ns1-type": "string"
},
"manual_management_tls_ciphers": {
"title": "Allowed Cipher List",
"description": "The set of TLS ciphers to use, when communicating between cluster members.",
"type": "string",
"default": "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305",
"pattern": "(^([a-zA-Z0-9+!-]+)(:[a-zA-Z0-9+!-]+|$)*)",
"x-ns1-scc": false,
"x-ns1-validator": "generic"
},
"manual_management_tls_client_cert_verfiy": {
"title": "Strict Certificate Verification",
"description": "Whether or not to enforce strict certificate verfication, when communicating between cluster members.",
"type": "boolean",
"default": false,
"x-ns1-scc": false
},
"manual_management_tls_crl_file": {
"title": "CRL Certificate",
"description": "The CRL certificate to use for verifying client certificates revocation status, when communicating between cluster members.",
"type": "string",
"x-ns1-file-reference": "management.crl.pem",
"x-ns1-scc": false,
"x-ns1-type": "string"
},
"manual_management_tls_version": {
"title": "Minimum TLS Version",
"description": "The minimum TLS version to enforce, when communicating between cluster members.",
"type": "string",
"default": "TLSv1.2",
"pattern": "^TLSv1\\.(0|1|2)$",
"x-ns1-scc": false,
"x-ns1-validator": "generic"
},
"manual_transport_tls_cert_bundle": {
"title": "Certificate Bundle",
"description": "The combined certificate/key PEM file to present, when communicating between cluster members.",
"type": "string",
"x-ns1-file-reference": "transport.bundle.pem",
"x-ns1-scc": false,
"x-ns1-type": "string"
},
"manual_transport_tls_ciphers": {
"title": "Allowed Cipher List",
"description": "The set of TLS ciphers to use, when communicating between cluster members.",
"type": "string",
"default": "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305",
"pattern": "(^([a-zA-Z0-9+!-]+)(:[a-zA-Z0-9+!-]+|$)*)",
"x-ns1-scc": false,
"x-ns1-validator": "generic"
},
"manual_transport_tls_client_cert_verify": {
"title": "Strict Certificate Verification",
"description": "Whether or not to enforce strict certificate verfication, when communicating between cluster members. NOTE: You must set 'TLS certificate zone' for this to work with custom certificates",
"type": "boolean",
"default": false,
"x-ns1-scc": false
},
"manual_transport_tls_crl_file": {
"title": "CRL Certificate",
"description": "The CRL certificate to use for verifying client certificates revocation status, when communicating between cluster members.",
"type": "string",
"x-ns1-file-reference": "transport.crl.pem",
"x-ns1-scc": false,
"x-ns1-type": "string"
},
"manual_transport_tls_sni_zone": {
"title": "TLS Certificate Zone",
"description": "The zone to use for TLS verification purposes, when communicating between cluster members.",
"type": "string",
"default": "",
"x-ns1-scc": false
},
"manual_transport_tls_version": {
"title": "Minimum TLS Version",
"description": "The minimum TLS version to enforce, when communicating between cluster members.",
"type": "string",
"default": "TLSv1.2",
"pattern": "^TLSv1\\.(0|1|2)$",
"x-ns1-scc": false,
"x-ns1-validator": "generic"
},
"max_reconnect_attempts": {
"title": "Max Reconnect Attempts",
"description": "Max number of attempts to reconnect to core host when the connection either never existed or no longer exists",
"type": "integer",
"default": 5,
"x-ns1-tag": "Application Configuration"
},
"metrics_addr_base": {
"title": "Metrics base address",
"description": "Base address of unix socket that server metrics, in the form of unix:///var/run/socketdir/",
"type": "string",
"default": "unix:///var/run/ns1daemons/",
"x-ns1-tag": "Application Configuration"
},
"metrics_flush_interval": {
"title": "Metrics Flush Interval",
"description": "Interval for flushing metrics to the data node",
"type": "string",
"default": "30s",
"x-ns1-tag": "Operational Details"
},
"monitoring_region": {
"title": "Monitoring region",
"description": "The region for which this instance of monprobed is running jobs",
"type": "string",
"default": "lga",
"x-ns1-tag": "Application Configuration"
},
"num_metrics_procs": {
"title": "Number of Query Metrics Processors",
"description": "The number of processors running to collect metrics for monprobed",
"type": "integer",
"maximum": 100,
"minimum": 1,
"x-ns1-dynamic": "${ context.vcpus }",
"x-ns1-tag": "Operational Details",
"x-ns1-validator": "isBetween"
},
"pop_id": {
"title": "Location ID",
"description": "This specifies t