API Reference

Blackhole API Reference

REST API for managing devices, ACLs, DNS records, mesh topology, and billing programmatically. All endpoints are available at https://api.blackhole.dev/v1.

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from the dashboard under Settings → API Keys.

curl https://api.blackhole.dev/v1/devices \
  -H "Authorization: Bearer bh_live_xxxxxxxxxxxx"

API keys are scoped: read, write, or admin. Use the narrowest scope needed for each integration.

Devices

GET/v1/devices

List all devices in your mesh network.

GET /v1/devices

{
  "devices": [
    {
      "id": "dev_01abc",
      "name": "macbook-pro",
      "ip": "100.64.0.1",
      "os": "macOS 14.2",
      "online": true,
      "last_seen": "2026-04-06T08:00:00Z",
      "tags": ["tag:dev-laptop"]
    }
  ]
}

GET/v1/devices/:id

Get a single device by ID.

Parameter	Type	Required	Description
id	string	Yes	Device ID (dev_*)

DELETE/v1/devices/:id

Remove a device from the mesh. The device will be disconnected immediately.

Parameter	Type	Required	Description
id	string	Yes	Device ID

PATCH/v1/devices/:id

Update device metadata (name, tags, expiry).

Parameter	Type	Required	Description
name	string	No	Rename the device
tags	string[]	No	Replace tag assignments
key_expiry_disabled	boolean	No	Disable automatic key expiry

ACLs

GET/v1/acls

Fetch the current ACL policy document.

GET /v1/acls

{
  "acls": [...],
  "tagOwners": {...},
  "updated_at": "2026-04-06T07:00:00Z"
}

POST/v1/acls

Replace the ACL policy document. Validated server-side before applying.

Parameter	Type	Required	Description
acls	ACLRule[]	Yes	Full ACL rule set
tagOwners	object	No	Tag ownership map

DNS

GET/v1/dns/nameservers

List configured nameservers for your mesh.

POST/v1/dns/nameservers

Set custom nameservers for split-DNS or override configurations.

Parameter	Type	Required	Description
nameservers	string[]	Yes	List of DNS server IPs
search_paths	string[]	No	DNS search domains

GET/v1/dns/records

List all custom DNS records in your mesh.

POST/v1/dns/records

Create a custom DNS A record pointing to a mesh IP.

Parameter	Type	Required	Description
name	string	Yes	Hostname (e.g. db.internal)
value	string	Yes	Mesh IP address

Mesh

GET/v1/mesh/status

Get overall mesh health: connected devices, relay usage, NAT traversal stats.

GET /v1/mesh/status

{
  "total_devices": 12,
  "online_devices": 9,
  "direct_connections": 34,
  "relay_connections": 2,
  "relay_regions": ["us-east", "eu-west"]
}

GET/v1/mesh/routes

List all active subnet routes advertised by devices.

POST/v1/mesh/routes/:id/approve

Approve a subnet route advertised by a device.

Parameter	Type	Required	Description
id	string	Yes	Route ID

Billing

GET/v1/billing/subscription

Fetch current plan, billing cycle, and seat usage.

GET /v1/billing/subscription

{
  "plan": "team",
  "seats": 12,
  "seats_used": 9,
  "current_period_end": "2026-05-01T00:00:00Z",
  "amount_due": 54.00,
  "currency": "usd"
}

POST/v1/billing/portal

Generate a Stripe Customer Portal URL for self-serve plan changes and invoice downloads.