controld

# Control D DNS Management

Control D is a DNS filtering and privacy service. This skill enables full API access.

## Authentication

Store API token in environment variable or pass directly:
```bash
export CONTROLD_API_TOKEN="your-api-token"
```

Get your API token from: https://controld.com/dashboard (Account Settings > API)

**Token Types:**
- **Read** - View-only access to Profiles, Devices, and Analytics
- **Write** - View and modify data (create/modify/delete)

**Security Tip:** Restrict tokens by allowed IP addresses for automation hosts.

## API Reference

Base URL: `https://api.controld.com`
Auth: `Authorization: Bearer $CONTROLD_API_TOKEN`

### Profiles

DNS filtering profiles define blocking rules, filters, and service controls.

```bash
# List all profiles
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles" | jq '.body.profiles'

# Create profile
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Profile"}' \
  "https://api.controld.com/profiles"

# Clone existing profile
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cloned Profile","clone_profile_id":"PROFILE_ID"}' \
  "https://api.controld.com/profiles"

# Update profile
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Name"}' \
  "https://api.controld.com/profiles/PROFILE_ID"

# Delete profile
curl -s -X DELETE -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID"
```

### Profile Options

```bash
# List available profile options
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/options" | jq '.body.options'

# Update profile option (status: 1=enabled, 0=disabled)
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":1,"value":"some_value"}' \
  "https://api.controld.com/profiles/PROFILE_ID/options/OPTION_NAME"
```

### Devices

Devices are DNS endpoints that use profiles for filtering.

```bash
# List all devices
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/devices" | jq '.body.devices'

# List device types (icons)
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/devices/types" | jq '.body.types'

# Create device
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Home Router","profile_id":"PROFILE_ID","icon":"router"}' \
  "https://api.controld.com/devices"

# Update device
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Name","status":1}' \
  "https://api.controld.com/devices/DEVICE_ID"

# Delete device
curl -s -X DELETE -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/devices/DEVICE_ID"
```

**Device Icons:** `desktop-windows`, `desktop-mac`, `desktop-linux`, `mobile-ios`, `mobile-android`, `browser-chrome`, `browser-firefox`, `browser-edge`, `browser-brave`, `browser-other`, `tv-apple`, `tv-android`, `tv-firetv`, `tv-samsung`, `tv`, `router-asus`, `router-ddwrt`, `router-firewalla`, `router-freshtomato`, `router-glinet`, `router-openwrt`, `router-opnsense`, `router-pfsense`, `router-synology`, `router-ubiquiti`, `router-windows`, `router-linux`, `router`

**Device Status:** `0`=pending, `1`=active, `2`=soft-disabled, `3`=hard-disabled

### Filters

Native and external blocking filters for profiles.

```bash
# List native filters for profile
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/filters" | jq '.body.filters'

# List external filters
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/filters/external" | jq '.body.filters'

# Enable/disable filter (status: 1=enabled, 0=disabled)
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":1}' \
  "https://api.controld.com/profiles/PROFILE_ID/filters/filter/FILTER_ID"
```

### Services

Block, bypass, or redirect specific services (apps/websites).

```bash
# List service categories
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/services/categories" | jq '.body.categories'

# List services in category
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/services/categories/CATEGORY" | jq '.body.services'

# List profile services with their actions
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/services" | jq '.body.services'

# Set service action (do: 0=block, 1=bypass, 2=spoof)
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"do":0,"status":1}' \
  "https://api.controld.com/profiles/PROFILE_ID/services/SERVICE_ID"
```

### Custom Rules

Create custom blocking/bypass rules for specific domains.

