VPN · agent guide
Check a region.
One public GET, with no account or API key. Ask for one exact region ID before offering it as a choice. The answer is a short-lived service-to-node control check. It does not verify a device tunnel or guarantee a configuration can be issued.
One read-only request
Use the exact region ID from the current catalog. This example asks about Frankfurt.
curl -sS -i 'https://api.voidly.ai/v1/vpn/availability?region=eu-west-1'This prints the HTTP status and headers with the JSON body, including on 4xx responses. Programmatic clients should parse the status and headers separately from the body; a curl exit code of zero does not mean the region is available.
Omit region to list offered regions. A held region is omitted from that list; a query for its exact ID returns an unavailable row.
Read the observation.
Use the response timestamp and scope before acting. No response contains a node IP, peer count, uptime, or capacity figure.
- schema / scope
voidly-vpn-availability/v1andnode-control-healthidentify this read-only service observation.- observed_at / fresh_for_seconds
- Read the ISO observation time. Treat it as stale after the reported freshness period, currently 15 seconds. A cached response keeps its original observation time.
- status
available,degraded,unavailable, orunknownsummarizes the requested read. Unknown means the control check could not establish a result; it is not proof that the VPN is down.- regions
- Each row has an exact
id,city,country, andstatus. A general read omits held IDs. An all-held fleet returns an empty list withunavailablestatus. - HTTP limits
- The public read is budgeted at 60 requests per minute per source network (an IPv4 address or IPv6 /64). A successful response includes
X-RateLimit-Limit: 60,X-RateLimit-Remaining, andX-RateLimit-Reset; the reset value is Unix seconds.
When a request fails
A malformed query returns HTTP 400; an unknown region ID returns HTTP 404. Read the JSON error.code and fix the query or refresh the region list.
At HTTP 429, error.code is RATE_LIMIT_EXCEEDED. Wait for the Retry-After seconds, or until error.details.resetAt (Unix seconds), before another read. Other non-200 responses are not availability verdicts; do not offer a region from a failed request.
A passing control check cannot establish reachability from a user’s network, a successful WireGuard handshake, routing protection, or issuance readiness. The person using the VPN must finish setup and check their own client.