NextDNS

https://nextdns.github.io/
Admin
NextDNS is a DNS service platform offering an API for managing profiles, analytics, logs, and DNS...
Tokens:12,245
Snippets:89
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### GET /profiles/:profile/logs/download

Source: https://nextdns.github.io/api/#authentication

Downloads the DNS logs for a specific profile.

```APIDOC
## GET /profiles/:profile/logs/download

### Description
Downloads logs for the specified profile. By default, this redirects to the public file URL.

### Method
GET

### Endpoint
https://api.nextdns.io/profiles/:profile/logs/download

### Parameters
#### Path Parameters
- **profile** (string) - Required - The profile identifier.

#### Query Parameters
- **redirect** (integer) - Optional - Set to 0 to receive a JSON response containing the file URL instead of a redirect.
```

--------------------------------

### Reasons Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the reasons analytics endpoint.

```json
{
  "data": [
    {
      "id": "blocklist:nextdns-recommended",
      "name": "NextDNS Ads & Trackers Blocklist",
      "queries": 131833
    },
    {
      "id": "native:apple",
      "name": "Native Tracking (Apple)",
      "queries": 402
    },
    {
      "id": "disguised-trackers",
      "name": "Disguised Third-Party Trackers",
      "queries": 269
    },
    ...
  ],
  ...
}
```

--------------------------------

### GET /profiles/:profile/logs/stream

Source: https://nextdns.github.io/api/#authentication

Streams new DNS logs in real-time using Server-sent events (SSE).

```APIDOC
## GET /profiles/:profile/logs/stream

### Description
Stream new logs in real-time with Server-sent events (SSE).

### Method
GET

### Endpoint
/profiles/:profile/logs/stream

### Parameters
#### Path Parameters
- **profile** (string) - Required - The profile identifier.

#### Query Parameters
- **id** (string) - Optional - The last received event ID to resume streaming from a specific point.
- **raw** (boolean) - Optional - If true, shows all DNS queries including noise.
```

--------------------------------

### Devices Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the devices analytics endpoint.

```json
{
  "data": [
    {
      "id": "8TD1G",
      "name": "Romain’s iPhone",
      "model": "iPhone 12 Pro Max",
      "queries": 489885
    },
    {
      "id": "E24AR",
      "name": "MBP",
      "model": "Macbook Pro",
      "localIp": "192.168.0.11",
      "queries": 215663
    },
    {
      "id": "__UNIDENTIFIED__",
      "queries": 74242
    },
    ...
  ],
  ...
}
```

--------------------------------

### IP Versions Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the IP versions analytics endpoint.

```json
{
  "data": [
    {
      "version": 6,
      "queries": 784154
    },
    {
      "version": 4,
      "queries": 174308
    },
    ...
  ],
  ...
}
```

--------------------------------

### Pagination Metadata

Source: https://nextdns.github.io/api

Example of pagination metadata in an API response, showing the cursor for fetching the next page of results.

```json
{
  "data": [...],
  "meta": {
    "pagination": {
      "cursor": "j2k3zl3b4v"
     }
   }
}

// get the next page with /endpoint?...&cursor=j2k3zl3b4v

```

--------------------------------

### Domains Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the domains analytics endpoint.

```json
{
  "data": [
    {
      "domain": "app-measurement.com",
      "queries": 29801
    },
    {
      "domain": "gateway.icloud.com",
      "root": "icloud.com",
      "queries": 18468
    },
    {
      "domain": "app.smartmailcloud.com",
      "root": "smartmailcloud.com",
      "queries": 16414
    },
    ...
  ],
  ...
}
```

--------------------------------

### Status Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the status analytics endpoint.

```json
{
  "data": [
    {
      "status": "default",
      "queries": 819491
    },
    {
      "status": "blocked",
      "queries": 132513
    },
    {
      "status": "allowed",
      "queries": 6923
    },
    ...
  ],
  ...
}
```

--------------------------------

### IPs Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the IPs analytics endpoint.

```json
{
  "data": [
    {
      "ip": "91.171.12.34",
      "network": {
        "cellular": false,
        "vpn": false,
        "isp": "Free",
        "asn": 12322
      },
      "geo": {
        "latitude": 48.8998,
        "longitude": 2.703,
        "countryCode": "FR",
        "country": "France",
        "city": "Gagny"
      },
      "queries": 136935
    },
    {
      "ip": "2a01:e0a:2cd:1234:312a:4c24:215d:185",
      "network": {
        "cellular": false,
        "vpn": false,
        "isp": "Free",
        "asn": 12322
      },
      "geo": {
        "latitude": 48.5136,
        "longitude": -1.9042,
        "countryCode": "FR",
        "country": "France",
        "city": "Miniac-Morvan"
      },
      "queries": 40410
    },
    ...
  ],
  ...
}
```

--------------------------------

### Paginated Response Meta

Source: https://nextdns.github.io/api/#authentication