```bash
# List rule folders
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/groups" | jq '.body.groups'

# Create rule folder
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Rules","do":0}' \
  "https://api.controld.com/profiles/PROFILE_ID/groups"

# Update rule folder
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"do":0,"status":1}' \
  "https://api.controld.com/profiles/PROFILE_ID/groups/FOLDER_ID"

# Delete rule folder
curl -s -X DELETE -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/groups/FOLDER_ID"

# List rules in folder
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/rules/FOLDER_ID" | jq '.body.rules'

# Create custom rule (do: 0=block, 1=bypass, 2=spoof, 3=redirect)
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostnames":["ads.example.com","tracking.example.com"],"do":0,"status":1}' \
  "https://api.controld.com/profiles/PROFILE_ID/rules"

# Delete custom rule
curl -s -X DELETE -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/rules/HOSTNAME"
```

**Rule Actions (do):** `0`=block, `1`=bypass, `2`=spoof (resolve via proxy), `3`=redirect

### Default Rule

Set default action for unmatched domains.

```bash
# Get default rule
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/profiles/PROFILE_ID/default" | jq '.body.default'

# Set default rule
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"do":1,"status":1}' \
  "https://api.controld.com/profiles/PROFILE_ID/default"
```

### Proxies

List available proxy locations for traffic redirection (spoofing).

```bash
# List all proxy locations
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/proxies" | jq '.body.proxies'
```

Use proxy PK values with the `via` parameter when setting service/rule actions to `do:2` (spoof).

### IP Access Control

Manage known/allowed IPs for devices.

```bash
# List known IPs for device
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"DEVICE_ID"}' \
  "https://api.controld.com/access" | jq '.body.ips'

# Learn new IPs
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"DEVICE_ID","ips":["1.2.3.4","5.6.7.8"]}' \
  "https://api.controld.com/access"

# Delete learned IPs
curl -s -X DELETE -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"DEVICE_ID","ips":["1.2.3.4"]}' \
  "https://api.controld.com/access"
```

### Analytics

Configure logging and storage settings.

```bash
# List available log levels (0=off, 1=basic, 2=full)
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/analytics/levels" | jq '.body.levels'

# List storage regions
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/analytics/endpoints" | jq '.body.endpoints'

# Get statistics for a device (requires Full analytics level)
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/stats?device_id=DEVICE_ID&start=2024-01-01&end=2024-01-31" | jq '.body'

# Get activity log (requires Full analytics level)
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/queries?device_id=DEVICE_ID&limit=100" | jq '.body.queries'
```

### Account & Network

```bash
# Get account info
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/users" | jq '.body'

# Get current IP info
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/ip" | jq '.body'

# List network/resolver status
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/network" | jq '.body'
```

---

## Organization Management (Business Accounts)

Organization features require a business account. These endpoints manage multi-user access, sub-organizations, and team deployments.

**Note:** Contact [[email protected]](mailto:[email protected]) from a work email to request business account access.

Organization capabilities include:
- Manage large amounts of end user devices or networks
- Quickly onboard hundreds/thousands of devices using RMM
- Grant access to team members with permission levels
- Group Profiles and Endpoints into Sub-Organizations
- Share Profiles between organizations
- Lock resolvers to specific IP addresses

### Organizations

The organization endpoints operate on the organization associated with your API token (no org_id in path).

```bash
# View organization info (your organization context)
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/organizations/organization" | jq '.body'

# Modify organization settings
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Updated Org Name&twofa_req=1" \
  "https://api.controld.com/organizations"
```

**Modify Organization Parameters (all optional):**
- `name` (string) — Organization name
- `contact_email` (string) — Primary contact email
- `twofa_req` (integer) — Require 2FA/MFA for members (0=no, 1=yes)
- `stats_endpoint` (string) — Storage region PK from `/analytics/endpoints`
- `max_users` (integer) — Max number of User Devices
- `max_routers` (integer) — Max number of Router Devices
- `address` (string) — Physical address
- `website` (string) — Website URL
- `contact_name` (string) — Contact person name
- `contact_phone` (string) — Phone number
- `parent_profile` (string) — Global Profile ID to enforce on all devices

**Note:** Modifying `max_users` and `max_routers` is a billable event.

### Members

View organization membership.

