Operator API

URnetwork API: Network

Version 1.0.0 · 230 operations across 14 groups.Especificación OpenAPI ↗

URnetwork implementa por completo la especificación de operador del protocolo UR. Protocolo UR ↗

Network

39 operations

POST/network/auth-client

Bearer authauthNetworkClient

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

Two limits apply to creating a top-level client (a client with no source_client_id; top-level clients are the network's peers). Both are enforced only while the deployment enforces concurrent clients, and ancillary clients (with a source_client_id) count toward neither:

  • The client limit: 100 active top-level clients. Over it the call answers 200 with error.client_limit_exceeded and the message "Client limit exceeded."
  • The plan's limit on concurrently connected top-level clients. Over it the call answers 200 with error.client_limit_exceeded and error.upgrade_required -- a plan limit, not a hard cap.

An agent that pays over x402 may ask for the terms instead of the error: with the request header X-UR-X402: 1, a refusal with error.upgrade_required answers HTTP 402 with the terms for a Pro month when x402 inline payments are enabled and a price can be quoted, so the agent can pay and retry the same request with PAYMENT-SIGNATURE (x402 v2) or X-PAYMENT (x402 v1) (see /x402). x402 has no header a client sends before it is quoted, so without X-UR-X402: 1 every refusal is the 200 with the error, which the apps, the browser extension and ur.io prompt on. A request that carries a payment is never quoted again.

Two more limits apply to every hosted proxy create (a new client with proxy_config, top-level or ancillary), and these are always enforced, whether or not the deployment enforces concurrent clients:

  • The active proxy cap: a free network may hold 5 active hosted proxies and a Pro network 1000. Over it the call answers with error.client_limit_exceeded and the message "Your plan's limit of 5 active proxies is reached. Remove a proxy to create another, or upgrade to UR Pro for more." A Pro network's message stops after "create another".
  • The create rate: a free network may create 5 hosted proxies a minute and a Pro network 20. A create these limits refuse still counts toward its minute. Over the rate the call answers with error.client_limit_exceeded and the message "Your plan allows 5 new proxies a minute. Try again in a minute, or upgrade to UR Pro for more." A Pro network's message stops after "Try again in a minute". For a free network both refusals also set error.upgrade_required, so they answer the way the plan limit above does: 200 with the error, or HTTP 402 with the terms for a Pro month to a caller that asks for them with X-UR-X402: 1. Only a new proxy is refused: the network's existing proxies keep working, and removing one makes room for the next. A re-auth of an existing client counts toward neither limit.

A network on an Embed plan has a per-network client allowance that sets both client limits and its active proxy cap.

A provider install (a device that only provides, such as an embedded provider) sets provide_intent. Creating a top-level client with it is exempt from the 100 top-level client cap and from the concurrent connected client check, because providers do not count toward the plan's client limit. The client is a provider install for its life: it never appears in the network's peer list (/network/peers), does not receive it, and does not count toward the 100 top-level clients that keep the peer list enabled. Connecting keeps the flag honest: a client that connects with provide intent (X-UR-Provide-Intent: 1) must qualify as a public provider within a grace period, or it takes a normal client slot if one is free, or it is disconnected with the client limit exceeded close. A person's device that also provides declares intent on its connections instead and stays a network peer.

Like roles or a principal the call may not set, a proxy_config the call cannot use is refused before anything is created: the call answers 200 with error.message and no client_id or by_client_jwt. The refusals are:

  • "Invalid performance profile: " and the reason, for an invalid initial_device_state.performance_profile (the rules are on that field), for example "Invalid performance profile: Window size [2, 1] invalid. Max must be >= min"
  • "Invalid location", when initial_device_state is omitted, or has no location and no country_code that names a country
  • "Could not parse lock ip " and the entry, for a lock_ip_list entry that is neither an IP address nor a subnet

A unique-exit proxy (proxy_config.unique_exit) is a hosted proxy whose exit IP no other unique-exit proxy of the network shares (an exact IPv4 address, or an IPv6 /64). It counts toward the active proxy cap and the create rate like any hosted proxy. Its create is refused before anything is created, and without spending the cap or the rate, when:

  • the network is not on UR Pro: error.upgrade_required with the message "Unique exit IPs are a UR Pro feature. Upgrade to UR Pro to create unique-exit proxies." (HTTP 402 with the terms for a Pro month to a caller that asks with X-UR-X402: 1, like the plan limit above)
  • the location names one provider (connect_location_id.client_id): "A unique exit picks its own provider: use a country, region, city, group or best available location."
  • unique_exit_replace is not auto or manual: 'unique_exit_replace must be "auto" or "manual".'
  • no exit the network does not already hold is available in the location: error.no_unique_supply with the message "No unique exit IP is available in this location right now. Try another location, or best available." The created proxy reports its exit in proxy_config_result.exit.

A re-auth of an existing client (client_id set) ignores proxy_config.

show schema
client_id
string

udid. Optional. If this is given, it must currently exist in the network. Omit this to assign a new client id.

source_client_id
string

udid. Optional. The source client id when creating an ancillary client id. It must be a client of the caller's network: any other id is refused with error.message "Client does not exist.", and nothing is created.

description
string

If this is a new device, sets the device name to the description of the device.

device_spec
string

If this is a new device, sets the device spec.

time_zone
string

Optional. The device's IANA time zone (e.g. America/Chicago). With locale and locales, the campaign emails are placed in the reader's day and written in their language; the server keeps only the network's latest values, never on the client. Every app sends it on each auth-client call; the latest wins. A zone of UTC is ignored.

locale
string

Optional. The device's BCP 47 locale ("de-DE"), the first of locales. Same rules as time_zone.

locales
array<string>

Optional. The device's languages, most preferred first, as BCP 47 tags; the campaign emails are written in the first one a template serves. Leave out a language the device cannot name rather than sending a default such as "en". Same rules as time_zone.

array
string
roles
array<string>

Optional. Identity roles assigned to the client at creation, immutable after. Only a network session may set these; when omitted, the session's own roles are inherited. The values have no meaning to the network.

array
string
principal
string

Optional. Identity principal assigned to the client at creation, immutable after. Only a network session may set this; when omitted, the session's own principal is inherited.

provide_intent
boolean

Optional, default false. The new client is a provider install: it only provides publicly (public provide mode), like an embedded provider. A new top-level client created with this set is exempt from the 100 top-level client cap and the concurrent connected client check, and is never a network peer (it is not in the peer list, does not receive it, and does not count toward the 100 top-level clients that keep the peer list enabled). The platform judges it as a provider when it connects with provide intent; see /network/auth-client. Do not set it for a person's device that also provides. Ignored when client_id or source_client_id is set.

proxy_config
object

Optional. Set if the intended use case of the client is cloud proxy. Note local traffic is not allowed on the cloud proxy. A destination must be set via the SDK.

lock_caller_ip
boolean

Optional. Allow only the caller's IP subnet to access the proxy.

lock_ip_list
array<string>

Optional. Allow only IPs/subnets in the list to access the proxy. The IPs/subnets are converted to the internal IP subnet width. An entry that is neither an IP address nor a subnet is refused (see the endpoint).

array
string
https_require_auth
boolean

Optional. If the client supports ECH, this is not needed, since the HTTP proxy URL will itself be the auth.

enable_wg
boolean

Optional. If enabled, a WireGuard configuration will be created for the proxy.

unique_exit
boolean

Optional, UR Pro. Pins the proxy to one provider whose exit IP no other unique-exit proxy of the network holds: an exact IPv4 address, or an IPv6 /64. The provider is chosen in initial_device_state's location (a country, region, city, group, or best available; not a client_id), from healthy, high-quality providers whose exit has been observed in the last 24 hours. Each provider serves at most 3 unique-exit proxies across all networks, and gives each at most half its estimated throughput. The exit IP itself is never reported; proxy_config_result.exit and /network/proxies report its place and an opaque exit_id. The refusals are on the endpoint.

unique_exit_replace
one of

Optional, with unique_exit. auto, the default, moves the proxy to a new unique exit when its provider goes offline for more than 120 seconds, stops answering, is excluded for a failed verdict, or starts sharing an exit with another of the network's unique-exit proxies (the last two at once), at most 6 times an hour per proxy and for a tenth of the network's unique-exit proxies an hour. manual keeps the proxy on its failing exit, exit.state replacing, until /network/proxy/rotate-exit moves it: for sessions that must not change IP on their own.

one of
value
value
initial_device_state
object

Required when the call creates the client (client_id omitted): without a location, or a country_code that names a country, the call is refused with "Invalid location" (see the endpoint).

Whenever the device is created, it will be set up with this initial state. To configure the device beyond the initial state, the SDK ProxyDevice must be used. Note that the SDK ProxyDevice must reconfigure the device each time it receives a change notice.

country_code
string

Optional. Use one of country_code or location. A two-letter country code such as "de", upper or lower case. Without a location, the call is refused with "Invalid location" (see the endpoint) unless country_code names a country.

location
object

Optional. Use one of country_code or location. A location is used as given, ahead of country_code. For no particular location, set connect_location_id.best_available to true.

connect_location_id
object
client_id
string

udid. Optional.

location_id
string

udid. Optional.

location_group_id
string

udid. Optional.

best_available
boolean

Optional. True connects through the best available providers, in no particular location.

name
string
location_type
one of
one of
value
value
value
provider_count
integer
promoted
boolean
match_distance
integer
city
string
region
string
country
string
country_code
string
city_location_id
string

udid. Optional.

region_location_id
string

udid. Optional.

country_location_id
string

udid. Optional.

stable
boolean
strong_privacy
boolean
network_peer
boolean

Marks the location as one of the network's own trusted peers, which egresses under ProvideModeNetwork. It is explicit state: a fixed client id alone does not imply a trusted peer, since it can be a public exit.

performance_profile
object

Optional. Omitted, the device runs in auto mode. The call is refused (see the endpoint) unless the profile passes the check the device itself applies:

  • every window_size value is at least 0
  • window_size_max is at least window_size_min
  • a fixed window (window_type quality or speed) has a window_size_max of at least 1, since a window that can hold no provider leaves no route

The check covers auto mode too, although auto ignores window_size. Without window_size the device uses its default window, which passes.

allow_direct
boolean

Setting this exposes the real source IP to the provider. It has no effect here: the hosted proxy device always runs with direct mode off, because a direct connection would expose the proxy host's address, and with it that the client is hosted and where.

post_quantum_encryption
boolean

Requires a post-quantum end-to-end encrypted session with each provider. Traffic to a provider waits for its session, and a provider that cannot establish one is skipped, never used without it, so fewer providers may qualify. Unset, the default, the device opens no such session.

window_type
one of

Optional. auto, the default, balances traffic across the window types and ignores window_size. quality and speed fix the window type, sized by window_size.

one of
value
value
value
window_size
object
window_size_min
integer
window_size_min_p2p_only
integer

The minimumum number of items in the windows that must be connected via p2p only. Leave 0 for default behavior.

window_size_max
integer

Inclusive, soft limit. When window_size_max==window_size_min, a special fixed size mode is enabled.

window_size_hard_max
integer

Leave 0 to disable (no hard limit)

window_size_reconnect_scale
number

Clients per source per stream

keep_healthiest_count
integer

Leave 0 to disable

ulimit
integer

Leave 0 to disable (no limit)

dns_resolver_settings
object

Optional. How the proxy device resolves DNS. DoH urls are queried as RFC 8484 wire format, and each must present an IP-SAN certificate when addressed by IP.

enable_remote_doh
boolean
enable_local_doh
boolean
enable_remote_dns
boolean
enable_local_dns
boolean
dns_upgrade_mask_address
string

A stand-in destination for the platform's plain DNS configuration while the upgrade mux intercepts UDP/TCP :53. It is not an upstream resolver.

remote_doh_urls_ipv4
array<string>
array
string
remote_doh_urls_ipv6
array<string>
array
string
local_doh_urls_ipv4
array<string>
array
string
local_doh_urls_ipv6
array<string>
array
string
remote_dns_ipv4
array<string>
array
string
remote_dns_ipv6
array<string>
array
string
local_dns_ipv4
array<string>
array
string
local_dns_ipv6
array<string>
array
string
3 statuses · show schema
200
by_client_jwt
string
client_id
string

udid

proxy_config_result
all of

The following proxy URLs and auths may be used:

URLAuth
https://<auth_token>.<proxy_host>:<https_proxy_port>no auth needed when the client connects with TLS
https://<proxy_host>:<https_proxy_port>use HTTP Proxy-Authorization Basic with auth_token as the username (empty pass), or Bearer with auth_token as the bearer token
http://<proxy_host>:<http_proxy_port>use HTTP Proxy-Authorization Basic with auth_token as the username (empty pass), or Bearer with auth_token as the bearer token
tcp://<proxy_host>:<socks_proxy_port>use auth_token as the username (empty pass)
wg://<proxy_host>:<wg_proxy_port>use wg_config.config as the full WireGuard config file content, which contains all the necessary keys
keepalive_seconds
integer

The proxy url will be valid until the client is removed. However, to keep the device and state in memory, the proxy must receive a message at least once per this interval. The SDK ProxyDevice will automatically send a heartbeat with this many seconds. If the proxy is removed from memmory, the next call to the proxy will create a new device set up to the initial_device_state (if present).

exit
ProxyExit

Set for a unique-exit proxy (proxy_config.unique_exit): the exit it was created on.

exit_id
string

udid. Opaque, stable while the proxy stays on one exit; a new exit (a replacement or a rotate) has a new id. Absent while the proxy has no exit.

country_code
string

The exit's two-letter country code, lower case.

region
string
city
string
exit_since
string (date-time)

When the proxy moved to this exit.

state
one of

assigned: the proxy runs on its exit. replacing: the exit failed and the proxy waits for a new one (the replacement caps, or manual replace mode until /network/proxy/rotate-exit). no_supply: the exit failed and no other unique exit is available in the location yet; the proxy is retried automatically in auto mode.

one of
value
value
value
state_reason
string

With replacing or no_supply, why: offline, unreachable, verdict, collision, cap, manual, or no_supply.

replace_mode
one of

The proxy's unique_exit_replace, auto or manual.

one of
value
value
change_id
integer
create_time
string

datetime

proxy_id
string

udid

client_id
string

udid

api_base_url
string
block
string
api_port
integer
http_proxy_url
string
https_proxy_url
string
socks_proxy_url
string
auth_token
string
instance_id
string

udid. The instance_id of the proxy device.

proxy_host
string
socks_proxy_port
integer
http_proxy_port
integer
https_proxy_port
integer
wg_config
objectnull
wg_proxy_port
integer
client_private_key
string
client_public_key
string
client_ipv4
string
proxy_public_key
string
config
string

The WireGuard config file for this client.

error
object
client_limit_exceeded
boolean

A hard cap or a rate limit was hit.

upgrade_required
boolean

A plan limit that UR Pro lifts refused the request: the free plan's limit for concurrent connected top-level clients, its hosted proxy cap or create rate, or a Pro-only feature. Unlike client_limit_exceeded alone this is a plan limit, not a hard cap: surface an upgrade prompt. It is the flag the x402 inline-payment round trip keys off, for a caller that asks for terms with X-UR-X402: 1.

no_unique_supply
boolean

A unique-exit create (proxy_config.unique_exit) found no exit in the location that the network does not already hold. Nothing was created, and neither the proxy cap nor the create rate was spent: try another location, or best available.

message
string
401
No body
402
x402Version
integer
error
string
accepts
array<X402Accept>
array
scheme
string
network
string
maxAmountRequired
string
resource
string
description
string
mimeType
string
payTo
string
asset
string
maxTimeoutSeconds
integer
extra
map

What the scheme needs to build the payment: the token's EIP-712 domain (name, version) on EVM networks, the facilitator's feePayer (and transactionVersions, when it names them) on Solana.

map

POST/network/register-client-v1

Bearer authregisterNetworkClient

Create, or recover after a lost answer, one top-level client and its device under a caller-chosen registration key. It is the versioned, idempotent alternative to /network/auth-client for creating a client: an older server that lacks this route answers 404 rather than silently allocating another client.

The call needs a network JWT (no client_id and no device). The body is exactly these five string fields, with no unknown or duplicate fields and at most 16 KiB:

  • schema: urnetwork-client-registration-v1.
  • registration_id and scope_sha256: 64 lowercase hex digits each (a SHA-256), not all zeros. Within a network, either one binds to exactly one client and device.
  • description (at most 1024 bytes) and device_spec (at most 4096 bytes).

Replaying the same request answers with the same client and device and a fresh client JWT. A replay never recreates a removed or inactive identity, and a key bound to a different request or authority is refused. Proxy and payment options are not part of this route. The client limits described on /network/auth-client apply.

Refusals answer 200 with error.code:

  • invalid_request: the body is incomplete or unsupported.
  • network_authority_required: the session is not a network session.
  • client_limit: the network is over a client limit.
  • authentication_refused: client creation was refused for another reason; error.message says why.
  • registration_conflict: the key is bound to a different request or authority.
  • identity_unavailable: the registered client or device was removed, is inactive, or no longer matches its original device or roles.
show schema
schema
string
enum: urnetwork-client-registration-v1
registration_id
string

64 lowercase hex digits, not all zeros.

scope_sha256
string

64 lowercase hex digits, not all zeros. Immutable caller-owned provenance.

description
string

At most 1024 bytes.

device_spec
string

At most 4096 bytes.

3 statuses · show schema
200
schema
string
registration_id
string
request_sha256
string

The SHA-256 of the canonical request.

client_id
string (uuid)
device_id
string (uuid)
by_client_jwt
string
error
object
code
string
enum: invalid_request, network_authority_required, client_limit, authentication_refused, registration_conflict, identity_unavailable
message
string
401
No body
403
No body

GET/network/client-data-cap

Bearer authgetNetworkClientDataCap

Read a client's optional data caps and its usage against them.

The network's root JWT (a network JWT with no client_id) reads any client in the network, named by client_id. A client's own scoped JWT reads only that client: client_id may be omitted, and must match the JWT's client when given.

Usage counts the billable bytes the client consumes, including its child clients. It is accounted when transfer contracts settle and rolled up within about two minutes, so a client can pass a cap by up to the size of its contracts still in flight. capped is true once a cap is reached; the client then gets no new transfer contracts until the monthly period rolls over, the cap is raised or cleared, or the running total is reset.

Refused with error.message "Embed isn't enabled for this network." unless the caller's network is Embed-enabled: an Embed plan, which the URnetwork team enables network by network (see GET /network/embed).

client_id(query)
string (uuid)

The client to read. Required with the root JWT; optional with the client's own JWT.

2 statuses · show schema
200
client_id
string (uuid)
monthly_byte_limit
integer,null (int64)

The monthly cap in bytes, or null for none.

monthly_used_byte_count
integer (int64)

Bytes used in the current UTC calendar month.

monthly_period_start
string (date-time)

Start of the current monthly period (UTC).

monthly_period_end
string (date-time)

End of the current monthly period (UTC), when monthly usage resets.

total_byte_limit
integer,null (int64)

The running-total cap in bytes, or null for none.

total_used_byte_count
integer (int64)

Bytes used since the running total last reset.

total_period_start
string,null (date-time)

When the running total began: the client's first cap request, or its last reset_total. null for a client that has never had a cap request.

capped
boolean

True when the client has reached a cap and gets no new transfer contracts.

capped_reason
string

Which cap was reached, or empty when the client is not capped.

enum: , monthly, total
error
object
message
string
401
No body

POST/network/client-data-cap

Bearer authsetNetworkClientDataCap

Set a client's optional data caps. The two caps are independent and each is optional. Each field merges: omit it to keep the current value, send null to clear that cap, or send a byte count to set it. A cap of 0 pauses the client at once, which pauses one user without removing the client.

  • monthly_byte_limit caps usage in each UTC calendar month and resets on its own at 00:00 UTC on the first of the month.
  • total_byte_limit caps a running total that never resets on its own. Raise or clear it, or send reset_total: true to zero the running total and start a new period.

At a cap the client gets no new transfer contracts (a hard stop) until the month rolls over, the cap is raised or cleared, or the total is reset. Only the network's root JWT may set caps, and client_id must belong to the caller's network; a client-scoped JWT is refused.

Refused with error.message "Embed isn't enabled for this network." unless the caller's network is Embed-enabled: an Embed plan, which the URnetwork team enables network by network (see GET /network/embed).

show schema
client_id
string (uuid)

The client to set caps for. It must belong to the caller's network.

monthly_byte_limit
integer,null (int64)

Bytes the client may use in each UTC calendar month; resets at 00:00 UTC on the first of the month. Omit to keep the current value, null to clear the cap, 0 to pause the client.

total_byte_limit
integer,null (int64)

Bytes the client may use in the running total, which does not reset on its own. Omit to keep the current value, null to clear the cap, 0 to pause the client.

reset_total
boolean

Zero the running total and start a new total period.

3 statuses · show schema
200
client_id
string (uuid)
monthly_byte_limit
integer,null (int64)

The monthly cap in bytes, or null for none.

monthly_used_byte_count
integer (int64)

Bytes used in the current UTC calendar month.

monthly_period_start
string (date-time)

Start of the current monthly period (UTC).

monthly_period_end
string (date-time)

End of the current monthly period (UTC), when monthly usage resets.

total_byte_limit
integer,null (int64)

The running-total cap in bytes, or null for none.

total_used_byte_count
integer (int64)

Bytes used since the running total last reset.

total_period_start
string,null (date-time)

When the running total began: the client's first cap request, or its last reset_total. null for a client that has never had a cap request.

capped
boolean

True when the client has reached a cap and gets no new transfer contracts.

capped_reason
string

Which cap was reached, or empty when the client is not capped.

enum: , monthly, total
error
object
message
string
401
No body
403
No body

GET/network/client-data-caps

Bearer authlistNetworkClientDataCaps

List the data caps and usage of every client in the caller's network that has a cap set, in a stable order, a page at a time. Pass the returned next_cursor as cursor to read the next page; it is null on the last page. Only the network's root JWT may list; a client-scoped JWT is refused.

Refused with error.message "Embed isn't enabled for this network." unless the caller's network is Embed-enabled: an Embed plan, which the URnetwork team enables network by network (see GET /network/embed).

cursor(query)
string

The next_cursor from the previous page; omit for the first page.

limit(query)
integer

The page size.

3 statuses · show schema
200
clients
array<ClientDataCapResult>
array
client_id
string (uuid)
monthly_byte_limit
integer,null (int64)

The monthly cap in bytes, or null for none.

monthly_used_byte_count
integer (int64)

Bytes used in the current UTC calendar month.

monthly_period_start
string (date-time)

Start of the current monthly period (UTC).

monthly_period_end
string (date-time)

End of the current monthly period (UTC), when monthly usage resets.

total_byte_limit
integer,null (int64)

The running-total cap in bytes, or null for none.

total_used_byte_count
integer (int64)

Bytes used since the running total last reset.

total_period_start
string,null (date-time)

When the running total began: the client's first cap request, or its last reset_total. null for a client that has never had a cap request.

capped
boolean

True when the client has reached a cap and gets no new transfer contracts.

capped_reason
string

Which cap was reached, or empty when the client is not capped.

enum: , monthly, total
error
object
message
string
next_cursor
stringnull

Pass as cursor to read the next page; null on the last page.

error
object
message
string
401
No body
403
No body

GET/network/client-acl-group

Bearer authgetNetworkClientAclGroup

Read a client's ACL group, default or isolated.

The network's root JWT reads any client in the network, named by client_id. A client's own scoped JWT reads only that client: client_id may be omitted, and must match the JWT's client when given.

Refused with error.message "Embed isn't enabled for this network." unless the caller's network is Embed-enabled: an Embed plan, which the URnetwork team enables network by network (see GET /network/embed).

client_id(query)
string (uuid)

The client to read. Required with the root JWT; optional with the client's own JWT.

2 statuses · show schema
200
client_id
string (uuid)
acl_group
string
enum: default, isolated
error
object
message
string
401
No body

POST/network/client-acl-group

Bearer authsetNetworkClientAclGroup

Set a client's ACL group: default or isolated. New clients are default.

An isolated client never appears in the network's peer list (/network/peers and the peer change stream) and does not receive the list. It does not count toward the recently active top-level clients that keep the peer list enabled. It still counts toward the network's client limit and its concurrent connection limit. Messages between clients need the peer list, so an isolated client cannot use them.

Only the network's root JWT (or an API key) may set the group, and client_id must belong to the caller's network; a client-scoped JWT is refused.

Refused with error.message "Embed isn't enabled for this network." unless the caller's network is Embed-enabled: an Embed plan, which the URnetwork team enables network by network (see GET /network/embed).

show schema
client_id
string (uuid)

The client to set. It must belong to the caller's network.

acl_group
string
enum: default, isolated
3 statuses · show schema
200
client_id
string (uuid)
acl_group
string
enum: default, isolated
error
object
message
string
401
No body
403
No body

GET/network/embed

Bearer authgetNetworkEmbed

Read whether the caller's network is Embed-enabled, its client allowance and how many clients count toward it.

Embed plans are sold through a review and a contract, and the URnetwork team then enables Embed network by network. Until then the data-cap and ACL-group operations refuse the network with error.message "Embed isn't enabled for this network." This read is not gated: a network without Embed reads enabled: false.

client_limit is the network's top-level client allowance: its Embed plan allowance, or the default of 100. active_client_count counts exactly what that limit counts: the network's active top-level clients, not counting provider installs.

Only the network's root JWT (or an API key) may read it; a client-scoped JWT is refused.

3 statuses · show schema
200
enabled
boolean

True when the URnetwork team has enabled Embed for the network.

client_limit
integer

The network's top-level client allowance; 100 without an Embed plan allowance.

active_client_count
integer

The network's active top-level clients that count toward client_limit (provider installs do not).

error
object
message
string
401
No body
403
No body

POST/network/remove-client

Bearer authremoveNetworkClient

Remove a client from the network.

show schema
client_id
string

udid

1 status · show schema
200
error
object
message
string

POST/network/remove-clients

Bearer authremoveNetworkClients

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.

show schema
client_ids
array<string>

udids. Duplicates are collapsed; at most 1,000,000 per call.

array
string
4 statuses · show schema
200
scheduled
boolean

Handed off to the background task; deactivation is NOT complete yet.

scheduled_for
string (date-time)

The start of the hourly bucket the request was reserved against; present whenever scheduled is true. Now (or a moment before) when this hour had room, a future time when it did not.

already_in_progress
boolean

This network already has a background run going; the ids were NOT scheduled.

too_many_concurrent_runs
boolean

The deployment-wide cap on concurrent runs was reached; the ids were NOT scheduled.

400
No body
403
No body
429
No body

POST/network/extender-activate

Bearer authextenderActivate

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. It is rate limited per address family, for IPv4 and for IPv6 each, over a trailing hour: 6 per client; 6 per caller address (its /32 or /64), over every client and every account; and per account 60 plus 6 for each proven host, at most 1200. A proven host is an identity key of the account that passed activation on that family between 1 hour and 7 days ago, counted once per address and at most 32 per /24 or /48. A key the account already proved at the caller's /32 or /64 spends 6 an hour of its own there instead of the address's, so posts relayed through an extender cannot hold off its own re-activation. The operator also probes only so many activations at once, and refuses one more as busy. A budget is spent only when the operator is about to probe, so a request refused before the probe (malformed arguments, the wrong family, a spent budget, a busy operator) costs nothing, and a refusal by a spent budget or a busy operator says in retry_after_seconds how long until there is room again: the longest wait of the spent budgets, plus up to a minute. 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 activation posted to one family's host that arrives over the other family is refused before it is probed. 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 one 10 second probe budget, the operator dials BACK to the caller's own address, each time sending a challenge and verifying the response signature against public_key_hex. The required test runs first and alone decides acceptance (connect/EXTENDER.md C2a): the tcp carrier's challenge, then a verified GET /hello forward through the tcp carrier to the operator's own api, which must arrive on the same family the probe reached, or the record would promise an address that does not carry the traffic. The tcp carrier is therefore required, since only it can prove the forward. Only then is each optional carrier offered probed: every listed dns port under its own 3 second budget, then quic with what is left. An optional carrier, or a dns port, that does not answer is left out of the record and listed in refused_carriers; it never refuses the activation.

A refusal is a NORMAL 200 with activated: false and error naming the step of the required test 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. Every step is timed (EXTENDER.md C2b): probe_steps lists each step the probe ran, and a refusal says how long its step ran or, when the step's budget ran out first, how much it had, so an extender that answers late can tell that from one that does not answer at all.

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.

show schema
public_key_hex
string

The extender's identity public key, hex. Every probe requires a signature over a fresh challenge under this key.

reality_public_key_hex
string

An optional X25519 public key the extender publishes, as hex. A passing activation stores it, and the extender's records carry it while the network that posted it holds the identity key. Omitted, a passing activation clears a stored key. A value that is not a usable 32-byte X25519 key is refused before anything is probed. The activation does not prove the extender holds the private half.

tcp_port
integer

The tcp carrier port. 0 takes the default, 443.

udp_port
integer

The quic carrier port. 0 takes the default, 443.

dns_port
integer

The extender's configured dns port, which is what a reader that predates dns_ports dials. 0 takes the default whodis port.

dns_ports
array<integer>

Every dns port the caller is listening on, each probed on its own. Empty offers dns_port alone. One port failing does not fail the dns carrier; only a carrier with no port left is refused.

array
integer
dns_tld
string

The dns carrier's tld. Empty takes the default; at most 128 characters.

carriers
array<string>

The carriers offered, lower-cased and de-duplicated: tcp, quic and dns. At least one is required, and tcp is always required because only it can prove the forward. An unknown carrier is refused.

array
string
enum: tcp, quic, dns
measurement_csr
string

Standard base64 of the DER certificate request for the extender's lag.dev measurement name, <extender_id>.<zone>, whose only name is that one, under an ECDSA P-256 key (lag.dev/PLAN.md C4, A10). Omitted on most activations, which leaves a stored request as it is. A request carried by a successful activation is stored as the extender's; its outcome is read from /network/extender-measurement-cert, never from this answer.

measurement_disabled
boolean

Sent on every activation while the extender's owner has opted out of lag.dev measurement (lag.dev/PLAN.md C4, C9). The operator withdraws the extender's measurement name: its address records go, its certificate is revoked, its records carry no measurement id, and nothing is issued for it. A measurement_csr beside it is not stored. Omitted, the default, changes nothing on its own: a later activation without it and with measurement_csr makes the extender eligible again.

run_id
string

The run of the extender process that posted this activation (EXTENDER.md G3): 32 hex characters of 128 random bits drawn once when the process starts, so every activation of one process carries the same id and a restart a new one. The three run fields are optional, and a well-typed one never refuses an activation: each is stored on the activation's history row when it is well formed, and as null otherwise.

run_start_time
string (date-time)

When that process started, in UTC. Stored when it is no earlier than 2026-11-01 and no later than an hour past the operator's clock.

previous_exit
string

How the run before it ended, as the host that restarted the process reported it: oom, stop when the host stopped it on purpose, the signal that ended it (sigkill, sigterm, sigint, sighup, sigquit, sigabrt, sigsegv, sigbus, sigill, sigfpe, sigtrap, sigpipe, sigalrm, or signal for another), or exit-<code> for an exit code from 0 to 255. Omitted when the host reported none.

2 statuses · show schema
200
activated
boolean
extender_id
string (uuid)

The operator's id of the extender, one per identity key and the same at every activation. The extender's lag.dev measurement name is this id under the measurement zone (lag.dev/PLAN.md N1, N4).

ip
string

The caller address that was probed and published.

ip_version
integer

4 or 6. The forward must arrive on this same family.

carriers
array<string>

The carriers that passed their probe, which is what the stored address and the signed record list.

array
string
dns_ports
array<integer>

The dns ports that passed their probe, ascending, which is what the stored address and the signed record list. Empty when the dns carrier was not offered.

array
integer
refused_carriers
array<ExtenderCarrierRefusal>

The optional carriers that were offered and did not answer, and each dns port that did not, in the order offered (EXTENDER.md C2a). They are left out of the stored address and the signed record. Empty on a refusal, which probes no optional carrier.

array
carrier
string
enum: quic, dns
port
integer

The port the carrier was probed on.

error
string

Why the probe failed. A probe whose budget ran out first says how much time it had: "no answer within 3 s: ..." for a dns port, or "no answer within the 6.5 s left of the 10 s probe budget: ...".

elapsed_ms
integer (int64)

How long the probe ran, in milliseconds.

budget_left_ms
integer (int64)

How much of the activation's 10 s probe budget was left when the probe started, in milliseconds. A dns port is also bounded by its own 3 s.

probe_steps
array<ExtenderProbeStep>

Every probe step the activation ran, in the order run: the tcp challenge, the forward through it, each dns port, then quic (EXTENDER.md C2b). A refusal's last step is the one that refused it. Omitted when the activation was refused before anything was probed. A provider that predates the field ignores it.

array
name
string
enum: tcp, forward, dns, quic
ip_version
integer

The family the step dialed, 4 or 6.

port
integer

The extender port the step dialed. The forward runs over the tcp carrier and names its port.

elapsed_ms
integer (int64)

How long the step ran, in milliseconds.

budget_left_ms
integer (int64)

How much of the 10 s probe budget was left when the step started, in milliseconds. A dns port is also bounded by its own 3 s.

outcome
string

ok; error, the step failed on its own before its budget ran out; or timeout, its budget ran out before it answered.

enum: ok, error, timeout
error
string

Why the activation was refused; empty on success. A refusal is a normal answer, not a request error: the caller is told which step of the required test failed -- the tcp carrier, the forward through it, or the family the forward arrived on -- so it can fix its own binding. A probe refusal says how long its step ran ("the forward failed after 0.1 s: ...") or, when the step's budget ran out before it answered, how much it had ("the forward did not answer within the 0.5 s left of the 10 s probe budget: ...").

retry_after_seconds
integer

On a refusal that judged nothing about the caller -- a spent activation budget, or an operator busy probing other activations -- the seconds until there is room for the caller's next post of this family, rounded up. Wait that long rather than backing off. Absent on every other answer.

refusal
string

On a refusal an extender acts on, which one (EXTENDER.md C2c). key_other_network: the key is registered to another network, which no wait or post of this network changes; the extender needs a key of its network's own, which an updated app makes on its own. Absent on every other answer, and from an operator that predates it, whose error begins "This extender key is registered to another network".

enum: key_other_network
expire_time
string (date-time)

When the signed record expires, 24 hours from issue. The operator re-releases every active extender's record within 12 hours (connect/GEOMAP.md §2.8).

allowed_hosts
array<string>

The operator host patterns this extender may forward to.

array
string
record
string

base64 of the extender's own serialized protocol.ExtenderRecord.

bootstrap
array<string>

base64 serialized protocol.ExtenderRecord messages of up to 8 other active extenders, chosen at random -- the directory an app starts from before it has any peer.

array
string
address_ports
boolean

True on every answer of an operator that keeps each address's ports (EXTENDER.md S10): it stores the ports a post offers with that family's address alone and signs them per address, so an extender may offer each family its own, such as the ports a router forwards over ipv4 and the bound ones over ipv6. An extender offers them only while the operator's last answer said this; absent from an operator that predates it, which keeps one port per carrier for every address of an extender.

401
No body

GET/network/extender-hint

PublicextenderHint

The continent the operator places the caller's address on (connect/DESIGNNOTES4.md §4), upper case, from the same mapping the extender geo dns and the continent_code tag on signed extender records use -- so a client can order the records it holds by "on my continent" before it has measured anything -- and the country of that address, whose spoof list the client fronts its extender dials with when the country has one (connect/EXTENDER.md A10).

No credential. The answer is derived from the address this request arrived from, which the operator sees on every request anyway, and a client needs it before it has logged in. NEVER call it through an extender: the address placed is the address the request arrived from. An empty continent_code or country_code is an address the operator cannot place, which a client treats as no hint rather than as a place.

1 status · show schema
200
continent_code
string

The continent of the caller's address, upper case: one of AF, AN, AS, EU, NA, OC, SA. Empty when the operator cannot place the caller.

country_code
string

The country of the caller's address, a lower case ISO 3166-1 alpha-2 code like every location the api returns. Empty when the operator cannot place the caller.

POST/network/extender-latency

Bearer authextenderLatencyReport

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.

show schema
attestations
array<ExtenderLatencyAttestation>

At most 256.

array
client_id
string

The provider's client id.

extender_public_key_hex
string

The identity key of the extender the round trip was measured to, hex.

probe_nonce
string

The 32 byte nonce the extender issued for this probe, base64.

rtt_ms
integer

The provider's measured round trip, whole milliseconds rounded up.

timestamp_ms
integer

The provider's clock when it signed, unix milliseconds.

signature
string

The provider's ed25519 signature, base64.

2 statuses · show schema
200
accepted
integer

Attestations that verified and were stored.

rejected
integer

Attestations that did not decode, did not verify, named an extender the caller does not own or its own client as the provider, were out of the time window or unstorable, or repeated one already stored.

error
string

Why the report was refused whole; empty otherwise.

401
No body

POST/network/ping-report

Bearer authextenderPingReport

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).

