A short-lived download URL of the list artifact the calling node should load (node side).
const url = 'https://api.opdns.io/v1/nodes/self/lists/latest';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.opdns.io/v1/nodes/self/lists/latest \ --header 'Authorization: Bearer <token>'An authorised download of the current list artifact (the one
GET /v1/nodes/self/profile names in lists), so the artifact’s object storage
need not be public. url is a presigned object-storage URL that works without
other credentials for 10 minutes (until expires_at), or the artifact’s
announced URL when the cloud does not presign (expires_at null). Fetch url
without the node token. version and sha256 name the artifact, so a node can
check that it is the one it was told about before downloading; the artifact’s
signature is verified after the download as usual. Never cached
(Cache-Control: no-store); ask again for each download.
Authorizations
Section titled “Authorizations”Responses
Section titled “Responses”Where to download the artifact.
object
Absolute artifact URL; presigned when expires_at is set.
Artifact version; 0 when only configured by flag.
Hex SHA-256 of the artifact; may be empty.
When the presigned url stops working (10 minutes after the request); null when it is not presigned.
Presigned URL of the list-signing trust.json beside the artifact, valid until expires_at; fetch it without the node token. Absent when url is not presigned (trust.json is then in the same directory as url) or the cloud could not sign it (use the announced trust.json).
Example
{ "url": "https://objects.opdns.io/opdns/lists/fleet/v12.bin?X-Amz-Expires=600&X-Amz-Signature=0f3c", "version": 12, "sha256": "9f2b6c1e4d7a8b3c5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d", "expires_at": "2026-10-03T12:10:00Z", "trust_url": "https://objects.opdns.io/opdns/lists/fleet/trust.json?X-Amz-Expires=600&X-Amz-Signature=7a1d"}Headers
Section titled “Headers”Missing or unknown node token (unauthenticated) or revoked node (node_revoked).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/node_revoked", "title": "Unauthorized", "status": 401, "code": "node_revoked", "detail": "This node was removed from your account, so its token no longer works. Enrol it again to reconnect it.", "request_id": "5f2c9a0e7b1d4c38"}Not found (also for resources of another organisation).
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/not_found", "title": "Not Found", "status": 404, "code": "not_found", "detail": "We couldn't find that. It may have been deleted, or the link may be wrong.", "request_id": "5f2c9a0e7b1d4c38"}Rate limited (rate_limited). For an API token, the organisation’s plan rate is spent until RateLimit-Reset.
object
Stable machine code.
object
Seconds, repeating the Retry-After header (rate limits, offline nodes).
The plan limit a plan_limit problem hit.
object
The plan’s value of the limit.
Where to move to a larger plan.
The scope the API token lacked (insufficient_scope).
Example
{ "type": "https://opdns.io/problems/rate_limited", "title": "Too Many Requests", "status": 429, "code": "rate_limited", "detail": "Too many requests in a short time. Please wait a moment, then try again.", "request_id": "5f2c9a0e7b1d4c38", "retry_after": 6}Headers
Section titled “Headers”On every response to an API token: the organisation’s plan rate, requests per one-minute window (api_requests_per_minute).
On every response to an API token: the requests left to the organisation in the current window.
On every response to an API token: seconds until the current window ends and the count resets.
On every response to an API token: the quota policy, <limit>;w=60.