controld

What this skill does

# 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