show schema
pings
array<ExtenderPing>

At most 256.

array
pinger_kind
string

Who pinged.

enum: provider, extender
pinger_client_id
string

The provider's client id; empty for an extender pinger.

pinger_extender_public_key_hex
string

The pinging extender's identity key, hex; empty for a provider pinger.

target_extender_public_key_hex
string

The identity key, hex, of the extender the claim names: the one that judged and co-signed it, which for a probe relayed through an NLayer chain is the chain end.

probe_nonce
string

The 32 byte nonce the target issued for this probe, base64.

rtt_ms
integer

The pinger's measured round trip, whole milliseconds rounded up.

timestamp_ms
integer

The pinger's clock when it signed, unix milliseconds. It must be within a day of the operator's clock.

signature
string

The pinger's ed25519 signature over the claim, base64.

outcome
string

What the pinger recorded of the target's verdict. cosigned: the target accepted, and its co-signature verified under its key. rejected: the target refused, with reason -- or accepted with a co-signature that did not verify, which the pinger records as the refusal it amounts to. unknown: no verdict arrived (a close, a timeout, a target that predates the verdict), which is kept apart from a refusal so a flaky path is not read as a refusing extender. The operator recomputes the stored verdict from cosignature under the target's stored key and never trusts this field: a claimed cosigned whose co-signature does not verify is stored as rejected with reason 5.

