# Voidly Probes: agent quickstart

Start with public data. Reading these links does not create an account, register a node, or run a measurement. An agent should not install or start a probe without the network operator's explicit decision.

## One read-only call: public incident totals

Probe aggregates and operator listings are temporarily withheld to protect volunteers. Start with the public incident record instead:

```bash
curl --fail-with-body --max-time 30 -sS https://api.voidly.ai/data/incidents/stats
```

These totals describe incident records, not probe coverage, current accessibility, a roster of operators, or proof of accepted probe submissions. The read needs no Voidly credential and does not run a probe. Check the response metadata and incident types before citing a count. Preserve the endpoint, returned metadata and access date with the citation. A non-2xx, malformed or incomplete response is unavailable, not zero. Keep a named User-Agent in custom clients, and back off rather than polling rapidly.

## Probe publication is on hold

`/v1/probe/stats` is on hold. The checked-in Worker returns HTTP 503 with `{"available":false,"error":"probe_publication_held"}` before any origin read; an edge block may prevent that JSON from reaching the caller. Do not retry through an alternate alias or direct origin. Public incident totals are a separate dataset and must never fill missing probe metrics.

Accessibility endpoints, including `/v1/accessibility/check`, are also on hold during source review and return HTTP 503 with code `ACCESSIBILITY_REVIEW_HOLD`. The CLI `npx @voidly/cli check` command is on hold for the same reason. These responses do not establish whether a domain is accessible.

## Discover before installing

| Purpose | Public link | What it establishes |
| --- | --- | --- |
| Current served targets | [GET `/v1/probe/domains`](https://api.voidly.ai/v1/probe/domains) | The target-list response for this request. Add `?country=XX` for a country supplement. Inspect `global` and `country_domains`; a missing or empty `global` list is not proof that the client has no targets. |
| Public incident totals | [GET `/data/incidents/stats`](https://api.voidly.ai/data/incidents/stats) | Aggregate incident records; not probe counts or current accessibility. |
| Probe aggregates | `/v1/probe/stats` — on hold | Publication is temporarily withheld to protect volunteers. |
| Human setup and risks | [Probes](https://voidly.ai/probes) · [Join guide](https://voidly.ai/probes/join) | Participation, privacy, traffic, and stopping details. |
| API and client source | [API docs](https://voidly.ai/api-docs) · [OpenAPI](https://voidly.ai/openapi.json) · [Python client source](https://github.com/voidly-ai/community-probe) | Integrator reference and inspectable client code. |
| Custom client protocol | [Probe protocol](https://voidly.ai/probe-protocol.md) | Separate ingest-key registration path; do not use it as the Python client's token instructions. |

The served target list can change without a client update. The continuous Python client fetches it at startup and about daily; if the fetch fails, it uses its bundled targets. Its `--once` mode also uses bundled targets. Reading the target list sends a request to Voidly, but does not contact the listed sites.

## Install and activation are separate

The published Python package is [`voidly-probe` on PyPI](https://pypi.org/project/voidly-probe/). `python3 -m pip install voidly-probe` installs it; installation alone does not register a node or measure. On an unregistered installation, `voidly-probe` without `--consent` prints the consent disclosure and exits. `voidly-probe --status` reads the local node identity and, if present, requests its public status.

**Activation is an explicit operator action:** `voidly-probe --consent` registers through `POST /v1/community/register`, stores a private token in `~/.voidly/node.json`, and starts outbound DNS, TLS, and HTTP checks. Do not use that command as a dry run. Starting the [Docker image](https://hub.docker.com/r/emperormew2/voidly-probe) also activates measurement immediately. Before either start, review the served and bundled targets, local network rules, and [participation risks](https://voidly.ai/probes#risks). The network operator and tested services can observe the traffic; node location and measurement history can become public. The default registration location lookup contacts ipinfo.io unless `VOIDLY_COUNTRY` and optional `VOIDLY_CITY` are set before first registration.

After activation, stop the running process to stop new checks. `voidly-probe --unregister` removes only the local identity file; it does not revoke the remote token, remove a pending-results cache, or erase submitted data and downstream copies. Keep the token private.

## What counts as a measurement

The Python client signs result submissions with its community token and sends them to `POST /v1/probe/results`. The custom-client [ingest-key protocol](https://voidly.ai/probe-protocol.md) uses a different registration and credential. Registration, a last-seen timestamp, a leaderboard counter, or a successful client status check shows neither a new result row nor downstream acceptance. The Worker can update community counters before forwarding a submission, and the client may cache failed submissions locally. A successful API response is a submission response, not proof that every downstream dataset accepted the observation. Check measured data and its freshness separately.

For the community-client path, the checked-in Worker specifies at most 10 registration requests per hour per IP and 1,000 authenticated submissions per hour per node; its submission 429 includes `Retry-After: 3600`. It filters off-list domains and caps a submitted batch at 100 results. These implementation limits can change; use the served response and back off on refusal. The custom-client path has its own trial/full limits in the [protocol](https://voidly.ai/probe-protocol.md).