```bash
# List organization members
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/organizations/members" | jq '.body.members'
```

### Sub-Organizations

Sub-organizations compartmentalize profiles and endpoints into logical groups:
- **Departments** - Internal organizational units
- **Physical sites** - Office locations, branches
- **Customer companies** - For MSPs managing multiple clients
- **Any logical grouping** - Based on your needs

Each sub-org has its own Profiles, Endpoints, and optionally a Global Profile that applies to all its Endpoints.

```bash
# List sub-organizations
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/organizations/sub_organizations" | jq '.body.sub_organizations'

# Create sub-organization
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "name=Customer ABC&contact_email=john@example.com&twofa_req=0&stats_endpoint=ENDPOINT_PK&max_users=50&max_routers=10" \
  "https://api.controld.com/organizations/suborg"
```

**Create Sub-Organization Parameters:**

Required:
- `name` (string) — Organization name
- `contact_email` (string) — Primary contact email
- `twofa_req` (integer) — Require 2FA/MFA (0=no, 1=yes)
- `stats_endpoint` (string) — Storage region PK from `/analytics/endpoints`
- `max_users` (integer) — Max number of User Devices
- `max_routers` (integer) — Max number of Router Devices

Optional:
- `address` (string) — Physical address
- `website` (string) — Website URL
- `contact_name` (string) — Contact person name
- `contact_phone` (string) — Phone number
- `parent_profile` (string) — Global Profile ID to enforce on all devices

### Provisioning Codes

Mass deploy ctrld daemon to endpoints using RMM tools.

```bash
# List provisioning codes
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/provision" | jq '.body.codes'

# Create provisioning code
curl -s -X POST -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id":"PROFILE_ID",
    "device_type":"windows",
    "expires_after":"7d",
    "limit":100,
    "prefix":"office-"
  }' \
  "https://api.controld.com/provision"

# Invalidate provisioning code
curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"invalid"}' \
  "https://api.controld.com/provision/CODE_ID"

# Delete provisioning code
curl -s -X DELETE -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/provision/CODE_ID"
```

**Device Types:** `windows`, `mac`, `linux`

**Deployment Commands:**
```bash
# Windows (PowerShell as Admin)
(Invoke-WebRequest -Uri 'https://api.controld.com/dl/rmm' -UseBasicParsing).Content | Set-Content "$env:TEMP\ctrld_install.ps1"; Invoke-Expression "& '$env:TEMP\ctrld_install.ps1' 'CODE'"

# macOS/Linux
sh -c 'sh -c "$(curl -sSL https://api.controld.com/dl/rmm)" -s CODE'
```

---

## Billing

View billing history, subscriptions, and active products.

```bash
# Get payment history
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/billing/payments" | jq '.body'

# Get active and canceled subscriptions
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/billing/subscriptions" | jq '.body'

# Get currently activated products
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/billing/products" | jq '.body'
```

---

## Mobile Config (Apple Devices)

Generate signed Apple DNS profiles (.mobileconfig) for iOS/macOS devices.

```bash
# Generate mobile config profile for a device
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/mobileconfig/DEVICE_ID" -o config.mobileconfig

# With optional parameters
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/mobileconfig/DEVICE_ID?client_id=my-iphone&dont_sign=0" -o config.mobileconfig

# Exclude specific WiFi networks
curl -s -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
  "https://api.controld.com/mobileconfig/DEVICE_ID?exclude_wifi[]=HomeNetwork&exclude_wifi[]=OfficeWiFi" -o config.mobileconfig
```

**Path Parameter:**
- `device_id` (required) — Device/Resolver ID

**Query Parameters (all optional):**
- `exclude_wifi[]` (array) — WiFi SSIDs to exclude from using Control D
- `exclude_domain[]` (array) — Domain names to exclude from using Control D
- `dont_sign` (string) — Set to `1` to return unsigned profile
- `exclude_common` (string) — Set to `1` to exclude common captive portal hostnames from WiFi exclusions
- `client_id` (string) — Optional client name