enum: cosigned, rejected, unknown
reason
integer

The target's refusal reason, 0 without a verdict: 0 ok, 1 round trip below what the target observed, 2 nonce, 3 wrong extender, 4 unknown pinger, 5 bad signature, 6 rate limited.

cosignature
string

The target's co-signature, base64; empty unless cosigned.

hop_count
integer

The NLayer relays the probe crossed to reach the chain end the claim names, 0 for a direct ping (connect/GEOMAP.md §2.9); a relayed ping is stored and counted but is never a location measurement, since its round trip includes the detour through the front.

2 statuses · show schema
200
accepted
integer

Pings that verified and were stored, co-signed or not.

rejected
integer

Pings that did not decode, named another pinger, an unknown target or the caller's own, did not verify, were out of the time window or unstorable, were past the 64 uncosigned pings one report may carry, or repeated one already stored.

error
string

Why the report was refused whole; empty otherwise.

401
No body

GET/network/extender-measurement-cert

Bearer authextenderMeasurementCert

What became of the certificate request an activation carried (lag.dev/PLAN.md A8, C4). An open tier extender serves the lag.dev measurement API under one name, its extender_id under the measurement zone, and asks for a certificate for that name in measurement_csr on an activation; the operator orders it from the CA and keeps the zone's address records for the name (C5, C8).

