REST API v1

API Reference

Complete REST API documentation for integrating Nebula DNS into your applications, automation workflows, and custom security tools.

Base URL

https://api.nebuladns.io/api/v1

All API requests should be made to this base URL. All requests must use HTTPS.

Response Format

Content-Type: application/json

All responses return JSON with consistent structure, HTTP status codes, and detailed error messages.

Authentication

The Nebula DNS API uses Bearer token authentication. Include your API token in the Authorization header of every request.

HTTP HeaderRequired on all requests
Authorization: Bearer YOUR_API_TOKEN

Generate API tokens from your dashboard under Settings › API Keys.

ENDPOINTS

API Endpoints

Organized by resource type for easy navigation.

Authentication

User authentication, token management, and session handling.

POST
/auth/login
POST
/auth/logout
POST
/auth/refresh
GET
/auth/me

Tenants

Manage tenant organizations and settings.

GET
/tenants
GET
/tenants/:id
PATCH
/tenants/:id
GET
/tenants/:id/usage

Users

User management and team member administration.

GET
/users
POST
/users
GET
/users/:id
PATCH
/users/:id
DELETE
/users/:id

Policies

DNS filtering policies and rule management.

GET
/policies
POST
/policies
GET
/policies/:id
PATCH
/policies/:id
DELETE
/policies/:id

Locations

Network locations and DNS resolver configuration.

GET
/locations
POST
/locations
GET
/locations/:id
PATCH
/locations/:id
DELETE
/locations/:id

Lists

Custom block lists and allow lists.

GET
/lists
POST
/lists
GET
/lists/:id
POST
/lists/:id/entries
DELETE
/lists/:id/entries/:entryId

Reports

Analytics, reporting, and query logs.

GET
/reports/summary
GET
/reports/queries
GET
/reports/threats
GET
/reports/categories
POST
/reports/export

Agents

Client agent management and deployment.

GET
/agents
POST
/agents
GET
/agents/:id
DELETE
/agents/:id

EXAMPLES

Example Request

A quick end-to-end example to get you started.

GET/policies

Retrieve all DNS filtering policies for your tenant.

curl
curl -X GET \
  https://api.nebuladns.io/api/v1/policies \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
200 OKJSON response

Policy array with metadata returned as JSON.

application/json
{
  "success": true,
  "data": [
    {
      "id": "pol_abc123",
      "name": "Default Policy",
      "enabled": true,
      "categories_blocked": [
        "malware",
        "phishing"
      ],
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Rate Limits

API rate limits are applied per API token based on your subscription plan:

F
Free— 100 requests/hour
P
Pro— 1,000 requests/hour
E
Enterprise— 10,000 requests/hour

Rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset) are included in all responses. Contact sales for custom limits.

Additional Resources

START BUILDING

Ready to Start Building?

Generate your first API token and start integrating Nebula DNS into your applications and automation workflows today.

Generate API TokenTry in Swagger