**Note:** This endpoint returns binary data (not JSON) on success. Errors still return JSON.

---

## Helper Script

Use `scripts/controld.sh` for common operations:

```bash
# List profiles
./scripts/controld.sh profiles list

# Create profile
./scripts/controld.sh profiles create "My Profile"

# List devices
./scripts/controld.sh devices list

# Create device
./scripts/controld.sh devices create "Router" PROFILE_ID router

# Block domain
./scripts/controld.sh rules block PROFILE_ID "ads.example.com"

# Bypass domain
./scripts/controld.sh rules bypass PROFILE_ID "trusted.com"

# Enable filter
./scripts/controld.sh filters enable PROFILE_ID FILTER_ID

# Block service (e.g., facebook, tiktok)
./scripts/controld.sh services block PROFILE_ID SERVICE_ID

# List proxies
./scripts/controld.sh proxies list

# Organization management (business accounts)
./scripts/controld.sh orgs info               # View organization info
./scripts/controld.sh orgs members            # List members
./scripts/controld.sh orgs suborgs            # List sub-organizations
./scripts/controld.sh provision list

# Billing
./scripts/controld.sh billing payments        # Payment history
./scripts/controld.sh billing subscriptions   # Subscriptions
./scripts/controld.sh billing products        # Active products

# Mobile Config (Apple devices)
./scripts/controld.sh mobileconfig DEVICE_ID config.mobileconfig
```

## Common Workflows

### Set Up New Device

1. List profiles: `profiles list`
2. Create or select profile
3. Create device with profile: `devices create NAME PROFILE_ID ICON`
4. Note the resolver addresses (DoH/DoT/IPv4) from response
5. Configure device DNS to use resolvers

### Block Social Media

1. List social media services: `curl ... /services/categories/social`
2. Block each service: `services block PROFILE_ID facebook`
3. Or create custom rules for specific domains

### Enable Ad Blocking

1. List filters: `filters list PROFILE_ID`
2. Enable ad-related filters: `filters enable PROFILE_ID ads`
3. Enable malware filters: `filters enable PROFILE_ID malware`

### Redirect Traffic Through Proxy (Geo-Spoofing)

1. List proxies: `./scripts/controld.sh proxies list`
2. Set service to spoof via proxy:
   ```bash
   curl -s -X PUT -H "Authorization: Bearer $CONTROLD_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"do":2,"status":1,"via":"PROXY_PK"}' \
     "https://api.controld.com/profiles/PROFILE_ID/services/SERVICE_ID"
   ```

### Mass Deploy to Enterprise Endpoints

1. Create provisioning code: `provision create`
2. Deploy via RMM using the provided command
3. Monitor endpoint registrations in dashboard

## Rate Limiting

API rate limit: ~1200 requests per 5 minutes (4 req/sec average). Exponential backoff on 429 responses.

## Notes

- Organization endpoints require a business account
- Sub-organization members inherit parent org member permissions unless explicitly added
- Global Profile on a sub-org applies to ALL devices in that sub-org
- Analytics data is stored for 1 month (raw logs) or 1 year (stats)
- SSO supported: Okta OIDC and Microsoft EntraID OIDC

## API Documentation Sources

- **Conceptual docs:** https://docs.controld.com/docs/
- **API reference:** https://docs.controld.com/reference/get-started (JS-rendered)
- **API base URL:** https://api.controld.com

**Verified endpoints (from API reference, March 2026):**
- Core: `/profiles`, `/devices`, `/access`, `/proxies`, `/services`, `/filters`
- Organization: `/organizations/organization`, `/organizations/members`, `/organizations/sub_organizations`, `/organizations/suborg`, `/organizations` (PUT)
- Billing: `/billing/payments`, `/billing/subscriptions`, `/billing/products`
- Mobile Config: `/mobileconfig/{device_id}`
- Provisioning: `/provision`

Organization and billing endpoints require a business account.