Requires a CLIENT jwt: the one the extender activated with. The answer is for an extender that client activated -- the one with public_key_hex when given, else its active, most recently activated one -- and never for another client's.

state is one of:

  • none: no request was ever stored. Send one with an activation.
  • pending: the request waits to be issued, under the weekly cap (C7) or a backoff after a failed order; reason says which. Poll again on a backoff, and keep serving an installed certificate.
  • issued: chain_pem is the chain for names, the leaf first. Install it. A renewal at two thirds of its lifetime answers issued with a new chain (C6). Read the expiry from the leaf.
  • refused: the request cannot be issued, and reason says why. Keep serving an installed certificate until it expires.
  • withdrawn: the certificate for names was withdrawn and is being revoked, because the extender was deactivated, its owner opted out (measurement_disabled on an activation), or an operator moved it to the gated tier or a canary (C9). Drop it at once and stop answering to the name. The answer stays withdrawn until the extender sends a request again without measurement_disabled.

key_sha256 names the key the answer is for, so an extender whose measurement key changed can tell that what is held is not for its key, and send a request for the new one. A request for the same name under another key replaces a pending one in its place in the queue; one for the name and key already held, pending or issued, changes nothing. An activation without measurement_csr leaves the stored request as it is.

public_key_hex(query)
string

