{"openapi":"3.1.0","info":{"title":"NextDNS (BYOK) API","version":"0.1.0","description":"NextDNS (BYOK) lets an AI assistant read your own NextDNS data through the NextDNS API with a key you supply (NextDNS API key). Read-only: 10 tools (get_profile, list_denylist, list_allowlist, get_query_status, get_top_domains, get_block_reasons, get_devices, get_protocols, get_query_types, get_destinations). The BYOK key travels with each request, is used for that one call only and is never...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-nextdns.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-nextdns/docs"},"termsOfService":"https://connectorbay.com/byok-nextdns/terms"},"servers":[{"url":"https://byok-nextdns.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-nextdns/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_profile":{"post":{"operationId":"get_profile","summary":"Get a profile's configuration: security and privacy settings, parental control, and logging, performance and block page ","description":"Get a profile's configuration: security and privacy settings, parental control, and logging, performance and block page settings. Use for \"What security and privacy settings does my NextDNS profile abc123 use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"}},"required":["profile"],"title":"get_profileArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_denylist":{"post":{"operationId":"list_denylist","summary":"List the domains on a profile's deny list with whether each entry is active. Use for \"Which domains are blocked in my Ne","description":"List the domains on a profile's deny list with whether each entry is active. Use for \"Which domains are blocked in my NextDNS profile abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"}},"required":["profile"],"title":"list_denylistArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_allowlist":{"post":{"operationId":"list_allowlist","summary":"List the domains on a profile's allow list with whether each entry is active. Use for \"Which domains are always allowed ","description":"List the domains on a profile's allow list with whether each entry is active. Use for \"Which domains are always allowed in my NextDNS profile abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"}},"required":["profile"],"title":"list_allowlistArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_query_status":{"post":{"operationId":"get_query_status","summary":"Count DNS queries of a profile by outcome (default, blocked, allowed) in a time window. Use for \"How many DNS queries di","description":"Count DNS queries of a profile by outcome (default, blocked, allowed) in a time window. Use for \"How many DNS queries did NextDNS block for profile abc123 in the last 7 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, inclusive: ISO 8601, a Unix timestamp, a relative value such as '-7d' or '-6h', or a date such as 2026-10-01.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, exclusive, same formats as date_from (for example 'now').","title":"Date To"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many rows to return (1 to 500).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.pagination.cursor of the previous answer to get the next page.","title":"Cursor"},"device":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only count queries of this device id; '__UNIDENTIFIED__' selects all unidentified devices.","title":"Device"}},"required":["profile"],"title":"get_query_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_top_domains":{"post":{"operationId":"get_top_domains","summary":"List the most queried domains of a profile with query counts, optionally only blocked, allowed or default-resolved ones,","description":"List the most queried domains of a profile with query counts, optionally only blocked, allowed or default-resolved ones, or grouped by root domain. Use for \"Which domains were blocked most often on NextDNS profile abc123 this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, inclusive: ISO 8601, a Unix timestamp, a relative value such as '-7d' or '-6h', or a date such as 2026-10-01.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, exclusive, same formats as date_from (for example 'now').","title":"Date To"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many rows to return (1 to 500).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.pagination.cursor of the previous answer to get the next page.","title":"Cursor"},"device":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only count queries of this device id; '__UNIDENTIFIED__' selects all unidentified devices.","title":"Device"},"status":{"anyOf":[{"enum":["default","blocked","allowed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only domains with this outcome: default, blocked or allowed.","title":"Status"},"root":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to group by root domain.","title":"Root"}},"required":["profile"],"title":"get_top_domainsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_block_reasons":{"post":{"operationId":"get_block_reasons","summary":"List why queries were blocked (blocklists, native trackers and so on) with query counts. Use for \"Which blocklists block","description":"List why queries were blocked (blocklists, native trackers and so on) with query counts. Use for \"Which blocklists blocked the most queries in NextDNS profile abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, inclusive: ISO 8601, a Unix timestamp, a relative value such as '-7d' or '-6h', or a date such as 2026-10-01.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, exclusive, same formats as date_from (for example 'now').","title":"Date To"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many rows to return (1 to 500).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.pagination.cursor of the previous answer to get the next page.","title":"Cursor"},"device":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only count queries of this device id; '__UNIDENTIFIED__' selects all unidentified devices.","title":"Device"}},"required":["profile"],"title":"get_block_reasonsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_devices":{"post":{"operationId":"get_devices","summary":"List the devices that sent queries through a profile with model and query counts. Use for \"Which devices send the most D","description":"List the devices that sent queries through a profile with model and query counts. Use for \"Which devices send the most DNS queries on NextDNS profile abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, inclusive: ISO 8601, a Unix timestamp, a relative value such as '-7d' or '-6h', or a date such as 2026-10-01.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, exclusive, same formats as date_from (for example 'now').","title":"Date To"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many rows to return (1 to 500).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.pagination.cursor of the previous answer to get the next page.","title":"Cursor"},"device":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only count queries of this device id; '__UNIDENTIFIED__' selects all unidentified devices.","title":"Device"}},"required":["profile"],"title":"get_devicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_protocols":{"post":{"operationId":"get_protocols","summary":"Count queries by transport protocol (DNS-over-HTTPS, DNS-over-TLS, UDP and others). Use for \"Which DNS protocols do my d","description":"Count queries by transport protocol (DNS-over-HTTPS, DNS-over-TLS, UDP and others). Use for \"Which DNS protocols do my devices use on NextDNS profile abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, inclusive: ISO 8601, a Unix timestamp, a relative value such as '-7d' or '-6h', or a date such as 2026-10-01.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, exclusive, same formats as date_from (for example 'now').","title":"Date To"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many rows to return (1 to 500).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.pagination.cursor of the previous answer to get the next page.","title":"Cursor"},"device":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only count queries of this device id; '__UNIDENTIFIED__' selects all unidentified devices.","title":"Device"}},"required":["profile"],"title":"get_protocolsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_query_types":{"post":{"operationId":"get_query_types","summary":"Count queries by DNS record type (A, AAAA, HTTPS and so on). Use for \"What DNS query types does NextDNS profile abc123 s","description":"Count queries by DNS record type (A, AAAA, HTTPS and so on). Use for \"What DNS query types does NextDNS profile abc123 see most\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, inclusive: ISO 8601, a Unix timestamp, a relative value such as '-7d' or '-6h', or a date such as 2026-10-01.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, exclusive, same formats as date_from (for example 'now').","title":"Date To"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many rows to return (1 to 500).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.pagination.cursor of the previous answer to get the next page.","title":"Cursor"},"device":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only count queries of this device id; '__UNIDENTIFIED__' selects all unidentified devices.","title":"Device"}},"required":["profile"],"title":"get_query_typesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_destinations":{"post":{"operationId":"get_destinations","summary":"Count queries by destination: by country code (with sample domains) or by large company (apple, google and so on). Use f","description":"Count queries by destination: by country code (with sample domains) or by large company (apple, google and so on). Use for \"Which countries do my DNS queries go to on NextDNS profile abc123\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"profile":{"description":"NextDNS profile identifier (the short code in the profile's settings URL), for example 'abc123'.","maxLength":32,"title":"Profile","type":"string"},"date_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window, inclusive: ISO 8601, a Unix timestamp, a relative value such as '-7d' or '-6h', or a date such as 2026-10-01.","title":"Date From"},"date_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window, exclusive, same formats as date_from (for example 'now').","title":"Date To"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many rows to return (1 to 500).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.pagination.cursor of the previous answer to get the next page.","title":"Cursor"},"device":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only count queries of this device id; '__UNIDENTIFIED__' selects all unidentified devices.","title":"Device"},"type":{"anyOf":[{"enum":["countries","gafam"],"type":"string"},{"type":"null"}],"default":"countries","description":"Grouping: countries or gafam.","title":"Type"}},"required":["profile"],"title":"get_destinationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}