URnetwork API: Network

Gain permission to use the connect protocol as the requested clientId, or assign a new clientId.

When the deployment enforces concurrent clients, a network is limited to 100 TOP-LEVEL clients (clients with no source_client_id, which are the network's peers); ancillary clients are not counted. Over the limit the call answers 200 with error.upgrade_required -- a plan limit, not a hard cap -- and an agent can settle it inline with the x402 round trip below.

Remove a client from the network.

Remove many clients from the caller's network in one call, so a network with hundreds of thousands of offline clients can be cleared without the caller chunking the request. Duplicate ids are collapsed; at most 1,000,000 ids per call (more is an error), and the body is capped at 100 MB.

A small request (at most 10,000 ids) runs synchronously when the deployment's hourly bulk-removal budget has room right now, and the result is empty. Anything else is handed to a background task and the result says so: scheduled with scheduled_for naming the hourly bucket it was reserved against (the present moment when this hour had room, a future hour when it did not). The work is NOT complete when scheduled is true.

Two refusals leave the ids unscheduled and ask the caller to retry: already_in_progress when this network already has a background run going, and too_many_concurrent_runs when the deployment-wide cap on concurrent runs is reached.

Offer the calling client as an extender and, if it proves out, publish it in the directory (connect/EXTENDER.md C2).

Requires a CLIENT jwt (from /network/auth-client): the activation is attributed to a network and a client, and is rate limited per user (6 per hour). Call it on the family api host of the family being activated -- api-v4.bringyour.com for an IPv4 address, api-v6.bringyour.com for an IPv6 one -- so the caller address the operator probes back has exactly one family. An operator without family hosts (a development operator on an ip literal, say) is activated through its plain api url instead, and the family of the outcome is the one the result reports. NEVER call it through an extender: the address that is probed and published is the address this request arrived from.

Nothing is taken on the caller's word. Inside the request, and within a 10 second budget, the operator dials BACK to the caller's own address on every carrier offered and on every dns port listed, each time sending a challenge and verifying the response signature against public_key_hex; it then performs a verified GET /hello forward through the tcp carrier to its own api. The tcp carrier is therefore required, since only it can prove the forward. One dns port failing is not the dns carrier failing -- only a dns carrier with no port left is refused -- and the forward must arrive on the same family the probe reached, or the record would promise an address that does not carry the traffic.

A refusal is a NORMAL 200 with activated: false and error naming the carrier that failed, not an HTTP error: the caller is a provider running this on a timer, and it needs to tell "this carrier did not answer" from "the request was malformed". Nothing is stored on a refusal.

On success the extender row and the family's address row are upserted active and a record publish row is queued for gossip. The answer carries the extender's own freshly signed record and up to 8 signed records of other active extenders, which is the only bootstrap an app has before it has any peer.

Forward the latency attestations providers made to this client's extenders (connect/DESIGNNOTES4.md §3). Accepted for one release for extenders on the previous binary, and superseded by /network/ping-report, where the pinger reports its own pings with the target's co-signature (connect/GEOMAP.md D14).

A provider that probes an extender puts its client id in the probe; the extender answers with a fresh nonce; the provider sends back its measured round trip under its own client key signature, over the nonce, the extender's identity key, its client id and a timestamp. The extender forwards the claim only when it is no lower than the interval the extender itself observed between its response and the provider's frame, less a tolerance -- so the provider cannot claim to be closer than it was seen to be, and the extender cannot change what the provider signed. Only a provider attests; a consumer client probes without identifying itself.

Requires a CLIENT jwt: every attestation must name, by identity key, an extender the calling client activated, and the report is rate limited per user (240 per hour). The operator verifies each attestation's signature against the provider's registered client key and stores what verifies. An attestation that does not decode, does not verify, names an extender the caller does not own, names the extender's own client as the provider, carries a timestamp more than a day from the operator's clock or a round trip no column can hold, or repeats one already stored (same extender, provider and nonce) is counted in rejected and not named. A report of more than 256 attestations is refused whole.

Report the pings this client measured of extenders, and what each target answered (connect/GEOMAP.md §2.5). The PINGER reports: a provider over its client credential, an extender over its activation credential. Both kinds share one report and one attestation, and sign under different domains (see ExtenderPing).

A probe that identifies its pinger is answered with a fresh nonce; the pinger sends back its measured round trip under its own signature; the target accepts the claim only when it is no lower than the interval it observed itself, less a tolerance, and answers every claim with one verdict: an acceptance carrying the target's co-signature over the exact claim, or a refusal with its reason. The pinger reports the claim and what became of it, whatever that was.

Requires a CLIENT jwt, and every ping must name the calling client as its pinger: a provider ping by the caller's client id, an extender ping by the identity key of an extender the caller activated. The target must be an extender the operator has activated, active or not, and not one the caller activated itself. The operator verifies the pinger's signature under the key it holds for the pinger -- the provider's registered client key, or the extender's stored identity key -- and RECOMPUTES the verdict under the target's stored identity key: a ping is stored as co-signed only when its co-signature verifies, whatever outcome says. A ping without a verifying co-signature is the pinger's claim only, never a measurement; at most 64 of them are accepted from one report and the rest are rejected. A ping that does not decode, names another pinger, names an unknown target or the caller's own, does not verify, carries a timestamp more than a day from the operator's clock, or repeats one already stored (same target, pinger and nonce) is counted in rejected and not named. A report of more than 256 pings is refused whole, and reports are rate limited per user (240 per hour).

Search for locations and groups that match a query, where there are at least one active provider in good health. The match algorithm accounts for typos and misspelling, and the tolerance can be tuned in the input. Note that a location or group will need to be mapped to an actual provider using /network/find-providers2.

Randomly sample providers for locations, groups, or devices, which are active and in good health. This allows random iteration by using the exclude input to mark visited providers.

Allow network to toggle leaderboard ranking visibility

Turn the network's name on or off on the points leaderboard. Every network with points is ranked and listed either way; this switch only decides whether its row shows the network name or "Anonymous". The emoji tag (/network/emoji) shows on the row regardless.

Set the network's emoji tag: 1 to 6 emoji (each grapheme cluster must be a single emoji: pictographs with skin tones, ZWJ sequences, keycaps, flags). Letters, digits and punctuation are rejected with the message "Use 1 to 6 emoji.". An empty string clears the tag. The tag is shown on the points leaderboard row and in the network's own header.

Block providing to a location

Unblock providing to a location

Update the caller network's name.

Store where a provider's traffic exits: exit_ip, the address the operator's own /my-ip-info echo saw the probe come from THROUGH the provider's tunnel. The server places it with its own GeoLite2 (the location row, the country, and city_confident when GeoLite2's accuracy radius is within the configured city radius) and prefers it over the lookup on the provider's control-connection address. The address itself is never stored, and no ip-intelligence verdict is recorded (connect/GEOMAP.md §11.3, D24).

