API

The Hopbits API

A REST API over HTTPS with JSON in, JSON out, double-entry credit accounting, and an OpenAPI 3.1.0 schema.

On this page

Base URL & OpenAPI 3.1.0
Authentication
Requests
Errors
What is in the API

Base URL & OpenAPI 3.1.0

Base URL

https://api.hopbits.io/v1

GET/v1/openapi.json

Returns the complete OpenAPI 3.1.0 JSON specification for SDK generators, Postman, and API clients.

Authentication

Send an API key (hb_live_...) as a Bearer token with every authenticated request.

Request

curl https://api.hopbits.io/v1/kinds \
  -H "Authorization: Bearer $HOPBITS_KEY"

Response

{
  "kinds": [
    {
      "name": "http",
      "version": 1,
      "capability": "measure.http.v1",
      "transport": "tcp",
      "default_port": 443,
      "allowed_ports": [80, 443, 8080, 8443],
      "credits_per_probe": 1,
      "description": "HTTP/HTTPS request with DNS, TCP, TLS, and TTFB phase timings"
    },
    {
      "name": "tcp_connect",
      "version": 1,
      "capability": "measure.tcp_connect.v1",
      "transport": "tcp",
      "default_port": 443,
      "allowed_ports": [80, 443, 8080, 8443],
      "credits_per_probe": 1,
      "description": "TCP three-way handshake latency check"
    },
    {
      "name": "icmp_ping",
      "version": 1,
      "capability": "measure.icmp_ping.v1",
      "transport": "icmp",
      "credits_per_probe": 1,
      "description": "ICMP echo round-trip latency and packet loss"
    }
  ]
}

Requests

Request bodies are UTF-8 JSON and may be up to 64 KiB. Responses carry Cache-Control: no-store.

Errors

Every error returns an HTTP status code and a stable JSON error envelope:

401

{ "error": { "code": "unauthorized", "message": "authentication required" } }

Code	Meaning
`bad_request`, `invalid_request`	The request body could not be parsed or a field failed validation.
`unauthorized`	The Bearer token is missing or invalid.
`forbidden`	The key or session is not permitted to perform this action.
`not_found`	No resource exists at that identifier.
`body_too_large`	The request body exceeds 64 KiB.
`insufficient_credits`	Available credits are below the required reservation (`402`).
`unknown_type`	Unsupported measurement or check kind (`422`). Only `http`, `tcp_connect`, and `icmp_ping` exist.
`max_credits_exceeded`	Estimated cost exceeds the caller's `max_credits` guard (`422`).
`rate_limited`	Target or account rate budget reached (`429`). Wait and retry.
`no_nodes_online`	No matching online node is available right now (`503`).
`unavailable`, `internal`	Hopbits could not complete the request. Retry shortly.

What is in the API

Part	What it is for
Measurements	On-demand global probes, network-class & ASN filters, `?wait=` synchronous polling, zero-credit failure protection, and live `/v1/network` coverage.
Checks	Scheduled uptime monitors, `PATCH` editing, per-run credit settlement, outage email + HMAC webhooks, and `test-webhook`.
IP location	Speed-of-light IP geolocation, VPN/country `claim` verification, and per-VP exclusion proof.
Verify a target	Prove domain ownership via DNS TXT or HTTP `.well-known`, re-verify or delete targets, and opt domains out of probing.
Credits, usage & estimate	Dry-run cost estimator (`/v1/estimate`), live credit balances, double-entry ledger, and 30d product spend.