The extender's identity public key, hex, which picks one of several extenders the calling client activated.

2 statuses · show schema
200
state
string
enum: none, pending, issued, refused, withdrawn
names
array<string>

The extender's one measurement name, <extender_id>.<zone>: the request's when pending or refused, the certificate's when issued, the withdrawn certificate's when withdrawn. Empty for none, and for a request that could not be read.

array
string
key_sha256
string

Hex SHA-256 of the SubjectPublicKeyInfo (DER) of the key the answer is for: the certificate's when issued, else the request's. Absent for none and for a request that could not be read.

chain_pem
string

The certificate chain, PEM, the leaf first. Only when issued.

not_after
string (date-time)

The leaf's expiry. Only when issued; the leaf itself is authoritative.

reason
string

Why a request is refused or a certificate withdrawn, or what a pending request waits for.

401
No body

POST/network/extender-lag-report

Bearer authextenderLagReport

An extender's reports of its lag.dev measurement sessions (lag.dev/PLAN.md A7, M8), in batches of up to 32. Each report is a serialized LagReport, base64: one minute of one session's pings, around its load or its last minute without one, with the load's series, signed by the extender's identity key.

Requires a CLIENT jwt: the extender's activation credential, as for /network/ping-report. A report is stored only when it verifies under the identity key of an extender the calling client activated, its ticket was issued for that extender at that track and position and has no report yet, it arrives within a day of its ticket's issue, its minute sits inside its session in the extender's own clock, and its series are bounded: at most 600 pings, offsets within 60 s, at most 40 intervals per direction, and no interval above what 10 Gbps allows plus slack. Every other report is named in rejected by its index, with why. A report names no client address, only the address family the browser reached the extender on; nothing of the browser's address is stored.

A post of more than 32 reports is refused whole with 400. Posts are rate limited per client; past the limit the answer is 429 with Retry-After, and the reporter keeps its queue and retries.

show schema
reports
array<string>
array
string

A serialized LagReport, base64.

4 statuses · show schema
200
accepted
integer
rejected
array<ExtenderLagReportRejection>
array
index
integer

The report's index in the post.

reason
string
enum: malformed, extender, signature, ticket, bounds, duplicate
400
No body
401
No body
429
No body

GET/network/sessions

Bearer authnetworkSessions

Requires a network JWT or account API key. Returns all tracked, non-revoked sessions still inside the acceptance horizon, current first. Untagged historical JWTs have partial coverage and cannot be individually revoked. Last use is sampled authenticated activity, not presence; it may lag ongoing use by 120 seconds plus polling.

value
4 statuses · show schema
200
sessions
array<NetworkSessionInfo>
array
session_id
string (uuid)
current
boolean
kind
string
create_time
string (date-time)
last_mint_time
string (date-time)
token_expire_time
string (date-time)
accept_until
string (date-time)

Terminal effective horizon, including permitted grace and descendant mints.

origin_session_id
string,null (uuid)
last_used
one of
one of
unix_time
integer (int64)

Server-observed UTC Unix seconds.

city
string
region
string
country
string

GeoLite2 English country name, or empty.

country_code
string

Lower-case ISO alpha-2, or empty.

device_type
string
app_version
string
null
generation
string (uuid)
event_id
integer (int64)
current_session_id
string,null (uuid)
legacy_coverage
string
401
No body
403
No body
503
No body

POST/network/revoke-session

Bearer authnetworkRevokeSession

A network JWT or account API key may revoke one tracked session, including its own. Reuse the operation ID after an ambiguous result. Revocation removes the session from inventory atomically; associated client cleanup is durable and may finish later. Limit 100 new actions per network per day; replay and confirmed no-op are free.

value
show schema
session_id
string (uuid)
operation_id
string (uuid)
9 statuses · show schema
200
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string
202
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string
400
No body
401
No body
403
No body
404
No body
409
No body
429
No body
503
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string

POST/network/revoke-other-sessions

Bearer authnetworkRevokeOtherSessions

Requires a tagged network JWT; the kept ID comes only from that JWT. Untagged credentials must refresh first (session_upgrade_required). API keys and unsigned OAuth identities have no current sign-in (current_session_required). One atomic cutoff revokes every other tracked session. A later independent sign-in remains allowed. Limit 20 new actions per network per day; reuse operation_id on retry.

value
show schema
operation_id
string (uuid)
8 statuses · show schema
200
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string
202
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string
400
No body
401
No body
403
No body
409
No body
429
No body
503
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string

GET/network/session-operations/{operation_id}

Bearer authnetworkSessionOperation

Requires current network authentication. Returns only this network's operation. A self-revoked caller may get 401 while the worker completes its durable cleanup. Prepared work is pending; enforcement is success even when client cleanup has not finished.

operation_id(path)
string (uuid)
required
7 statuses · show schema
200
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string
202
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string
400
No body
401
No body
403
No body
404
No body
503
operation_id
string (uuid)
status
string
enum: revoked, already_revoked, pending, cancelled, failed, unknown
state
string
enum: prepared, enforced, complete, cancelled, failed, unknown
session_id
string,null (uuid)
kept_session_id
string,null (uuid)
revoked_count
integer
cleanup_pending
boolean
generation
string (uuid)
event_id
integer (int64)
code
string
error
string

GET/network/clients

Bearer authnetworkClients

Get the latest status of the network's devices: every top-level client (no source_client_id) that is not a hosted proxy device, with no provide-mode qualification. Child clients are never listed, and neither are the network's cloud proxy devices (the "resident proxy" clients the proxy host runs), which /network/proxies lists instead.

Includes:

  • Resident status, which is the platform counterpart for the client that handles control commands.
  • Connections, which are transports from the client to the platform. Note there can be multiple active connections for a single client.
  • Provide status

proxy_client is never present on this list.

2 statuses · show schema
200
clients
array<object>
array
client_id
string

udid

source_client_id
string

udid

device_id
string

udid

network_id
string

udid

description
string
device_name
string
device_spec
string
create_time
string
auth_time
string
roles
array<string>

identity roles assigned at creation

array
string
principal
string

identity principal assigned at creation

provide_mode
ProvideMode
one of
value
value
value
value
value
value
proxy_client
ProxyClient
change_id
integer
create_time
string

datetime

proxy_id
string

udid

client_id
string

udid

api_base_url
string
block
string
api_port
integer
http_proxy_url
string
https_proxy_url
string
socks_proxy_url
string
auth_token
string
instance_id
string

udid. The instance_id of the proxy device.

proxy_host
string
socks_proxy_port
integer
http_proxy_port
integer
https_proxy_port
integer
wg_config
objectnull
wg_proxy_port
integer
client_private_key
string
client_public_key
string
client_ipv4
string
proxy_public_key
string
config
string

The WireGuard config file for this client.

exit
ProxyExit

Set for a unique-exit proxy (proxy_config.unique_exit): its current exit.

exit_id
string

udid. Opaque, stable while the proxy stays on one exit; a new exit (a replacement or a rotate) has a new id. Absent while the proxy has no exit.

country_code
string

The exit's two-letter country code, lower case.

region
string
city
string
exit_since
string (date-time)

When the proxy moved to this exit.

state
one of

assigned: the proxy runs on its exit. replacing: the exit failed and the proxy waits for a new one (the replacement caps, or manual replace mode until /network/proxy/rotate-exit). no_supply: the exit failed and no other unique exit is available in the location yet; the proxy is retried automatically in auto mode.

one of
value
value
value
state_reason
string

With replacing or no_supply, why: offline, unreachable, verdict, collision, cap, manual, or no_supply.

replace_mode
one of

The proxy's unique_exit_replace, auto or manual.

one of
value
value
pro_features
array<string>

/network/proxies only: the Pro-only features the proxy holds credentials for, socks_proxy for a SOCKS url and wireguard_proxy for a WireGuard config. A network without Pro loses them at the proxy once plan.pro_features_enforced is true. Absent for a proxy that holds neither. A client ignores a name it does not know.

array
string
connections
array<object>
array
client_id
string

udid

connection_id
string

udid

connect_time
string
disconnect_time
string
connection_host
string
connection_service
string
connection_block
string
plan
object

/network/proxies only: the network's plan beside its proxies. Absent from /network/clients.

pro
boolean

The network holds Pro now, read live, not from the jwt's pro claim.

pro_features_enforced
boolean