Example of the 'meta' section in a paginated API response, including pagination details and a cursor for fetching the next page.

```json
{
  "data": [...],
  "meta": {
    "pagination": {
      "cursor": "j2k3zl3b4v"
     }
   }
}
```

--------------------------------

### Protocols Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the protocols analytics endpoint.

```json
{
  "data": [
    {
      "protocol": "DNS-over-HTTPS",
      "queries": 958757
    },
    {
      "protocol": "DNS-over-TLS",
      "queries": 39582
    },
    {
      "protocol": "UDP",
      "queries": 2334
    },
    ...
  ],
  ...
}
```

--------------------------------

### GET /profiles/:profile/logs

Source: https://nextdns.github.io/api/#authentication

Retrieves detailed query logs for a specific profile with filtering capabilities.

```APIDOC
## GET /profiles/:profile/logs

### Description
Fetches a list of query logs for the profile, supporting various filters and pagination.

### Method
GET

### Endpoint
/profiles/:profile/logs

### Parameters
#### Path Parameters
- **profile** (string) - Required - The unique identifier of the profile.

#### Query Parameters
- **from** (Date) - Optional - Filter logs from this date.
- **to** (Date) - Optional - Filter logs to this date.
- **sort** (asc | desc) - Optional - Sort order.
- **limit** (Integer) - Optional - Number of results (10-1000).
- **cursor** (String) - Optional - Pagination cursor.
- **device** (String) - Optional - Filter by device ID.
- **status** (default | error | blocked | allowed) - Optional - Filter by query status.
- **search** (String) - Optional - Search query string.
```

--------------------------------

### GET /profiles/:profile/analytics/encryption

Source: https://nextdns.github.io/api/#authentication

Retrieves the encryption status of queries for a specific profile.

```APIDOC
## GET /profiles/:profile/analytics/encryption

### Description
Returns the distribution of encrypted vs unencrypted queries for the specified profile.

### Method
GET

### Endpoint
/profiles/:profile/analytics/encryption

### Parameters
#### Path Parameters
- **profile** (string) - Required - The unique identifier of the profile.
```

--------------------------------

### DNSSEC Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the DNSSEC analytics endpoint.

```json
{
  "data": [
    {
      "validated": false,
      "queries": 817664
    },
    {
      "validated": true,
      "queries": 8199
    },
    ...
  ],
  ...
}
```

--------------------------------

### Query Types Analytics Response

Source: https://nextdns.github.io/api/#authentication

Example JSON response for the query types analytics endpoint.

```json
{
  "data": [
    {
      "type": 28,
      "name": "AAAA",
      "queries": 356230
    },
    {
      "type": 1,
      "name": "A",
      "queries": 341812
    },
    {
      "type": 65,
      "name": "HTTPS",
      "queries": 260478
    },
    ...
  ],
  ...
}
```

--------------------------------

### Manage Profile

Source: https://nextdns.github.io/api/#authentication

Allows retrieval (GET), update (PATCH), and deletion (DELETE) of a specific profile using its unique ID.

```APIDOC
## Manage Profile

You can then `GET`, `PATCH` and `DELETE` a profile at: `https://api.nextdns.io/profiles/:profile` (`:profile` in our example should be `abc123`).
```

--------------------------------

### GET /profiles/:profile/analytics/destinations

Source: https://nextdns.github.io/api/#authentication

Retrieves analytics data grouped by destination types such as countries or GAFAM companies.

```APIDOC
## GET /profiles/:profile/analytics/destinations

### Description
Returns analytics data grouped by specific destination types.

### Method
GET

### Endpoint
/profiles/:profile/analytics/destinations

### Parameters
#### Path Parameters
- **profile** (string) - Required - The unique identifier of the profile.

#### Query Parameters
- **type** (string) - Required - The grouping type (e.g., 'countries', 'gafam').
```

--------------------------------

### Get Time Zone Information

Source: https://nextdns.github.io/api

Retrieve the user's current time zone settings using JavaScript's `Intl.DateTimeFormat` object. This is useful for ensuring consistent date and time handling in API requests.

```javascript
Intl.DateTimeFormat().resolvedOptions().timeZone
> "Europe/Paris"
```

--------------------------------

### Get Time Zone Information

Source: https://nextdns.github.io/api/#authentication

Retrieve the user's time zone using JavaScript's `Intl.DateTimeFormat` object. The API requires time zone names from the Time Zone Database.

```javascript
Intl.DateTimeFormat().resolvedOptions().timeZone
> "Europe/Paris"

```

--------------------------------

### Create Profile

Source: https://nextdns.github.io/api

Creates a new profile by sending a Profile JSON object to the `/profiles` endpoint.

```APIDOC
## Create Profile

To create a new profile, `POST` at `https://api.nextdns.io/profiles` the above JSON. The API will return:

```json
{
  "data": {
    "id": "abc123" // the id of the newly created profile
  }
}
```
```

--------------------------------

### Retrieve All DNS Queries (Raw Logs)

Source: https://nextdns.github.io/api/#authentication

Use the `raw=1` query parameter to display all DNS queries, including those considered noise by default. This provides a comprehensive view of network access.

```json
{
  "data": [
    {
      "timestamp": "2021-03-18T03:00:10.338Z",
      "domain": "21-courier.push.apple.com",
      "root": "apple.com",
      "tracker": "apple",
      "encrypted": true,
      "protocol": "DNS-over-HTTPS",
      "clientIp": "2a01:e0a:2cd:87a0:1b23:2832:57cd:aa1d",
      "client": "apple-profile",
      "device": {
        "id": "8TD1G",
        "name": "Romain’s iPhone",
        "model": "iPhone 12 Pro Max"
      },
      "status": "default",
      "reasons": []
    },
    {
      "timestamp": "2021-03-18T02:56:14.182Z",
      "domain": "sb.scorecardresearch.com",
      "root": "scorecardresearch.com",
      "tracker": "scorecard_research_beacon",
      "encrypted": false,
      "protocol": "UDP",
      "clientIp": "91.172.51.28",
      "status": "blocked",
      "reasons": [
        {
          "id": "blocklist:nextdns-recommended",
          "name": "NextDNS Ads & Trackers Blocklist"
        },
        {
          "id": "blocklist:oisd",
          "name": "oisd"
        }
      ]
    },
    ...
  ],
  ...
}
```

--------------------------------

### Create Profile

Source: https://nextdns.github.io/api/#authentication

Creates a new profile by sending a POST request to `/profiles` with the profile JSON object in the request body. Returns the ID of the newly created profile.

```APIDOC
## Create Profile

To create a new profile, `POST` at `https://api.nextdns.io/profiles` the above JSON. The API will return:

```json
{
  "data": {
    "id": "abc123" // the id of the newly created profile
  }
}

```
```

--------------------------------

### Stream New Logs in Real-Time

Source: https://nextdns.github.io/api/#authentication

Use the `/logs/stream` endpoint to receive new DNS query logs as Server-sent events (SSE). This endpoint supports most query parameters from the `/logs` endpoint, excluding pagination and sorting parameters.

```text
id: 64v32d9r6rwkcctg6cu38e9g60
data: {"timestamp":"2021-03-16T04:40:30.344Z","domain":"g.whatsapp.net","root":"whatsapp.net","encrypted":true,"protocol":"DNS-over-HTTPS","clientIp":"2a01:e0a:2cd:87a0:5540:d573:57cd:aa1d","client":"apple-profile","device":{"id":"8TD1G","name":"Romainâ€™s iPhone","model":"iPhone 12 Pro Max"},"status":"default","reasons":[]}


```

--------------------------------

### Create Profile Response

Source: https://nextdns.github.io/api/#authentication

API response after successfully creating a new profile, containing the ID of the newly created profile.

```json
{
  "data": {
    "id": "abc123"
  }
}
```

--------------------------------

### Authentication

Source: https://nextdns.github.io/api/#authentication

All API requests must include your API key in the `X-Api-Key` header.

```APIDOC
## Authentication

Pass your API key via the `X-Api-Key` header for every calls:
`X-Api-Key: a8f4e42e896ff37f181e3e8a42a9737e1423d8e7`