A submission without exit_ip -- the retired vendor-consensus shape -- is refused with a 400; the legacy fields are accepted and ignored for one release. The body is capped at 16 KiB.

Record that the prober TRIED to probe a provider, whether or not the try produced a location. The prober reports failures here; a success is already implied by the stored location. Without this, a provider that can never be probed successfully would sort to the head of the due queue on every poll forever.

Submit up to 10,000 blackhole results at once: for each provider, did anything get through. The WHOLE batch is validated before any of it is written, so a caller reporting fire-and-forget is never left unable to tell which results landed. checked_at is required and is never fabricated server-side (an "as of now" stamp would defeat the freshness bound the gate depends on) and may not be in the future; a failed check must name a failure class of at most 64 characters. Unknown fields are rejected.

A failed check is a failure, not a verdict: the server keeps each provider's run of consecutive failures, and the provider is dark only once the run reaches the configured count over the configured span (connect/GEOMAP.md §11.3); a TLS-authentication failure is dark at once. A check marked not_measured -- its tunnel was gone and could not be re-created -- counts nothing and only reschedules the provider.

Take deployment-wide byte budget before spending any probe bytes. Active probing pulls real paid contract traffic through a provider's tunnel, so it is rationed per hourly bucket. byte_count is clamped to the per-probe maximum (16 MiB), so an oversized request cannot swallow a bucket.

The prober measures over a tunnel it has open right now, so a reservation that lands in a LATER bucket is cancelled again and the request answered 429 with Retry-After pointing at the bucket that does have room; without that the hourly ceiling would be decorative.

Store one active bandwidth measurement taken over a provider's tunnel. An active probe is a point measurement rather than a window, so the server stamps arrival time as both window bounds.

The row is keyed on (client_id, source), so source must be one of the known ACTIVE values; an unrecognised tag would create a row nothing ever reads or replaces. passive is refused outright: that figure is derived server-side from bytes the provider was already paid to carry, which is what makes it ungameable, and accepting a submitted one would let this endpoint overwrite a derived figure with an asserted one. A non-positive rate or sample size is refused rather than allowed to overwrite a real measurement.

Store one egress-health run: over the provider's tunnel, how many of the sampled loads of each class passed after their retries -- a load fails only when every attempt failed (connect/GEOMAP.md §11.3). Loads whose tunnel could not be re-created, and canaries, are in no count and are named apart. A failed load of a site on probation, or of one marked incompatible with the provider's place, is taken out of the counts by the server and named in the stored row's unscored_failed_names. The row is an upsert keyed on client_id, so a bad submission does not sit beside the good one -- it destroys the last good measurement. Everything is therefore validated before anything is stored, and unknown fields are rejected outright (a misspelled field would decode to a perfectly consistent zero, filling the table with plausible rows describing a measurement that never happened).

class_results must sum EXACTLY to ok_count/total_count: the classes are the score, and a total that does not decompose into them means the two halves came from different runs. The reputation class dissolved into the sites: reputation_ok, reputation_total and reputation_failed_names are accepted, always zero from a current prober, and ignored, and a reputation key inside class_results is still refused.

A real client network reporting that a provider carried nothing. This is the ONE route in this group that is not operator-secret authed: the reporter is a network, and the network is the unit the quorum counts, so the reporting network is taken from the session jwt and never from the body. A met quorum only brings the provider's next probe forward. Unknown fields in the body are rejected.