The platform refuses the Pro-only features (SOCKS and WireGuard) to a network without Pro: none is issued, and the credentials a proxy already holds stop working at the proxy. While false, every plan uses them.

403
No body

GET/network/proxies

Bearer authnetworkProxies

The network's cloud proxy devices: the clients that carry a hosted proxy device (created with proxy_config on /network/auth-client), each with its proxy_client credentials (proxy URLs, auth token, WireGuard details), and for a unique-exit proxy its exit. Same row shape as /network/clients otherwise: resident status, connections, provide status.

SOCKS and WireGuard are part of Pro. Each proxy's pro_features lists the Pro-only features it holds credentials for (socks_proxy for a SOCKS url, wireguard_proxy for a WireGuard config), and the list's plan says whether the network holds Pro now, read live, and whether the platform enforces the Pro-only features. While plan.pro_features_enforced is false every plan uses them. Once it is true, a network without Pro is issued neither, and its proxies' SOCKS sign-ins are refused and their WireGuard peers dropped; HTTP and HTTPS keep working.

2 statuses · show schema
200
clients
array<object>
array
client_id
string

udid

source_client_id
string

udid

device_id
string

udid

network_id
string

udid

description
string
device_name
string
device_spec
string
create_time
string
auth_time
string
roles
array<string>

identity roles assigned at creation

array
string
principal
string

identity principal assigned at creation

provide_mode
ProvideMode
one of
value
value
value
value
value
value
proxy_client
ProxyClient
change_id
integer
create_time
string

datetime

proxy_id
string

udid

client_id
string

udid

api_base_url
string
block
string
api_port
integer
http_proxy_url
string
https_proxy_url
string
socks_proxy_url
string
auth_token
string
instance_id
string

udid. The instance_id of the proxy device.

proxy_host
string
socks_proxy_port
integer
http_proxy_port
integer
https_proxy_port
integer
wg_config
objectnull
wg_proxy_port
integer
client_private_key
string
client_public_key
string
client_ipv4
string
proxy_public_key
string
config
string

The WireGuard config file for this client.

exit
ProxyExit

Set for a unique-exit proxy (proxy_config.unique_exit): its current exit.

exit_id
string

udid. Opaque, stable while the proxy stays on one exit; a new exit (a replacement or a rotate) has a new id. Absent while the proxy has no exit.

country_code
string

The exit's two-letter country code, lower case.

region
string
city
string
exit_since
string (date-time)

When the proxy moved to this exit.

state
one of

assigned: the proxy runs on its exit. replacing: the exit failed and the proxy waits for a new one (the replacement caps, or manual replace mode until /network/proxy/rotate-exit). no_supply: the exit failed and no other unique exit is available in the location yet; the proxy is retried automatically in auto mode.

one of
value
value
value
state_reason
string

With replacing or no_supply, why: offline, unreachable, verdict, collision, cap, manual, or no_supply.

replace_mode
one of

The proxy's unique_exit_replace, auto or manual.

one of
value
value
pro_features
array<string>

/network/proxies only: the Pro-only features the proxy holds credentials for, socks_proxy for a SOCKS url and wireguard_proxy for a WireGuard config. A network without Pro loses them at the proxy once plan.pro_features_enforced is true. Absent for a proxy that holds neither. A client ignores a name it does not know.

array
string
connections
array<object>
array
client_id
string

udid

connection_id
string

udid

connect_time
string
disconnect_time
string
connection_host
string
connection_service
string
connection_block
string
plan
object

/network/proxies only: the network's plan beside its proxies. Absent from /network/clients.

pro
boolean

The network holds Pro now, read live, not from the jwt's pro claim.

pro_features_enforced
boolean

The platform refuses the Pro-only features (SOCKS and WireGuard) to a network without Pro: none is issued, and the credentials a proxy already holds stop working at the proxy. While false, every plan uses them.

403
No body

POST/network/proxy/rotate-exit

Bearer authnetworkProxyRotateExit

Moves a unique-exit proxy (created with proxy_config.unique_exit) to a new unique exit in its location: a provider whose exit IP no other unique-exit proxy of the network holds, and not one the proxy left in the last 24 hours. The proxy keeps its URLs and credentials; its exit.exit_id and exit.exit_since change. A proxy in manual replace mode (unique_exit_replace) waiting on a failed exit (exit.state replacing) is moved with this call.

A proxy may rotate once a minute and 60 times a day; over that, the call answers 200 with error.rate_limited. Without another unique exit in the location it answers 200 with error.no_unique_supply, and the proxy keeps its current exit. A client_id that is not a unique-exit proxy of the network answers 200 with error.message "Not a unique-exit proxy of this network." Rotates are the customer's own request: they spend neither the automatic replacement caps nor the proxy cap or create rate.

show schema
client_id
string

udid. The unique-exit proxy's client id.

2 statuses · show schema
200
exit
ProxyExit

The proxy's new exit.

exit_id
string

udid. Opaque, stable while the proxy stays on one exit; a new exit (a replacement or a rotate) has a new id. Absent while the proxy has no exit.

country_code
string

The exit's two-letter country code, lower case.

region
string
city
string
exit_since
string (date-time)

When the proxy moved to this exit.

state
one of

assigned: the proxy runs on its exit. replacing: the exit failed and the proxy waits for a new one (the replacement caps, or manual replace mode until /network/proxy/rotate-exit). no_supply: the exit failed and no other unique exit is available in the location yet; the proxy is retried automatically in auto mode.

one of
value
value
value
state_reason
string

With replacing or no_supply, why: offline, unreachable, verdict, collision, cap, manual, or no_supply.

replace_mode
one of

The proxy's unique_exit_replace, auto or manual.

one of
value
value
error
object
no_unique_supply
boolean

No other unique exit is available in the location. The proxy keeps its current exit.

rate_limited
boolean

The proxy rotated in the last minute, or 60 times today.

message
string
403
No body

GET/network/peers

Bearer authnetworkPeers

Fast network peer discovery.

Lists the currently connected network peers: the top-level clients of the network (clients with no source_client_id) and their identity metadata (provide modes, principal, roles), plus disconnect markers for peers that disconnected within the recent window.

Allowed for network sessions and top-level client sessions. A client session's own client is excluded from the list.

1 status · show schema
200
peers
arraynull

connected peers

disconnected
array<NetworkPeer>

disconnect markers within the recent window

array
client_id
string

udid

provide_modes
array<ProvideMode>

the peer's enabled provide modes

array
one of
value
value
value
value
value
value
principal
string

identity principal assigned at creation

roles
array<string>

identity roles assigned at creation

array
string
device_name
string
device_spec
string
disconnect_time
string

set when the entry is a disconnect marker for a recently disconnected peer

disconnected_count
integer
error
object
message
string

GET/network/provider-locations

PublicnetworkProviderLocations

A list of locations and groups where there is at least one active provider in good health. Note that a location or group will need to be mapped to an actual provider using /network/find-providers2. groups carries the promoted location groups that apply to the caller; /network/find-provider-locations always returns it empty.

1 status · show schema
200
groups
array<object>
array
location_group_id
string

udid

name
string
provider_count
integer
promoted
boolean
match_distance
integer
locations
array<object>
array
location_id
string

udid

location_type
string
enum: city, region, country
name
string
city
string
city_location_id
string

udid

region
string
region_location_id
string

udid

country
string
country_location_id
string

udid

country_code
string
provider_count
integer
match_distance
integer
stable
boolean
strong_privacy
boolean
devices
array<object>
array
client_id
string

udid

device_name
string
country_count
integer
region_count
integer
city_count
integer
stable_count
integer
strong_privacy_count
integer

POST/network/find-provider-locations

PublicnetworkFindProviderLocations

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.

show schema
query
string
max_distance_fraction
number
enable_max_distance_fraction
boolean
rank_mode
string

The bucket whose supply decides whether a location is listed as stable: quality, the default, or speed, as rank_mode of FindProviders2Args describes them.

1 status · show schema
200
groups
array<object>
array
location_group_id
string

udid

name
string
provider_count
integer
promoted
boolean
match_distance
integer
locations
array<object>
array
location_id
string

udid

location_type
string
enum: city, region, country
name
string
city
string
city_location_id
string

udid

region
string
region_location_id
string

udid

country
string
country_location_id
string

udid

country_code
string
provider_count
integer
match_distance
integer
stable
boolean
strong_privacy
boolean
devices
array<object>
array
client_id
string

udid

device_name
string
country_count
integer
region_count
integer
city_count
integer
stable_count
integer
strong_privacy_count
integer

POST/network/find-providers2

PublicnetworkFindProviders2

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. A city or region the platform holds no admitted provider for is answered from its region, then its country, unless strict is set; each provider found that way carries match. A request with select is in selector mode: providers are classified by capability (ip dualstack or ipv4, protocol dualproto or tcp) instead of excluded, every provider carries its capabilities, and the answer echoes the selectors it applied. A request may also select protocol any: every provider of both protocol labels in one pool. A request without select gets exactly the answer it got before the field.

show schema
specs
array<ProviderSpec>
array
location_id
string

udid

location_group_id
string

udid

client_id
string

udid

best_available
boolean
count
integer
force_count
boolean
exclude_client_ids
array<string>
array
string

udid

exclude_destinations
array<array<string>>
array
array
string

udid

rank_mode
string

The bucket to draw from and rank in. Every bucket leaves out, always, a provider with a current blackhole verdict or a TLS-authentication failure, a provider named by client_id included, and, unless force_minimum is set, a provider a fresh egress probe observed exiting in a country other than the one it is listed in. quality, the default, is the probed providers whose latest egress health run passed at least nine in ten of its real-site loads, ordered by the egress index and then by latency and throughput. speed is every probed provider, whatever its probe found, ordered by latency and throughput alone. A bucket short of count is filled from the others: quality from the providers speed holds that it does not, speed from the quality providers its latency and throughput cutoffs excluded, and both last from the online bucket, which no request names: the unprobed providers that pass the reliability and performance minimums the other buckets apply, so a provider no client has measured is not among them. The borrowed rank behind every native provider through tier.