💡 Find your API key at the bottom of your account page (https://my.nextdns.io/account).
```

--------------------------------

### Pagination

Source: https://nextdns.github.io/api/#authentication

Endpoints returning arrays are paginated using `cursor` and `limit` query parameters. Cursors are provided in the `meta` section.

```APIDOC
## Pagination

Most endpoints that return an array for the `data` key are paginated.
Cursors are strings returned in the `meta` section of the response and should be passed as query string argument `cursor` to get the next page:

```json
{
  "data": [...],
  "meta": {
    "pagination": {
      "cursor": "j2k3zl3b4v"
     }
   }
}
```

// get the next page with /endpoint?...&cursor=j2k3zl3b4v


Use the `limit` query string argument to adjust the number of results per page (e.g. `/endpoint?...&limit=50`).
`cursor` will be `null` when there is no more page.
```

--------------------------------

### Pagination

Source: https://nextdns.github.io/api

Endpoints returning arrays are paginated using `cursor` and `limit` query parameters.

```APIDOC
## Pagination

Most endpoints that return an array for the `data` key are paginated.
Cursors are strings returned in the `meta` section of the response and should be passed as query string argument `cursor` to get the next page:

```json
{
  "data": [...],
  "meta": {
    "pagination": {
      "cursor": "j2k3zl3b4v"
     }
   }
}

// get the next page with /endpoint?...&cursor=j2k3zl3b4v
```

Use the `limit` query string argument to adjust the number of results per page (e.g. `/endpoint?...&limit=50`).
`cursor` will be `null` when there is no more page.
```

--------------------------------

### Logs

Source: https://nextdns.github.io/api

Retrieves logs for a NextDNS profile with various filtering options.

```APIDOC
## GET /profiles/:profile/logs

### Description
Fetches logs for a specified NextDNS profile, allowing filtering by date, status, device, and search terms.

### Method
GET

### Endpoint
/profiles/:profile/logs

### Query Parameters
- **from** (string) - Optional - Filter logs with dates greater than or equal to this value.
- **to** (string) - Optional - Filter logs with dates strictly less than this value.
- **sort** (string) - Optional - Order of logs. Values: `asc` (oldest first), `desc` (newest first). Default: `desc`.
- **limit** (integer) - Optional - Maximum number of results. Default: 100. Range: 10 to 1000.
- **cursor** (string) - Optional - Token for paginating to the next set of results.
- **device** (string) - Optional - Filter logs for a specific device. Use `__UNIDENTIFIED__` for unidentified devices.
- **status** (string) - Optional - Filter by log status. Values: `default`, `error`, `blocked`, `allowed`.
- **search** (string) - Optional - Filter logs matching the search query (e.g., a domain name).

### Response
#### Success Response (200)
- **data** (array) - An array of log objects.
- **meta.pagination.cursor** (string) - Cursor for the next page of results.

### Response Example
```json
{
  "data": [
    {
      "id": "log123",
      "timestamp": "2023-10-27T10:00:00Z",
      "client_ip": "192.168.1.1",
      "client_type": "router",
      "device": "MyRouter",
      "protocol": "UDP",
      "domain": "example.com",
      "type": "A",
      "status": "blocked",
      "resolver_ip": "10.0.0.1"
    },
    ...
  ],
  "meta": {
    "pagination": {
      "cursor": "nextCursorToken"
    }
  }
}
```
```

--------------------------------

### Profile Settings Endpoints

Source: https://nextdns.github.io/api

Endpoints for managing nested objects and arrays within a profile, such as performance settings and denylist.

```APIDOC
## GET / PATCH /profiles/:profile/settings/performance

### Description
Retrieves or updates the performance settings for a given profile.

### Method
GET, PATCH

### Endpoint
`https://api.nextdns.io/profiles/:profile/settings/performance`

## POST /profiles/:profile/denylist

### Description
Adds a domain to the denylist for a given profile.

### Method
POST

### Endpoint
`https://api.nextdns.io/profiles/:profile/denylist`

## GET / PATCH /profiles/:profile/privacy

### Description
Retrieves or updates privacy settings for a given profile.

### Method
GET, PATCH

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy`

## GET / PUT /profiles/:profile/privacy/blocklists

### Description
Retrieves or updates blocklists for a given profile. Individual child items support PATCH and DELETE.

### Method
GET, PUT

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy/blocklists`
```

--------------------------------

### Profile Object Structure

Source: https://nextdns.github.io/api/#authentication

Represents the structure of a single profile, including security, privacy, parental control, denylist, allowlist, and settings.

```APIDOC
## Profile

A entire profile can be represented with the following JSON:

```json
{
  "name": "My profile",
  "security": {
    "threatIntelligenceFeeds": true,
    "aiThreatDetection": true,
    "googleSafeBrowsing": true,
    "cryptojacking": true,
    "dnsRebinding": true,
    "idnHomographs": true,
    "typosquatting": true,
    "dga": true,
    "nrd": true,
    "ddns": true,
    "parking": true,
    "csam": true,
    "tlds": [
      {
        "id": "ru"
      },
      {
        "id": "cn"
      },
      {
        "id": "cf"
      },
      {
        "id": "accountants"
      }
    ]
  },
  "privacy": {
    "blocklists": [
      {
        "id": "nextdns-recommended"
      },
      {
        "id": "oisd"
      }
    ],
    "natives": [
      {
        "id": "huawei"
      },
      {
        "id": "samsung"
      }
    ],
    "disguisedTrackers": true,
    "allowAffiliate": true
  },
  "parentalControl": {
    "services": [
      {
        "id": "tiktok",
        "active": true
      },
      {
        "id": "facebook",
        "active": false
      }
    ],
    "categories": [
      {
        "id": "porn",
        "active": true
      },
      {
        "id": "social-networks",
        "active": false
      }
    ],
    "safeSearch": true,
    "youtubeRestrictedMode": true,
    "blockBypass": false
  },
  "denylist": [
    {
      "id": "badwebsite.com",
      "active": true
    },
    {
      "id": "pornhub.com",
      "active": false
    }
  ],
  "allowlist": [
    {
      "id": "goodwebsite.com",
      "active": true
    },
    {
      "id": "nytimes.com",
      "active": false
    }
  ],
  "settings": {
    "logs": {
      "enabled": true,
      "drop": {
        "ip": false,
        "domain": false
      },
      "retention": 7776000,
      "location": "eu"
    },
    "blockPage": {
      "enabled": true
    },
    "performance": {
      "ecs": true,
      "cacheBoost": false,
      "cnameFlattening": true
    },
    "web3": true
  }
}

```
```

--------------------------------

### Profile Object Structure

Source: https://nextdns.github.io/api

Represents the structure of a single profile, including security, privacy, parental controls, denylist, allowlist, and settings.

```APIDOC
## Profile

A entire profile can be represented with the following JSON:

```json
{
  "name": "My profile",
  "security": {
    "threatIntelligenceFeeds": true,
    "aiThreatDetection": true,
    "googleSafeBrowsing": true,
    "cryptojacking": true,
    "dnsRebinding": true,
    "idnHomographs": true,
    "typosquatting": true,
    "dga": true,
    "nrd": true,
    "ddns": true,
    "parking": true,
    "csam": true,
    "tlds": [
      {
        "id": "ru"
      },
      {
        "id": "cn"
      },
      {
        "id": "cf"
      },
      {
        "id": "accountants"
      }
    ]
  },
  "privacy": {
    "blocklists": [
      {
        "id": "nextdns-recommended"
      },
      {
        "id": "oisd"
      }
    ],
    "natives": [
      {
        "id": "huawei"
      },
      {
        "id": "samsung"
      }
    ],
    "disguisedTrackers": true,
    "allowAffiliate": true
  },
  "parentalControl": {
    "services": [
      {
        "id": "tiktok",
        "active": true
      },
      {
        "id": "facebook",
        "active": false
      }
    ],
    "categories": [
      {
        "id": "porn",
        "active": true
      },
      {
        "id": "social-networks",
        "active": false
      }
    ],
    "safeSearch": true,
    "youtubeRestrictedMode": true,
    "blockBypass": false
  },
  "denylist": [
    {
      "id": "badwebsite.com",
      "active": true
    },
    {
      "id": "pornhub.com",
      "active": false
    }
  ],
  "allowlist": [
    {
      "id": "goodwebsite.com",
      "active": true
    },
    {
      "id": "nytimes.com",
      "active": false
    }
  ],
  "settings": {
    "logs": {
      "enabled": true,
      "drop": {
        "ip": false,
        "domain": false
      },
      "retention": 7776000,
      "location": "eu"
    },
    "blockPage": {
      "enabled": true
    },
    "performance": {
      "ecs": true,
      "cacheBoost": false,
      "cnameFlattening": true
    },
    "web3": true
  }
}
```
```

--------------------------------

### Profile Settings Endpoints

Source: https://nextdns.github.io/api/#authentication

Endpoints for managing nested objects and arrays within a profile's settings.

```APIDOC
## GET /profiles/:profile/settings/performance

### Description
Retrieves the performance settings for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/settings/performance`
```

```APIDOC
## PATCH /profiles/:profile/settings/performance

### Description
Updates the performance settings for a given profile.

### Method
PATCH

### Endpoint
`https://api.nextdns.io/profiles/:profile/settings/performance`
```

```APIDOC
## POST /profiles/:profile/denylist

### Description
Adds a domain to the denylist for a given profile.

### Method
POST

### Endpoint
`https://api.nextdns.io/profiles/:profile/denylist`

### Request Body
- **domain** (string) - Required - The domain to add to the denylist.
```

```APIDOC
## GET /profiles/:profile/privacy

### Description
Retrieves privacy settings for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy`
```

```APIDOC
## PATCH /profiles/:profile/privacy

### Description
Updates privacy settings for a given profile.

### Method
PATCH

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy`
```

```APIDOC
## GET /profiles/:profile/privacy/blocklists

### Description
Retrieves the list of blocklists for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy/blocklists`
```

```APIDOC
## PUT /profiles/:profile/privacy/blocklists

### Description
Updates the list of blocklists for a given profile.

### Method
PUT

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy/blocklists`
```

```APIDOC
## POST /profiles/:profile/privacy/blocklists

### Description
Adds a blocklist to the profile.

### Method
POST

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy/blocklists`
```

```APIDOC
## PATCH /profiles/:profile/privacy/blocklists/:id

### Description
Updates a specific blocklist for a given profile.

### Method
PATCH

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy/blocklists/:id`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the blocklist to update.
```

```APIDOC
## DELETE /profiles/:profile/privacy/blocklists/:id

### Description
Deletes a specific blocklist from a given profile.

### Method
DELETE

### Endpoint
`https://api.nextdns.io/profiles/:profile/privacy/blocklists/:id`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the blocklist to delete.
```

--------------------------------

### API Response Format (Success)

Source: https://nextdns.github.io/api

Standard JSON structure for successful API responses, containing 'data' and optional 'meta' sections.

```json
{
  "data": {...}, // or [...], depending on the endpoint
  "meta": {...} // optional
}

```

--------------------------------

### Profile Object Structure

Source: https://nextdns.github.io/api

A comprehensive JSON representation of a user profile, detailing security, privacy, parental controls, and settings.

```json
{
  "name": "My profile",
  "security": {
    "threatIntelligenceFeeds": true,
    "aiThreatDetection": true,
    "googleSafeBrowsing": true,
    "cryptojacking": true,
    "dnsRebinding": true,
    "idnHomographs": true,
    "typosquatting": true,
    "dga": true,
    "nrd": true,
    "ddns": true,
    "parking": true,
    "csam": true,
    "tlds": [
      {
        "id": "ru"
      },
      {
        "id": "cn"
      },
      {
        "id": "cf"
      },
      {
        "id": "accountants"
      }
    ]
  },
  "privacy": {
    "blocklists": [
      {
        "id": "nextdns-recommended"
      },
      {
        "id": "oisd"
      }
    ],
    "natives": [
      {
        "id": "huawei"
      },
      {
        "id": "samsung"
      }
    ],
    "disguisedTrackers": true,
    "allowAffiliate": true
  },
  "parentalControl": {
    "services": [
      {
        "id": "tiktok",
        "active": true
      },
      {
        "id": "facebook",
        "active": false
      }
    ],
    "categories": [
      {
        "id": "porn",
        "active": true
      },
      {
        "id": "social-networks",
        "active": false
      }
    ],
    "safeSearch": true,
    "youtubeRestrictedMode": true,
    "blockBypass": false
  },
  "denylist": [
    {
      "id": "badwebsite.com",
      "active": true
    },
    {
      "id": "pornhub.com",
      "active": false
    }
  ],
  "allowlist": [
    {
      "id": "goodwebsite.com",
      "active": true
    },
    {
      "id": "nytimes.com",
      "active": false
    }
  ],
  "settings": {
    "logs": {
      "enabled": true,
      "drop": {
        "ip": false,
        "domain": false
      },
      "retention": 7776000,
      "location": "eu"
    },
    "blockPage": {
      "enabled": true
    },
    "performance": {
      "ecs": true,
      "cacheBoost": false,
      "cnameFlattening": true
    },
    "web3": true
  }
}

```

--------------------------------

### Resume Log Streaming

Source: https://nextdns.github.io/api/#authentication

To resume streaming from a specific point, pass the last `id` received from the stream as a query parameter to the `/logs/stream` endpoint. This prevents duplicate or missing logs when stitching recent and new data.

```json
{
  "data": [...],
  "meta": {
    ...
    "stream": {
      "id": "64v32d9r6rwkcctg6cu38e9g60"
    }
  }
}
```

--------------------------------

### Error Handling

Source: https://nextdns.github.io/api/#authentication

The API provides specific error structures for client-side errors (400 Bad Request) and user-related errors (200 OK with errors array).

```APIDOC
### Handling errors

The API will respond with a `400 Bad Request` and `{ "errors": [...] }` on client error:
  * Invalid or missing required `query` arguments.
  * Invalid body on POST, PATCH and PUT.


The API will respond with a `200 OK` and `{ "errors": [...] }` on user error:
  * Invalid domain when adding a domain to the Denylist.
  * Trying to rename a profile with the same name as another profile.
  * …

The `errors` array will contain _at least_ one `Error` object with the following format:

```json
{
  "code": "invalid",
  "detail": "\"HeLlO\" is not an integer.",
  "source": {
    "parameter": "limit" // for query string parameters, or "pointer" when the error is in the body.
  }
}
```
```

--------------------------------

### API Response Format

Source: https://nextdns.github.io/api/#authentication

Standard JSON structure for successful API responses, including a 'data' field and an optional 'meta' field.

```json
{
  "data": {...},
  "meta": {...}
}
```

--------------------------------

### Profile JSON Structure

Source: https://nextdns.github.io/api/#authentication

Complete JSON representation of a NextDNS profile, detailing security, privacy, parental control, denylist, allowlist, and settings.

```json
{
  "name": "My profile",
  "security": {
    "threatIntelligenceFeeds": true,
    "aiThreatDetection": true,
    "googleSafeBrowsing": true,
    "cryptojacking": true,
    "dnsRebinding": true,
    "idnHomographs": true,
    "typosquatting": true,
    "dga": true,
    "nrd": true,
    "ddns": true,
    "parking": true,
    "csam": true,
    "tlds": [
      {
        "id": "ru"
      },
      {
        "id": "cn"
      },
      {
        "id": "cf"
      },
      {
        "id": "accountants"
      }
    ]
  },
  "privacy": {
    "blocklists": [
      {
        "id": "nextdns-recommended"
      },
      {
        "id": "oisd"
      }
    ],
    "natives": [
      {
        "id": "huawei"
      },
      {
        "id": "samsung"
      }
    ],
    "disguisedTrackers": true,
    "allowAffiliate": true
  },
  "parentalControl": {
    "services": [
      {
        "id": "tiktok",
        "active": true
      },
      {
        "id": "facebook",
        "active": false
      }
    ],
    "categories": [
      {
        "id": "porn",
        "active": true
      },
      {
        "id": "social-networks",
        "active": false
      }
    ],
    "safeSearch": true,
    "youtubeRestrictedMode": true,
    "blockBypass": false
  },
  "denylist": [
    {
      "id": "badwebsite.com",
      "active": true
    },
    {
      "id": "pornhub.com",
      "active": false
    }
  ],
  "allowlist": [
    {
      "id": "goodwebsite.com",
      "active": true
    },
    {
      "id": "nytimes.com",
      "active": false
    }
  ],
  "settings": {
    "logs": {
      "enabled": true,
      "drop": {
        "ip": false,
        "domain": false
      },
      "retention": 7776000,
      "location": "eu"
    },
    "blockPage": {
      "enabled": true
    },
    "performance": {
      "ecs": true,
      "cacheBoost": false,
      "cnameFlattening": true
    },
    "web3": true
  }
}
```

--------------------------------

### Time Series Analytics for Query Types

Source: https://nextdns.github.io/api/#authentication

Retrieves time series data for DNS query types, showing query counts over specified intervals. Use with `interval`, `from`, `to`, `limit`, `alignment`, `timezone`, and `partials` parameters for detailed charting.

```javascript
// https://api.nextdns.io/profiles/abc123/analytics/queryTypes;series?from=-7d&interval=1d&limit=2
```

```json
{
  "data": [
    {
      "type": 28,
      "name": "AAAA",
      "queries": [
        4019,
        5801,
        2667,
        2817,
        3314,
        3128,
        3810
      ]
    },
    {
      "type": 1,
      "name": "A",
      "queries": [
        3873,
        5421,
        2691,
        2865,
        3387,
        3192,
        3864
      ]
    }
  ],
  "meta": {
    "series": {
      "times": [
        "2021-03-08T16:51:36.623Z",
        "2021-03-09T16:51:36.623Z",
        "2021-03-10T16:51:36.623Z",
        "2021-03-11T16:51:36.623Z",
        "2021-03-12T16:51:36.623Z",
        "2021-03-13T16:51:36.623Z",
        "2021-03-14T16:51:36.623Z"
      ],
      "interval": 86400
    },
    "pagination": {
      "cursor": "jS8sl16m"
    }
  }
}
```

--------------------------------

### Analytics Destinations by GAFAM Company

Source: https://nextdns.github.io/api/#authentication

Shows the distribution of DNS queries among major tech companies (Google, Apple, Facebook, Amazon, Microsoft) and other categories. Helps in identifying traffic sources related to these companies.

```json
{
  "data": [
    {
      "company": "others",
      "queries": 478732
    },
    {
      "company": "apple",
      "queries": 284832
    },
    {
      "company": "google",
      "queries": 159488
    },
    ...
  ],
  ...
}
```

--------------------------------

### Analytics Destinations by Country

Source: https://nextdns.github.io/api/#authentication

Provides a breakdown of DNS queries by country, including the top domains associated with each country. Useful for geographical traffic analysis.

```json
{
  "data": [
    {
      "code": "US",
      "domains": [
        "app.smartmailcloud.com",
        "imap.gmail.com",
        "api.coinbase.com",
        "events-service.coinbase.com",
        "ws.coinbase.com"
      ],
      "queries": 209851
    },
    {
      "code": "FR",
      "domains": [
        "inappcheck.itunes.apple.com",
        "iphone-ld.apple.com",
        "bag.itunes.apple.com",
        "itunes.apple.com",
        "www.apple.com"
      ],
      "queries": 105497
    },
    ...
  ],
  ...
}
```

--------------------------------

### DELETE /profiles/:profile/logs

Source: https://nextdns.github.io/api/#authentication

Clears all logs for a specific profile.

```APIDOC
## DELETE /profiles/:profile/logs

### Description
Deletes all logs associated with the specified profile.

### Method
DELETE

### Endpoint
https://api.nextdns.io/profiles/:profile/logs

### Parameters
#### Path Parameters
- **profile** (string) - Required - The profile identifier.
```

--------------------------------

### Response Format

Source: https://nextdns.github.io/api/#authentication

API responses with 200 or 400 status codes follow a standard JSON structure, either containing 'data' and optional 'meta' fields, or an 'errors' array.

```APIDOC
## Response format

All API responses with 200 or 400 status follow one of the following formats:

```json
{
  "data": {...}, // or [...], depending on the endpoint
  "meta": {...} // optional
}
```

```json
{
  "errors": [...]
}
```
```

--------------------------------

### Analytics Endpoints

Source: https://nextdns.github.io/api/#authentication

Endpoints for retrieving various analytics data for a given profile.

```APIDOC
## GET /profiles/:profile/analytics/*

### Description
Retrieves analytics data for a given profile. Specific data can be accessed by appending the desired analytics type (e.g., /protocols, /domains).

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/*`

### Query Parameters
- **from** (Date) - Optional - Filter out entities with older date (inclusive).
- **to** (Date) - Optional - Filter out entities with newer or equal date (exclusive).
- **limit** (Integer) - Optional - Limit the number of results returned. Default: `10`. Should be between 1 and 500.
- **cursor** (String) - Optional - Use `cursor` to get the next page.
- **device** (String) - Optional - Only get entities related to a specific device. Use `__UNIDENTIFIED__` to filter against all unidentified devices.
```

```APIDOC
## GET /profiles/:profile/analytics/status

### Description
Retrieves the status analytics for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/status`
```

```APIDOC
## GET /profiles/:profile/analytics/domains

### Description
Retrieves domain analytics for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/domains`

### Query Parameters
- **status** (string) - Optional - Filter by status (`default`, `blocked`, `allowed`).
- **root** (boolean) - Optional - If true, returns the root domain. Default `false`.
```

```APIDOC
## GET /profiles/:profile/analytics/reasons

### Description
Retrieves analytics based on blocking reasons for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/reasons`
```

```APIDOC
## GET /profiles/:profile/analytics/ips

### Description
Retrieves analytics based on IP addresses for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/ips`
```

```APIDOC
## GET /profiles/:profile/analytics/devices

### Description
Retrieves analytics based on devices for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/devices`
```

```APIDOC
## GET /profiles/:profile/analytics/protocols

### Description
Retrieves analytics based on DNS protocols for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/protocols`
```

```APIDOC
## GET /profiles/:profile/analytics/queryTypes

### Description
Retrieves analytics based on DNS query types for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/queryTypes`
```

```APIDOC
## GET /profiles/:profile/analytics/ipVersions

### Description
Retrieves analytics based on IP versions for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/ipVersions`
```

```APIDOC
## GET /profiles/:profile/analytics/dnssec

### Description
Retrieves analytics based on DNSSEC validation status for a given profile.

### Method
GET

### Endpoint
`https://api.nextdns.io/profiles/:profile/analytics/dnssec`
```

--------------------------------

### Time Series Analytics

Source: https://nextdns.github.io/api/#authentication

Endpoints for retrieving time-series data by appending ';series' to standard analytics endpoints.

```APIDOC
## GET /profiles/:profile/analytics/:metric;series

### Description
Returns time-series data for analytics metrics to facilitate chart creation.

### Method
GET

### Endpoint
/profiles/:profile/analytics/:metric;series

### Parameters
#### Query Parameters
- **interval** (Seconds | Duration) - Optional - The tumbling window size.
- **alignment** (start | end | clock) - Optional - Window alignment method.
- **timezone** (TimeZone) - Optional - Timezone for clock alignment.
- **partials** (none | start | end | all) - Optional - Handling of partial tumbling windows.
```

--------------------------------

### Analytics Destinations by GAFAM

Source: https://nextdns.github.io/api

Retrieves analytics data for destinations categorized by GAFAM companies (Google, Apple, Facebook, Amazon, Microsoft) and others.

```APIDOC
## GET /profiles/:profile/analytics/destinations?type=gafam

### Description
Provides a breakdown of query destinations categorized by major tech companies (Google, Apple, Facebook, Amazon, Microsoft) and others.

### Method
GET

### Endpoint
/profiles/:profile/analytics/destinations?type=gafam

### Query Parameters
- **type** (string) - Required - Must be set to 'gafam'.

### Response
#### Success Response (200)
- **data** (array) - An array of objects, each representing a company's analytics.
  - **company** (string) - The name of the company (e.g., 'others', 'apple', 'google').
  - **queries** (integer) - The number of queries associated with this company.

### Response Example
```json
{
  "data": [
    {
      "company": "others",
      "queries": 478732
    },
    {
      "company": "apple",
      "queries": 284832
    },
    {
      "company": "google",
      "queries": 159488
    },
    ...
  ],
  ...
}
```
```

--------------------------------

### Error Object Format

Source: https://nextdns.github.io/api/#authentication

Structure of an individual error object within the 'errors' array, detailing the error code, a descriptive message, and the source of the error.

```json
{
  "code": "invalid",
  "detail": "\"HeLlO\" is not an integer.",
  "source": {
    "parameter": "limit"
  }
}
```

--------------------------------

### Error Object Format

Source: https://nextdns.github.io/api

Structure of an individual error object within the 'errors' array, including code, detail, and source.

```json
{
  "code": "invalid",
  "detail": "\"HeLlO\" is not an integer.",
  "source": {
    "parameter": "limit" // for query string parameters, or "pointer" when the error is in the body.
  }
}

```
Tokens:
Raw