API

Verify a target

Prove that a host is yours to unlock 30s/60s check intervals, HTTP GET paths, custom ports, TCP connect, and ICMP ping.

On this page

List, re-verify or delete targets
Opt a domain or IP out of probing

Ask for a challenge
POST/v1/targets/verify
Request body
```
{ "hostname": "example.com", "method": "dns_txt" }
```
method is dns_txt or http_well_known (http). The response contains challenge_id, txt_record and txt_value, http_path, and expires_at (valid for 24 hours).
Publish the proof
For dns_txt, publish a DNS TXT record at txt_record with value txt_value. For HTTP, serve token as plain text at http_path.
DNS record
```
_hopbits-challenge.example.com.  TXT  "hopbits-verify=<token>"
```
Confirm
POST challenge_id to /v1/targets/verify. Hopbits checks the proof and records the verified domain and its proven IP addresses.
Request body
```
{ "challenge_id": "<challenge id>" }
```

List, re-verify or delete targets

GET/v1/targets

Lists your verified targets (id, hostname, proven IP addresses, verification method, and expiry timestamps).

POST/v1/targets/{id}/verify

Re-verifies an existing target ({id} accepts the target UUID id, normalized hostname, or challenge_id). Answers 200 if the live DNS TXT or .well-known proof matches, or 201 with a fresh challenge if re-publication is needed.

DELETE/v1/targets/{id}

Removes a verified target owned by your account ({id} accepts the target UUID id or normalized hostname). Answers 204 (404 if not owned).

Opt a domain or IP out of probing

Site and network owners can request removal without an account by emailing [email protected], or opt out immediately through the API with a free Hopbits account and Bearer API key:

POST/v1/optout

Issues a 24-hour DNS TXT or HTTP .well-known opt-out challenge for a domain, IP literal, or CIDR prefix (201 Created).

POST /v1/optout request

{
  "entry": "example.com",
  "domain": "example.com",
  "method": "dns_txt",
  "consented_to_list": false
}

201 Created response

{
  "challenge_id": "opt_8c4e12a9f0014d11",
  "entry": "example.com",
  "domain": "example.com",
  "method": "dns_txt",
  "token": "9d7a3f...",
  "txt_record": "_hopbits-optout.example.com",
  "txt_value": "hopbits-optout=9d7a3f...",
  "http_path": "/.well-known/hopbits-optout.txt",
  "consented_to_list": false,
  "expires_at": "2026-11-15T01:00:00Z"
}

POST/v1/optout/verify

Verifies the published DNS TXT or HTTP .well-known proof for challenge_id and immediately adds entry to the global coordinator and agent deny-list (200 OK).

POST /v1/optout/verify request & 200 response

// Request
{ "challenge_id": "opt_8c4e12a9f0014d11" }

// Response
{
  "ok": true,
  "entry": "example.com",
  "source": "self_service",
  "consented_to_list": false,
  "created_at": "2026-11-14T01:05:00Z"
}