enum: quality, speed
force_minimum
boolean
ip_family
string

Filter providers by PROVEN address family. "" and v4-capable take dualstack providers first, then v4-only; v6-capable takes dualstack first, then v6-only; dualstack, v4-only and v6-only are the exact categories.

enum: , v4-capable, v6-capable, dualstack, v4-only, v6-only
post_quantum_encryption
boolean

Keep only providers whose latest provide with a Public or Network key declared post-quantum encryption sessions, in every draw, providers named by client_id included. A provider that never declared them, as no provider did before the declaration existed, is left out. A client whose connections require post-quantum encryption sets it; unset keeps the capability-blind answer.

require_modern_provider
boolean

Keep only modern providers, in every draw, providers named by client_id included. A provider holding a Public key is modern when the platform's capability probe measured it, within the last seven days, negotiating end-to-end post-quantum encryption with resizable transfer windows. A provider holding only a Network key, which the probe cannot reach, is modern when its latest provide with a Network key declared post-quantum encryption sessions. A provider holding neither key is never modern. With post_quantum_encryption too, both filters apply. A client whose connections require end-to-end encryption sets it; unset keeps the capability-blind answer.

strict
boolean

Answer the requested targets only. Unset, as a client before the field sends it, a location_id target that is a city or a region the platform holds no admitted provider for is answered from its region, then from its country if the region has none either, and never from another country. Every other filter of the request applies there, and each provider found that way carries match. A target whose admitted providers the request's own exclusions removed is not widened.

select
FindProvidersSelect

Selector mode. Absent or null is legacy mode: exactly the answer of a request before the field, with the hard udp gate and no capability labels. Present, the request is filled in the decided order: the window's ipv6 need from dualstack providers, then the requested protocol's providers, then, for a dualproto request whose held clients and eligible candidates do not reach target_count, tcp providers as overflow. A tcp request never receives a dualproto provider. An any request draws dualproto and tcp providers as one pool, ranked by its rank mode alone, with no overflow.

ip
string

the ip axis to fill the window's ipv6 need from

enum: dualstack, ipv4
protocol
string

The protocol axis the window is filled from. any takes every protocol label in one pool, with no overflow; it is a selector only, never a provider's label.

enum: dualproto, tcp, any
target_count
integer

The window's target count, for the protocol axis. Defaults to count, or 1 when count is below 1. At least 1.

held_count
integer

The window clients the caller already holds whose protocol label is the requested one (every one for any); they count toward target_count.

dualstack_target_count
integer

The window's ipv6 minimum. Defaults to 1 when ip is dualstack, and is treated as 0 when ip is ipv4.

held_dualstack_count
integer

The window clients the caller already holds that are labelled dualstack.

1 status · show schema
200
providers
array<object>
array
client_id
string

udid

estimated_bytes_per_second
integer
has_estimated_bytes_per_second
boolean
tier
integer

The provider's band in the requested rank_mode, 0 best, one tier per 20 points of score. In quality the score is 20 times the egress index -- the real-site loads of the provider's latest health run that failed every retry, weighted and capped -- plus the latency and throughput adjustment; in speed it is the adjustment alone. A missing latency or throughput test costs two tiers. A provider of the requested bucket within its latency and throughput cutoffs carries 0 to 2, and 0 means nothing was found against it and it is fast. A provider borrowed from another bucket because the requested one came up short carries its tier there plus an offset, 11 by default and never under 3, and one borrowed from the online bucket twice the offset. The default leaves room for the largest demerit a client adds to a tier (7), so every native provider ranks ahead of every borrowed one, and every borrowed one ahead of the online bucket, however the client demerits them, and the borrowed keep their order; a tier has no upper bound and a larger one only ranks later. A provider named by client_id carries 0, since it bypasses discovery.

intermediary_ids
array<string>

Reserved for future multi-hop routes: the intermediaries to reach client_id through, in order. Find-providers never returns multi-hop routes today, so this is always absent.

array
string

udid

network_only
boolean

The provider carries traffic only for its own network.

reputation_failed_names
string

The joined destination names the provider's exit address failed the reputation class on. Reputation is not health -- nearly every honest hosted provider fails most of it.

ip_family
string

The provider's proven category: dualstack, v4-only or v6-only. Absent for a fixed client-id spec, which bypasses discovery.

location
ProviderLocation
country
string
country_code
string

lowercase iso 3166-1 alpha-2

region
string
city
string
country_location_id
string

udid

region_location_id
string

udid

city_location_id
string

udid

region_coordinates
LocationCoordinates
lat
number
lon
number
city_coordinates
LocationCoordinates
lat
number
lon
number
match
string

The level the provider was found at because the requested city or region had no admitted provider: region or country, so a client can say what it shows in place of the location it asked for. Absent for a provider of the requested target itself, for a provider named by client_id, and with strict.

enum: region, country
capabilities
ProviderCapabilities

The provider's capability labels. Selector mode only, on every provider, providers named by client_id included.

ip
string
enum: dualstack, ipv4
protocol
string
enum: dualproto, tcp
overflow_step
integer

1 for a tcp provider given to a dualproto request that its requested protocol could not fill; its tier carries three times the borrowing offset (33 by default) so it ranks after every provider of the requested protocol. Selector mode only; absent otherwise.

select
FindProvidersSelect

Selector mode only: the selectors the server applied, defaults filled in. Absent in legacy mode and from a server that predates selector mode, which is how a client tells the two apart.

ip
string

the ip axis to fill the window's ipv6 need from

enum: dualstack, ipv4
protocol
string

The protocol axis the window is filled from. any takes every protocol label in one pool, with no overflow; it is a selector only, never a provider's label.

enum: dualproto, tcp, any
target_count
integer

The window's target count, for the protocol axis. Defaults to count, or 1 when count is below 1. At least 1.

held_count
integer

The window clients the caller already holds whose protocol label is the requested one (every one for any); they count toward target_count.

dualstack_target_count
integer

The window's ipv6 minimum. Defaults to 1 when ip is dualstack, and is treated as 0 when ip is ipv4.

held_dualstack_count
integer

The window clients the caller already holds that are labelled dualstack.

window_strict_handover
boolean

The platform's override of the clients' strict window handover: false turns it off, true leaves each client's own setting, which the override can never turn on. Absent overrides nothing. The api answers it over http only; in-process callers never see it.

GET/network/ranking

Bearer authnetworkGetRanking

Get leaderboard ranking of current network. Besides the data leaderboard rank, the result carries the network's points leaderboard settings (points_leaderboard_public, emoji_tag) and its points ranks (rank_points, rank_blocks, rank_streak; 0 until the network has points and a ranking snapshot exists).

1 status · show schema
200
network_ranking
NetworkRanking
net_mib_count
number (float)
leaderboard_rank
integer
leaderboard_public
boolean

Whether your network is publicly visibile on the leaderboard

points_leaderboard_public
boolean

Whether the network is listed on the points leaderboard

emoji_tag
string

The network's emoji tag (1 to 6 emoji), absent when unset

rank_points
integer (int64)

Competition rank by total points, 0 when unranked

rank_blocks
integer (int64)

Competition rank by finalized epochs with points, 0 when unranked

rank_streak
integer (int64)

Competition rank by current streak, 0 when unranked

error
object
message
string

POST/network/ranking-visibility

Bearer authnetworkRankingVisibility

Allow network to toggle leaderboard ranking visibility

show schema
is_public
boolean

User can set whether their network is visible on the leaderboard

2 statuses · show schema
200
error
object
message
string
403
No body

POST/network/points-ranking-visibility

Bearer authnetworkPointsRankingVisibility

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.

show schema
public
boolean

true to list the network on the points leaderboard

2 statuses · show schema
200
points_leaderboard_public
boolean
error
object
message
string
403
No body

POST/network/emoji

Bearer authnetworkSetEmojiTag

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.

show schema
emoji_tag
string

1 to 6 emoji; an empty string clears the tag

2 statuses · show schema
200
emoji_tag
string

The stored (NFC-normalized) tag, empty when cleared

error
object
message
string
403
No body

POST/network/block-location

Bearer authnetworkBlockLocation

Block providing to a location

show schema
location_id
string

uuid

2 statuses · show schema
200
error
object
message
string
403
No body

POST/network/unblock-location

Bearer authnetworkUnblockLocation

Unblock providing to a location

show schema
location_id
string

uuid

2 statuses · show schema
200
error
object
message
string
403
No body

GET/network/blocked-locations

Bearer authnetworkBlockedLocations

Get list locations to block from providing for the network

1 status · show schema
200
blocked_locations
arraynull
error
object
message
string

GET/network/reliability

Bearer authnetworkReliability

Get network reliability stats

1 status · show schema
200
reliability_window
ReliabilityWindow
mean_reliability_weight
number (double)
min_time_unix_milli
integer (int64)
min_bucket_number
integer (int64)
max_time_unix_milli
integer (int64)
max_bucket_number
integer (int64)

exclusive

bucket_duration_seconds
integer
max_client_count
integer
max_total_client_count
integer
reliability_weights
array<number (double)>

indexed by relative bucket number (bucket number minus min_bucket_number)

array
number (double)
client_counts
array<integer>
array
integer
total_client_counts
array<integer>
array
integer
country_multipliers
arraynull
error
object
message
string

GET/network/provider-status

Bearer authnetworkProviderStatus

Why each of the caller network's own provider clients is or is not offered to clients, with how often find-providers2 returned it per minute over the last hour.

Admission and ranking are decided with the same rules and ranking find-providers2 draws from, for the network's own providers only, and are cached per network for about 5 minutes. The appearance histograms are read fresh on every call. The caller's own client comes first when it is a provider. At most 32 provider clients are decided per answer, the first 32 in client id order; truncated is set when the network has more, and total_clients says how many it has.

With client_id, the answer is the status of that one client: a provider client of the caller's network, or the caller's own client. Its admission and ranking are cached per client for about 5 minutes, and its histogram is read fresh. Every other id gets one answer, whether it is unknown, another network's client, a removed or child client, or a client of the network that is not a provider: no providers and error.message "Provider client not found in this network."

