The Pulsar decision service allows interaction with Pulsar over HTTP—giving customers the same decision-making power as the DNS mechanism. When queried, the decision service via HTTP returns an ordered list of optimal answers, making it compatible with client integrations and CDN token authentication.
To generate a decision for a single-named record, issue a request to:
|name||string||(Required) Name of the DNS record you want to query. This is the fully-qualified domain name of any record configured on the NS1 platform (ex. pulsar.example.com). Note that this record does not need to be delegated to NS1 in public registrars.|
(Optional) Record type. Default value is CNAME. All possible values are CNAME, TXT, SRV.
The Pulsar decision service uses the same API key and authentication mechanism as the NS1 platform API (see https://ns1.com/api). Create an API key in the NS1 portal to use in the X-NSONE-KEY request header.
Source address for decisions
Pulsar decisions are made based on the geographic and network location information of your source IP address. The Pulsar decision service selects the most appropriate source address by choosing the first specified value among the following options:
- If defined, the client address from the X-Forwarded-For request header (optional) is used.
- If no X-Forwarded-For address is defined, the client's source IP address is used.
curl -s -H "X-NSONE-Key: API_KEY" -H "X-Forwarded-For:192.0.2.1" "https://rt.ns1p.net/v1/decision?name=pulsar.example.com&type=TXT"
All responses (success and error) are returned as:
Successful responses share a common format:
resourcesarray contains an object for each resource output by Pulsar's decision process. The particular format of each resource varies by type; these are described below.
ttlis an integer value in seconds indicating how long the objects in the resources array are valid for.
Examples of resource payloads:
|CNAME AND TXT TYPES RESPONSE|
|SRV TYPE RESPONSE|
Error responses share a common format:
"message": "resource not found"
where message is a user-friendly description of the error condition. Technical reasons for failure are conveyed via HTTP status codes.
HTTP status codes
|300||Name exists but the type does not||Include the type parameter for which the name exists on the NS1 platform.|
|400||Invalid data in request||Either the URL parameter name or value is invalid.|
|401||No authorization provided||Include the proper API key header with your requests.|
|404||Either the name does not exist, NS1 is not authoritative for it, or the request was refused||Ensure the named record is configured correctly on the NS1 platform.|
|405||Unsupported HTTP method||Use only supported methods.|
|418||Request was correct and handled successfully, but resulted in a semantic error||Ensure the named record is correctly configured on NS1’s platform.|
|500||Request was correct and handled successfully, but resulted in corrupt or invalid data||This is a transient error condition. Retry the same request.|
|503||Exhausted attempts at servicing request||Retry the same request.|
For successful transactions, HTTP Cache-Control headers are set according to the record's TTL. All responses are returned set for private caches with max-age equal to the record's TTL.