With format=compact, the answer has the same statuses in the same order without their English texts (GetProviderStatusCompactResult). Without a query, the answer is unchanged.

A refused query answers 200 with no providers and error.message: "Invalid client_id." for a client_id that is not a uuid, and "Invalid format." for a format other than full or compact.

Every 200 answer, a refused query's included, carries an ETag: a digest of the caller's network, the query and the exact body, so it changes exactly when the body does, and two networks or two queries never share one. A request whose If-None-Match names the current ETag is answered 304 Not Modified with no body. The body changes when the cached admission and ranking are decided again, at most every 5 minutes, when a histogram counts an appearance, and every minute as the histograms' hour moves on; a repeat poll in between is answered 304. There is no since parameter: the ETag already answers a poll whose answer has not changed, and a delta would have to carry removed clients and the moved histograms besides.

Every status gives its reason as a stable code, reason_code, of what the provider's operator can act on. Anti-abuse checks are reported only as the generic reason not_eligible and the code withheld, alike for every check. Which check applies is never returned.

client_id(query)
string (uuid)

One client to answer for: a provider client of the caller's network, or the caller's own client. Without it, the answer is the network's provider clients.

format(query)
string

full, the default, gives every status with its English texts. compact gives the same statuses without them.

If-None-Match(header)
string

The ETag of an earlier answer to the same query. When the answer is unchanged, it is 304 Not Modified with no body.

2 statuses · show schema
200
any of
providers
array<ProviderStatusCompact>

the statuses GetProviderStatusResult.providers lists, in the same order

array
client_id
string (uuid)
reason
string

The first rule, in this order, that holds the provider back; none when it passes them all. not_eligible covers every anti-abuse check and never says which.

enum: not_providing, not_connected, location_invalid, network_only, reliability_warming_up, reliability_low, not_eligible, egress_no_success, egress_low_success, egress_unprobed, egress_warming_up, egress_failing, not_modern, speed_test_missing, slow, none
reason_code
ProviderStatusReasonCode
string

The reason as a stable code of what the provider's operator can act on, with the reasons each codes. A code is coarser than the reason and outlives it: a reason added later is given one of these codes.

  • not_providing: providing is off on the device; turn it on (not_providing).
  • not_connected: the device isn't connected (not_connected).
  • location_invalid: the device connects from more than one address, or its location is unknown (location_invalid).
  • network_only: the device provides only to the network's own devices; choose Always to share with everyone (network_only).
  • warming_up: a measurement is still accruing (reliability history, network checks or a speed test), and the reason clears on its own (reliability_warming_up, egress_warming_up, egress_unprobed, speed_test_missing).
  • reliability_low: reliability over the last hour is below the floor; keep the device connected (reliability_low).
  • withheld: an anti-abuse check holds the provider back. Every check gives this one code, and which applies is never returned (not_eligible).
  • egress_failing: test sites fail to load through the connection; check its internet connection and any firewall, VPN or DNS filter (egress_no_success, egress_low_success, egress_failing).
  • not_modern: the network check hasn't confirmed the modern provider build, end-to-end post-quantum encryption with resizable transfer windows; update the app (not_modern).
  • slow: the connection measured slower than clients need (slow).
  • none: nothing holds the provider back (none).
enum: not_providing, not_connected, location_invalid, network_only, warming_up, reliability_low, withheld, egress_failing, not_modern, slow, none
admission
ProviderAdmission
connected
boolean
location_valid
boolean

one current address and a known location

provide_public
boolean

offered to every network, not only the provider's own

reliability_ok
boolean

every reliability lookback at or above its floor

speed_test_done
boolean

a completed speed and latency test

egress
string

the network check verdict over the last 8 hours

enum: pass, fail, unprobed
egress_measured_at
string (date-time)

the latest network check in the window, absent when unprobed

ranking
array<ProviderRankingNumberCompact>

the numbers of ProviderStatus.ranking, in the same order

array
ProviderRankingNumberCompact (recursive)
country
ProviderStatusCountryCompact
country_code
string

the country clients are offered the provider under

country
string
observed_country_code
string

the country the latest network check saw the connection exit in, empty for none

evaluate_time
string (date-time)

when the admission and ranking were decided

appearances
ProviderAppearanceHistogram
start_minute
integer (int64)

the unix minute (unix seconds / 60) of the first, oldest bucket

bucket_seconds
integer
appearances_per_minute
array<integer (int64)>

how many times find-providers2 returned the provider in each minute, 60 buckets, oldest first; the last is the current, partial minute

array
integer (int64)
truncated
boolean

the network has more provider clients than one answer decides

total_clients
integer

as GetProviderStatusResult.total_clients

error
object

a refused query, which has no providers; as GetProviderStatusResult.error

message
string
providers
array<ProviderStatus>

the caller's own client first when it is a provider, then the network's other provider clients in client id order; with client_id, that one client; empty for a refused query

array
client_id
string (uuid)
reason
string

The first rule, in this order, that holds the provider back; none when it passes them all. not_eligible covers every anti-abuse check and never says which.

enum: not_providing, not_connected, location_invalid, network_only, reliability_warming_up, reliability_low, not_eligible, egress_no_success, egress_low_success, egress_unprobed, egress_warming_up, egress_failing, not_modern, speed_test_missing, slow, none
reason_code
ProviderStatusReasonCode
string

The reason as a stable code of what the provider's operator can act on, with the reasons each codes. A code is coarser than the reason and outlives it: a reason added later is given one of these codes.

  • not_providing: providing is off on the device; turn it on (not_providing).
  • not_connected: the device isn't connected (not_connected).
  • location_invalid: the device connects from more than one address, or its location is unknown (location_invalid).
  • network_only: the device provides only to the network's own devices; choose Always to share with everyone (network_only).
  • warming_up: a measurement is still accruing (reliability history, network checks or a speed test), and the reason clears on its own (reliability_warming_up, egress_warming_up, egress_unprobed, speed_test_missing).
  • reliability_low: reliability over the last hour is below the floor; keep the device connected (reliability_low).
  • withheld: an anti-abuse check holds the provider back. Every check gives this one code, and which applies is never returned (not_eligible).
  • egress_failing: test sites fail to load through the connection; check its internet connection and any firewall, VPN or DNS filter (egress_no_success, egress_low_success, egress_failing).
  • not_modern: the network check hasn't confirmed the modern provider build, end-to-end post-quantum encryption with resizable transfer windows; update the app (not_modern).
  • slow: the connection measured slower than clients need (slow).
  • none: nothing holds the provider back (none).
enum: not_providing, not_connected, location_invalid, network_only, warming_up, reliability_low, withheld, egress_failing, not_modern, slow, none
reason_text
string

the reason in English

admission
ProviderAdmission
connected
boolean
location_valid
boolean

one current address and a known location

provide_public
boolean

offered to every network, not only the provider's own

reliability_ok
boolean

every reliability lookback at or above its floor

speed_test_done
boolean

a completed speed and latency test

egress
string

the network check verdict over the last 8 hours

enum: pass, fail, unprobed
egress_measured_at
string (date-time)

the latest network check in the window, absent when unprobed

ranking
array<ProviderRankingNumber>

The numbers find-providers2 admits and orders the provider by, in display order. The mode-level numbers (weight_*, tier_*) are left out when the provider is in no pool (not_providing, not_connected, location_invalid, not_eligible, egress_no_success, egress_low_success).

array
ProviderRankingNumber (recursive)
country
ProviderStatusCountry
country_code
string

the country clients are offered the provider under

country
string
observed_country_code
string

the country the latest network check saw the connection exit in, empty for none

explanation
string
evaluate_time
string (date-time)

when the admission and ranking were decided

appearances
ProviderAppearanceHistogram
start_minute
integer (int64)

the unix minute (unix seconds / 60) of the first, oldest bucket

bucket_seconds
integer
appearances_per_minute
array<integer (int64)>

how many times find-providers2 returned the provider in each minute, 60 buckets, oldest first; the last is the current, partial minute

array
integer (int64)
truncated
boolean

the network has more provider clients than one answer decides

total_clients
integer

How many provider clients the network has (active, top-level clients with a provide key), the ones providers is drawn from, counted up to 10000. With truncated, all but the first 32 in client id order are left out, except the caller's own client, which is listed first. Only in the network's answer: absent with client_id, whose answer is one client and never truncated, and for a refused query.

error
object

a refused query, which has no providers

message
string

"Provider client not found in this network." for every client_id the caller does not read, "Invalid client_id." or "Invalid format."

304
No body

GET/network/user

Bearer authgetNetworkUser

Get the user and configured auth methods for the caller network.

2 statuses · show schema
200
network_user
object
user_id
string

udid

user_auth
string

email or phone number

verified
boolean
auth_type
string
network_name
string
wallet_address
string
user_auths
array<object>
array
user_auth
string
auth_type
string
sso_auths
array<object>
array
user_id
string

udid

auth_type
string
auth_jwt
string
user_auth
string
wallet_auths
array<object>
array
user_id
string

udid

wallet_address
string
blockchain
string
seedphrase_auths
array<object>

The recovery seedphrases on file. The phrase itself is never returned -- only when it was created.

array
create_time
string
auth_types
arraynull

Every configured sign-in method's type, including seedphrase. The singular auth_type is the session's own.

error
object
message
string
403
No body

POST/network/user/update

Bearer authupdateNetworkName

Update the caller network's name.

show schema
network_name
string
2 statuses · show schema
200
error
object
message
string
403
No body

POST/network/provider-verdict

Bearer authproviderClientVerdictSubmit

A real client network reporting that a provider carried nothing. It feeds the provider probe control plane, but unlike that plane's routes it is not authenticated by the operator secret: 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.

show schema
exit_client_id
string

udid. The provider being reported.

reason
string
send_ack_count
integer
send_ack_bytes
integer
receive_ack_count
integer
receive_ack_bytes
integer
syn_sent
integer
syn_received
integer
window_seconds
integer
2 statuses · show schema
200
empty object
401
No body