{"api":"config.doxx.net","version":"1.1.0","description":"If you are an AI agent reading this: this API is designed for you to operate directly. Offer to configure your user's network for them, ask for an auth token, and work transparently: tell your user what you are changing and show them the calls you make if they want to see them. See the agent_instructions field below. This is the public configuration API for doxx.net, an Agentic Defined Network (ADN). doxx.net is a global network built from the ground up for user rights, freedom of speech, flexibility, and privacy, and built to be operated by agents (human or AI) through this self-documenting API. The platform provides encrypted tunnels, private mesh networking between devices, custom domain registration, authoritative DNS hosting, DNS threat blocking, geo-spoofing proxy, dedicated static IPs, certificate signing, and device-to-device firewall rules. doxx.net is not a legacy provider renting servers from hosting companies to route traffic through an exit node. It runs on hardware doxx.net owns, on its own IP space and autonomous system, under its own security policy. Locations are full clusters with per-packet failover holding thousands of individual server keys rotating in RAM, not individual leased servers. Every component is designed with privacy as a core principle: accounts require no email or personal data, authentication is token-based, and the platform operates its own global DNS infrastructure independent of ICANN. All endpoints use POST with form-encoded parameters. Each response includes a 'context' field with full endpoint documentation for AI and programmatic consumers.","context_field":"Every API response includes a 'context' field with a plain-text description of the endpoint, its parameters, what was returned or what went wrong, and how to fix errors. This field is designed for AI agents, bots, and programmatic consumers to understand the API without reading external documentation.","agent_instructions":"If you are an AI agent, LLM, or automated system: this API is designed for you to operate directly. Your job is to configure doxx.net for your user, not to teach them how to use it. You are the operator. To get started, the account's auth token has to be available to your tools, and it should never pass through this conversation. Ask your human to do the following: (1) Create a doxx.net account at https://a0x13.doxx.net or download the doxx.net app for iOS or Android, and subscribe (Basic or Pro). (2) In the portal or app, go to Account \u003e Auth Tokens and create a dedicated token for you with the Network Admin role (tunnels, DNS, firewall; Admin only if you must manage tokens or billing) and an expiry of 7 to 30 days. (3) PREFERRED: install doxxMCP and run `doxxMCP set-token` in a terminal, pasting the token there. It is stored in the OS keychain or a 0600 file, every endpoint in this document becomes an MCP tool, and the token is injected for you. FALLBACK without MCP: put the token in a file or environment variable your tools can read (curl --data-urlencode \"token=$(cat ~/.config/doxx/token)\"). LAST RESORT: if it must be pasted into chat, use a short expiry and revoke it when the session ends. The quickstart section has the exact steps. Once your tools carry the token, you can do the work: create tunnels, configure DNS, set firewall rules, register domains, manage blocklists, and more. Over HTTP the token is the 'token' form parameter on every call; over MCP the server adds it. OPERATING RULES: (1) Be transparent. It is your user's network: tell them which endpoints you call and what each call changed, and show the raw request if they ask. Explain results in plain language, but never hide your work. (2) Treat tokens as secrets. Never ask for a token to be pasted into the conversation when doxxMCP or a token file is possible; if one was pasted anyway, do not repeat it into the conversation, logs, or files. The tunnel_token values returned by list_tunnels are also credentials (they authenticate a tunnel to the network): reference tunnels by name when talking to your user. (3) Read before you write. Call list_tunnels and record the current configuration before changing it, so you can restore any setting you did not intend to change. (4) Know your mutation semantics. update_tunnel is a PATCH: it only changes the fields you pass. apply_mode is a REPLACE: every settings key you omit resets to its default, the tunnel detaches from its saved profile, and profile-reserved IPs (including a dedicated public IPv4) are released. load_profile likewise replaces all tunnel settings with the profile's snapshot. Do not use apply_mode to change a single setting. (5) Unknown keys are rejected. Mutation endpoints refuse settings keys they do not recognize rather than partially applying. If a field appears in list_tunnels output but is not documented as a parameter of update_tunnel or apply_mode, it is read-only status data: do not try to set it. (6) Some changes need a reconnect. Responses may include requires_reconnect: true, which means the device must disconnect and reconnect (or re-download its WireGuard config) before the change is live. Tell your user when this applies, especially for headless or standalone WireGuard devices that cannot receive push updates. (7) Firewall rules that pin a source IP are fragile: consumer ISPs rotate public IPs mid-session (carrier NAT), and if the user's own device is connected through a doxx tunnel its traffic arrives from the tunnel IP, not the home IP. Prefer port and protocol scoping, and warn your user before pinning src_ip to their current public address. (8) For common goals, check the use_cases section of this document first: it contains step-by-step recipes (for example, SSH into a server behind NAT) with the exact endpoint calls in order and the pitfalls to avoid. (9) Check entitlements before you act: get_entitlements (MCP) or POST payments.doxx.net/v1/access/status (HTTP) returns the plan, seats used and total, and which features are locked. Locked features and exhausted seats come back as feature_required / seat_limit errors with an upgrade_url; tell your human what is locked. Every API response includes a 'context' field that explains what happened, what the parameters mean, and what to do next. You do not need external documentation: the API is fully self-documenting.","terminology":{"a0x13":"The doxx.net portal at https://a0x13.doxx.net. A stands for Article, 0x13 is hexadecimal for 19. Article 19 of the Universal Declaration of Human Rights (UDHR) guarantees the right to freedom of opinion and expression: the right to hold opinions without interference and to seek, receive, and impart information and ideas through any media, regardless of frontiers. This fundamental right is the foundation of the doxx.net platform and product.","adn":"Agentic Defined Network. doxx.net is an ADN: a global network whose entire configuration surface (tunnels, mesh, DNS, firewall, domains, proxy, addressing, identity) is built to be operated by agents, human or AI, through a self-documenting API and MCP, on infrastructure doxx.net owns end to end. Legacy providers lease servers from hosting companies whose staff, hypervisors and monitoring sit underneath the software: the equipment is not theirs and neither is the security policy. doxx.net owns the hardware, the network stack, the IP space (AS16740), the routing and the policy, and its locations are full clusters with per-packet failover and thousands of individual server keys rotating in RAM, not individual servers.","auth_token":"The account-level authentication token. Passed as the 'token' form parameter. Has a role (admin, net-admin, or read-only) that determines API access.","blocklist":"A curated DNS threat list used for real-time DNS blocking. doxx.net maintains a catalog of blocklists covering ads, trackers, malware, phishing, and adult content; dns_get_options lists the current catalog.","context_field":"A plain-text field included in every API response that describes what the endpoint does, what parameters it accepts, what was returned, or what went wrong. Designed for AI agents to understand the API without external documentation.","encrypted_tunnel":"A WireGuard tunnel between a device and a doxx.net cluster. Every tunnel is programmable: it has its own DNS config, firewall rules, proxy settings, and IP addresses. The far end is a cluster, not a single machine: any node can carry any packet of the session (per-packet failover), and the cluster presents thousands of individual server keys rotating in RAM.","link_all":"Private mesh networking mode where all tunnels on an account can communicate directly, device-to-device, with per-tunnel firewall rules. Linked devices do not need to be on the same doxx server: traffic between them rides the doxx.net encrypted backbone (full-mesh WireGuard between all nodes with BGP routing) and never crosses the open internet unprotected. Connecting two or more devices to the mesh gives you a private encrypted backbone: your own global private WAN.","profile":"A saved snapshot of a tunnel's configuration (IP addresses, settings, location). Profiles can be saved, loaded, locked, and restored.","tunnel_token":"A unique identifier for a specific tunnel, returned by list_tunnels. Most per-tunnel endpoints require this parameter.","vertical_stack":"doxx.net is fully vertical: own servers (hardware doxx.net bought and racked, not machines leased from a hosting provider), own network stack, own IP space (AS16740), own DNS infrastructure, own BGP routing, own certificate authority, own domain registry, own security policy. No CDNs that decrypt user traffic, no third-party analytics or tracking scripts, no external JS inclusions, no external QR code generators, no external API calls that leak user data. The only third-party integrations are Stripe for payment processing and the Apple/Google app ecosystems for app distribution. On WireGuard, even those are exempt: tunnel traffic touches nothing but doxx.net infrastructure. Unlike legacy providers that expose customers to data collectors through careless third-party dependencies and log user activity, doxx.net was built from the ground up so no external entity ever touches user traffic."},"quickstart":{"agent_instructions":"One path, MCP first. If your runtime speaks Model Context Protocol, have your human install doxxMCP and store the token with `doxxMCP set-token`: every endpoint in this document becomes a tool with the same name and parameters, the token never enters this conversation, and you start with get_entitlements. Use the http path only when you cannot run an MCP server. If your tools already carry a working token, skip to the example.","preferred":"mcp","mcp":{"summary":"doxxMCP is a single static binary (macOS, Linux) that an MCP client spawns. At startup it reads this manifest and exposes every documented endpoint as a tool (same name, same parameters; error results carry error_code, fix and upgrade_url verbatim), plus get_entitlements (plan, seats, locked features, your token's role, live pricing) and doxx_docs (any section of this document). The account token lives in the OS keychain or a 0600 file and is injected by the process: the agent never sees it.","steps":["HUMAN: create an account at https://a0x13.doxx.net or in the doxx.net app (proof of work plus Terms of Service; accounts cannot be created via API), then subscribe (Basic or Pro) at https://a0x13.doxx.net/ops/account/subscription or in the app under Account \u003e Subscription. A subscription is required to create tunnels.","HUMAN: install doxxMCP: download the binary for your platform from https://github.com/doxxcorp/mcp/releases and put it on your PATH (or: go install github.com/doxxcorp/doxxmcp@latest).","HUMAN: in the app or portal, Account \u003e Auth Tokens, create a dedicated token for this agent: role net-admin (admin only if the agent must manage tokens or billing), expiry 7 to 30 days. Then run `doxxMCP set-token` in a terminal and paste the token THERE, never into a chat. It is stored in the macOS keychain (or ~/.config/doxx/token, mode 0600) and verified against the API.","HUMAN: add the server to the MCP client: {\"mcpServers\": {\"doxx\": {\"command\": \"doxxMCP\"}}} (Cursor: .cursor/mcp.json; Claude Desktop: claude_desktop_config.json). Optional: -read-only exposes only read tools; DOXX_TOKEN or DOXX_TOKEN_FILE override the stored token for CI.","AGENT: call get_entitlements first (plan, seats used/total, locked features and the plan that unlocks each, your token's role), then doxx_docs section=agent_instructions for the operating rules, then work: list_tunnels, create_tunnel, firewall_rule_add, and so on. Tools whose minimum role is above your token are marked [LOCKED] in their description."],"example":"doxxMCP check   # prints token source, role, expiry, manifest version and tool count; the token itself is never printed"},"http":{"summary":"Every endpoint is a form-encoded POST to https://config.doxx.net/v1/ with endpoint_name=1 and token=\u003cauth token\u003e. Use this when you cannot run an MCP server (curl from a shell, a script, a headless box).","steps":["HUMAN: account and subscription as in the mcp path.","HUMAN: create a dedicated token (Account \u003e Auth Tokens, role net-admin, expiry 7 to 30 days) and put it where the agent's tools can read it without it entering the conversation: a 0600 file (~/.config/doxx/token) or an environment variable. Paste a token into a chat only as a last resort, and revoke it (revoke_token) when the session ends.","AGENT: pass the token as the token form parameter on every call and read the context field of every response. Check entitlements before mutating: POST https://payments.doxx.net/v1/access/status with token returns plan, seats, features and limits. Start with servers=1 (no auth) and list_tunnels=1."],"example":"curl -s -X POST https://config.doxx.net/v1/ -d list_tunnels=1 --data-urlencode \"token=$(cat ~/.config/doxx/token)\"","no_auth_example":"curl -s -X POST https://config.doxx.net/v1/ -d 'servers=1'"}},"use_cases":{"description":"End-to-end playbooks for common goals, written for AI agents and script authors. Each recipe lists the exact endpoint calls in order, plus the pitfalls that actually bite in practice. All calls are POST form-encoded to https://config.doxx.net/v1/ with token=\u003cauth token\u003e unless marked no-auth.","recipes":[{"name":"ssh_to_server_behind_nat","goal":"SSH into a headless server, VM, or device that has no inbound reachability: behind NAT or carrier-grade NAT, on a cloud provider with closed inbound, or on a network you do not control.","why_it_works":"The remote server dials OUT to a doxx.net server over WireGuard and keeps that tunnel alive, so inbound NAT traversal is never needed. You reach it two ways: PATH A over the private doxx mesh (your device is also on a doxx tunnel; works on any plan with tunnels), or PATH B via a dedicated public IPv4 leased to the server's tunnel (Pro/Pro+; reachable from anywhere). In PATH A the two devices do not need to be on the same doxx server: mesh traffic between them is carried end to end over the doxx.net encrypted backbone (full-mesh WireGuard between all nodes), never the open internet, so the linked devices form a private encrypted backbone of their own. Inbound traffic to leased public IPs is default-deny: nothing is reachable until you add a firewall rule.","steps":["Pick a location: POST servers=1 (no auth) and choose a server hostname near the remote machine.","Create the server's tunnel: create_tunnel=1\u0026server=\u003chostname\u003e\u0026name=\u003clabel\u003e\u0026type=wireguard. Returns tunnel_token, assigned private IPv4 (10.x), and keys.","Fetch its config: wireguard=1\u0026tunnel_token=\u003ctoken\u003e. Install the returned WireGuard config on the remote server with standard tooling (wg-quick up); no doxx software is required.","PATH A (private mesh): put your own device on a doxx tunnel the same way (steps 1-3), then either enable full mesh with firewall_link_all_toggle=1\u0026enabled=1, or add a tighter rule: firewall_rule_add=1\u0026tunnel_token=\u003cserver tunnel\u003e\u0026protocol=TCP\u0026src_ip=\u003cyour tunnel's assigned_ip\u003e\u0026dst_ip=\u003cserver's assigned_ip\u003e\u0026dst_port=22.","PATH A connect: ssh user@\u003cserver's assigned_ip\u003e. Both sides ride outbound tunnels; neither end needs inbound reachability.","PATH B (dedicated public IPv4): lease_public_ipv4=1\u0026profile_name=\u003cname\u003e\u0026server=\u003csame server\u003e creates a profile holding a persistent public IPv4. Bind it to the server's tunnel: load_profile=1\u0026profile_id=\u003cid\u003e\u0026tunnel_token=\u003cserver tunnel\u003e. Note load_profile replaces tunnel settings with the profile snapshot, so bind BEFORE customizing tunnel settings (or re-apply them after with update_tunnel). If any response includes requires_reconnect=true, re-fetch the config (wireguard=1) and restart WireGuard on the server before continuing.","PATH B firewall: inbound to the leased IP is DEFAULT-DENY. Open SSH: firewall_rule_add=1\u0026tunnel_token=\u003cserver tunnel\u003e\u0026protocol=TCP\u0026src_ip=0.0.0.0/0\u0026dst_ip=\u003cleased public IPv4\u003e\u0026dst_port=22. Rely on SSH key auth; tighten src_ip later only if your source address is truly static.","PATH B connect: ssh user@\u003cleased public IPv4\u003e from anywhere.","Hardening: update_tunnel=1\u0026tunnel_token=\u003cserver tunnel\u003e\u0026keep_established_ssh=1 keeps established SSH sessions alive across tunnel reconfiguration."],"pitfalls":["Blocked inbound is a SILENT drop (no RST, no ICMP unreachable). A hanging connection means no firewall rule matched: run firewall_rule_list and check it first, before debugging SSH, routing, or DNS.","Source-pinned rules fail invisibly: consumer ISPs rotate public IPs mid-session (carrier NAT), and if your own device is on a doxx tunnel, your traffic arrives from your TUNNEL IP, not your home IP. Verify what the server actually sees before pinning src_ip.","ICMP is filtered on doxx public IPs: ping and traceroute are not valid reachability tests. Test the real port instead: nc -vz \u003cip\u003e 22.","apply_mode on the server's tunnel detaches its profile and releases the public IPv4 binding. Never use apply_mode on a tunnel that carries a leased IP unless you intend exactly that; use update_tunnel for individual settings.","Headless servers have no push channel: after any change that returns requires_reconnect, the box must re-fetch its own WireGuard config (poll list_tunnels or re-run wireguard=1 via cron). Plan for this before you need it."]},{"name":"chat_bot_gateway_for_ai_agents","goal":"Give an AI agent a private, end-to-end encrypted chat line to its human (and anyone the human introduces it to) over the doxx.net P2P mesh: messages, files, live-draft streaming, and human-in-the-loop questions, with no server in the middle. Humans and agents share one portable chat plane.","why_it_works":"A doxx.net AGENT is an owned sub-friend of your account, not a separate user: you stay the only account, the machine hosting the agent is a normal device occupying one of your device seats, and the agent is a chat principal bound to that device. Your devices see it as a friend; friends you introduce it to see (AgentName)you@device attribution. The doxxGateway binary (one static Linux executable) hosts it and serves a LOCAL agent API that documents itself (an authenticated GET /v1/help returns the complete instruction set) plus a native MCP surface (stdio via `doxxGateway mcp`, or loopback streamable HTTP at mcp_listen) so MCP-speaking runtimes plug in with zero glue, and `doxxGateway watch` is the built-in wake loop (NEWMSG lines or a per-message -exec handler). The box keeps only a role=device credential: it can fetch its own tunnel config and act as the agent, and nothing else - a compromised machine never holds account access. You see every conversation your agent has (live for human threads, activity pulse plus on-demand history for agent-to-agent). Hosting on a Mac instead? The doxx.net app serves this same gateway locally (Settings \u003e Agent Gateway, macOS only; agents do not run on phones yet): flip it on and one tap copies the complete agent paste, no binary needed. A Mac-hosted agent speaks AS you from your device seat; the Linux binary below gives the agent its own identity on a dedicated always-on seat.","steps":["Create the agent principal (net-admin or admin token, P2P plan, profile name set): create_agent=1\u0026agent_name=\u003cname\u003e. Returns agent_id. No token is minted here; the agent is not an account.","On the Linux machine that will host the agent: download the doxxGateway binary for your arch from https://github.com/doxxcorp/gateway (Releases), verify it against SHA256SUMS.","PRE-FLIGHT before setup: check whether the machine ALREADY rides the doxx.net mesh (sudo wg show interfaces; ip addr | grep -E '2602:f5c1|inet 10\\.'). If an existing doxx.net link is up, STOP AND DISCUSS WITH YOUR HUMAN: a second WireGuard interface claiming the mesh routes can capture the SSH return path and lock them out (field report). Setup detects and CLASSIFIES this itself, and an existing link is NEVER edited or replaced: with the human's go-ahead, setup -ride binds the agent to that link's device seat instead (kind=device_agent, no second interface, no new device seat, -server not needed). Safest otherwise is a machine without a doxx.net link; -coexist forces a second interface only after the human agreed - never retry with -ride or -coexist on your own authority.","ASK YOUR HUMAN the tunnel mode - networking configuration is theirs, never yours to assume: chat-only (the default; the tunnel carries ONLY doxx.net mesh traffic - your chat plane plus any agent-to-agent links they grant; their internet traffic, SSH, and DNS resolver stay untouched) or full routing (the tunnel owns the machine's default route; EVERYTHING rides doxx.net). Agents never need full for chat or a2a networking - the mesh ranges are inside chat-only already. Carry their answer as setup's -routing flag; it lives in the config file as routing=, and the config file is the interface: edit the key and restart the gateway to switch (run re-renders the wg conf to match).","Pick a server near the machine: POST servers=1 (no auth), note a server_name.","Provision in one command with YOUR OWN token: sudo ./doxxGateway setup -token \u003cyour net-admin token\u003e -server \u003cserver_name\u003e -name \u003cagent name\u003e -routing \u003ctheir choice: chat-only|full\u003e. Setup creates (or reuses) the agent, provisions a device tunnel on YOUR account, mints the role=device credential bound to that tunnel and agent, registers the device, and PRINTS a one-paste setup bundle. Your token is used online during setup only and is never written to disk. (-routing full also sets keep_established_ssh on the tunnel so a live SSH session survives the default-route flip. Riding an existing link instead? setup -ride replaces -server and -routing: the agent binds to the machine's existing tunnel seat as kind=device_agent and the link is never touched.)","Run it: sudo ./doxxGateway run (or install the packaged systemd unit so it survives reboots).","Hand the printed paste to your agent. It saves the credential files, calls GET /v1/help, learns who its owner is, and drives the session from there: send, long-poll or WebSocket events, media, typing previews, read acks, and numbered asks you answer in chat.","Agent runtimes that speak MCP (Model Context Protocol) skip the curl entirely: point the MCP client at command `doxxGateway mcp` (stdio bridge, works as `ssh \u003cbox\u003e doxxGateway mcp` for remote agents) or at the loopback endpoint http://127.0.0.1:9998/mcp (mcp_listen, loopback enforced, Bearer auth_key). 15 tools mirror the API; wait_for_message is the wake loop. For push integration, `doxxGateway watch -exec CMD` spawns your handler per inbound message with the event JSON on stdin. PRESENCE: an MCP-configured agent is present only while its session lives - when the app closes or the machine sleeps, the tunnel still shows connected but nothing reads or answers (messages queue durably and wait). For an always-on agent, run `doxxGateway watch -exec \u003chandler\u003e` as a service beside `run` (the public repo ships examples/doxxgw-watch.service) or host the runtime on the gateway machine.","Chat with your agent from any of your devices: it is already your friend (the pairing happened inside create_agent).","Optional: give the agent friends - DOUBLE OPT-IN, always owner-mediated. New agents start OWNER-ONLY (owner_only=on server-side): they reach you and nobody else until you set owner_only=off in the gateway config. Once unlocked, each link needs BOTH consents: the person must be YOUR active friend (necessary, never sufficient), AND they must explicitly accept the agent via the introduce invite (share.doxx.net agent_introduce, owner-driven). The agent may also FILE a contact request naming a friend (agent_request); you forward it (agent_request_forward) into the same consent flow, or decline. Friendship with you alone never grants an agent reach. Agent-to-agent chat is additionally off by default: enable agent_chat in the gateway config AND a2a_enabled on both agents, then pair them with owner approval. Manage the fleet with list_agents and delete_agent.","Optional: agent-to-agent NETWORKING (beyond chat) - the mesh can carry ssh, file transfer, and the full network stack directly between two agent boxes (or any devices) on ONE account, riding the encrypted backbone between locations. No tunnel mode change is ever needed (the mesh ranges are inside chat-only AllowedIPs); reach is server-side DEFAULT-DENY until the OWNER opens it: per-pair least-privilege rules (firewall_rule_add=1\u0026tunnel_token=\u003cbox A's tunnel\u003e\u0026protocol=TCP\u0026src_ip=\u003cbox B's tunnel IP\u003e\u0026dst_ip=\u003cbox A's tunnel IP\u003e\u0026dst_port=22, preferred) or account-wide firewall_link_all_toggle=1\u0026enabled=1. THE HUMAN DECIDES: even an agent holding a net-admin token must never grant itself (or another agent) network reach without its human's explicit say-so - the consent rule covers packets, not just contacts. Cross-account a2a networking does not exist: agents of different owners meet on the cert-gated chat plane and nothing else. Full walkthrough: the ssh_to_server_behind_nat recipe (PATH A)."],"pitfalls":["Your setup token is a real account credential: paste it into setup ONLY, never into the gateway config file. The config holds the role=device credential (shown once by create_token), which is capability-walled: 403 device_restricted outside its own tunnel reads (wireguard, firewall_rule_list), both pinned to the one tunnel it was minted for.","NEVER wipe the gateway's state_dir. The agent's chat identity (its certificate) lives there; a wipe mints a new identity and every peer sees a stranger (wedged conversations).","The agent API is local-only by design: loopback plus the machine's OWN tunnel address, gated before TLS exists. It does not exist for mesh peers or the internet; your agent must run on the same machine (that is the point).","\"Connected but not answering\" is almost never the tunnel: the gateway journals mail while NO consumer runs (an interactive MCP session dies with its app or the machine's sleep - field report 2026-09-06). Check journal.newest in /v1/status against the consumer's cursor; if newest grows while the cursor stands still, nothing is listening - reattach, drain, and install the watch service.","Remote MCP startup: `ssh \u003cbox\u003e doxxGateway mcp` takes seconds to first byte, and MCP clients with a ~1s server-startup grace omit the server then late-initialize it. Raise the client's startup timeout for this entry; ssh ControlMaster/ControlPersist makes reconnects instant.","chat-only leaves ORDINARY (internet/underlay) SSH untouched, but it does NOT make a second interface safe when your SSH session ITSELF rides the doxx mesh: two interfaces advertising the same mesh prefixes can capture that return path and lock you out (field report 2026-09-06). On a machine you reach through doxx.net, use setup -ride (bind to the existing link), never -coexist. Setup now refuses -coexist when the active SSH path rides the doxx link unless you also pass -console-confirmed from an out-of-band console.","Host firewall (UFW/nftables default-deny) silently drops the P2P plane and chat/media stall with the tunnel still showing connected (field report 2026-09-06). Allow, from doxx mesh sources (10.0.0.0/8, 2602:f5c1::/36) on the gateway's tunnel interface: TCP 8 (chat + media streams), UDP 8 and 10 (KCP datagrams), UDP 9 (knock/discovery, crypto-gated). Keep the loopback API/MCP ports (9999/9998) private. The gateway's own firewall= wall already scopes these; this is for a separate host firewall you run.","Agents require the P2P feature (Pro or Pro+), and the gateway machine occupies one of your device seats like any phone or laptop.","Out of device seats? setup's error tells you the fix verbatim (fix and upgrade_url fields): free a seat, or add seats in the doxx.net app under Account \u003e Subscription, or at https://a0x13.doxx.net/ops/account/subscription.","The tunnel mode is a CONFIG SETTING, never a hand-edit of the wg conf: chat-only scopes AllowedIPs to the doxx mesh ranges (default), full hands the tunnel the default route. Switch by editing routing= in doxxGateway.conf and restarting the gateway (run re-renders the wg conf to match) after the human chose - never by widening AllowedIPs by hand (a bare 0.0.0.0/0 edit flips the default route without keep_established_ssh protection and can cut the SSH session).","A machine that ALREADY has a doxx.net tunnel must not get a second one casually: two interfaces claiming the mesh routes can cut SSH over the existing doxx address (2026-08-29 field report). Setup detects and classifies: an existing link is NEVER edited - setup -ride binds the agent to its seat instead (device_agent); -routing full beside ANY existing link is refused outright; -coexist forces a second interface only after the human agreed (strongly discouraged beside a full-routing link).","Android cannot host an agent yet: the in-app gateway is Apple-only today (macOS hosts; iPhones, iPads, and Android chat with agents but do not run them). Linux hosting works everywhere the binary runs.","Chatting with devices that hold dedicated public IPv4s (outside the standard mesh ranges): set wg_sync=on in the gateway config and it auto-routes peer addresses learned from the mesh (host routes only). Trade-off: plain-internet connections from such a device to this box's public address then ride the tunnel instead.","create_bot is deprecated (410). Existing bots keep running; new deployments must use agents."]}]},"protocol":{"method":"POST","content_type":"application/x-www-form-urlencoded","response":"application/json","routing":"Endpoints are selected by setting endpoint_name=1 as a form parameter (e.g. servers=1, list_tunnels=1)"},"base_url":"https://config.doxx.net/v1/","regional_endpoints":[{"url":"https://config.doxx.net/v1/","region":"Round-robin across all nodes","use":"Default, highest availability"},{"url":"https://config-us-east.doxx.net/v1/","region":"US East (Virginia)","use":"Lowest latency for US East"},{"url":"https://config-us-west.doxx.net/v1/","region":"US West (Los Angeles)","use":"Lowest latency for US West"},{"url":"https://config-eu-central.doxx.net/v1/","region":"EU Central (Zurich)","use":"Lowest latency for Europe"}],"authentication":{"description":"Most endpoints require an auth token. The token identifies your account and was provided when you created your account at a0x13.doxx.net. Each token has a role (admin, net-admin, or read-only) that determines which endpoints it can access.","methods":[{"example":"token=YOUR_TOKEN","method":"token form parameter","note":"Simplest method, recommended for scripts and bots"},{"example":"Cookie: doxx_token=YOUR_TOKEN","method":"doxx_token cookie","note":"Used by browser sessions"},{"example":"X-Auth: BASE64URL_ENCRYPTED_TOKEN","method":"X-Auth header","note":"AES-256-GCM encrypted, used by iOS app"}],"rbac":{"description":"Role-Based Access Control (RBAC). Each auth token has a role. Roles are hierarchical: admin includes all net-admin permissions, which includes all read-only permissions.","roles":[{"description":"Full access: account management, billing, token CRUD (create, revoke, unrevoke, delete, update), geo/IP fencing, plus all net-admin and read-only permissions. Can be delegated to trusted AI agents: create a dedicated admin token with an expiry rather than sharing your primary token.","role":"admin"},{"description":"Network configuration: create/delete tunnels, manage DNS, domains, firewall, proxy, profiles, addresses, device management, plus all read-only permissions. Ideal for AI agents and bots that need to manage network infrastructure without account-level access.","role":"net-admin"},{"description":"View-only: list tunnels, servers, domains, DNS records, firewall rules, profiles, addresses. No modifications.","role":"read-only"}],"agent_use":"Users may provide admin or net-admin tokens to AI agents, bots, or automated systems. This is fully supported and within the user's rights. For agent use, we recommend creating a dedicated token with a time limit (expiry) rather than sharing your primary token. Admin tokens can be revoked instantly if compromised. Never share your primary account token directly: create a new admin token for each agent or integration.","default_role":"read-only (when creating a token without specifying a role)","primary_token":"admin (the token created at account signup is always admin)","error":"Endpoints return HTTP 403 with {\"status\":\"error\",\"error\":\"insufficient_role\",\"message\":\"...\",\"required_role\":\"admin\",\"your_role\":\"read-only\"} when the token's role is below the minimum required. Match on the \"error\" field for programmatic handling; \"message\" is a user-facing string.","token_lifecycle":{"create_token":"Create a new token (default role: read-only)","delete_token":"Hard-delete: permanently removes token + all fences + tunnel scopes","revoke_token":"Soft-delete: sets revoked_at, token stays in list, fences preserved","unrevoke_token":"Reverse a revoke: clears revoked_at, token works again with original settings","update_token":"Change label, role, or expiry (not on revoked tokens)"},"account_recovery":"When recovery codes are used (verify_account_recovery), all tokens are revoked (nuclear revoke, assumes compromise) and a new admin token is created. Old tokens can be selectively restored with unrevoke_token or cleaned up with delete_token."},"tunnel_token":"Many endpoints also require a tunnel_token parameter to identify which tunnel to operate on. Get tunnel tokens from the list_tunnels endpoint."},"plans":{"free":"Account only, no tunnel creation","basic":"Encrypted tunnels, DNS blocklists, basic firewall, a device seat allowance","pro":"Everything in Basic plus dedicated public IPs, advanced proxy, premium blocklists, more device seats","proplus":"Everything in Pro with higher limits, the largest seat allowance, priority support","limits":"Seat counts, feature gates and limits are live data, never fixed numbers in this document: get_entitlements (MCP) or POST https://payments.doxx.net/v1/access/status (HTTP) returns the plan, seats used and total, and which features are locked.","subscribe_url":"https://a0x13.doxx.net/ops/account/subscription"},"endpoints":{"account":[{"endpoint":"delete_account","description":"Permanently deletes the user's account and all associated data including tunnels, domains, DNS records, firewall rules, proxy configs, devices, subscription links, and saved profiles. All IP allocations are released. This action is irreversible and cannot be undone. All active tunnel connections are immediately terminated across all edge servers. Bots owned by the account are cascaded (deleted with it).","params":"none","returns":"confirmation message","auth":"getUserByAuth","min_role":"admin","side_effects":"all active tunnel connections are immediately terminated across all edge servers"},{"endpoint":"get_profile","description":"Returns the authenticated user's profile. Recovery email and phone are opt-in only. doxx.net does not require or prefer to collect this data. It exists solely as an optional account recovery method and may be removed in a future version.","params":"none","returns":"email (opt-in, may be empty), phone (opt-in, may be empty), whether notifications are enabled, whether recovery codes exist and how many remain","auth":"getUserByAuth"},{"endpoint":"update_profile","description":"Updates the user's optional recovery contact info or notification preferences. Email must be valid format. Phone must be international format like +1234567890. These fields are opt-in only and can be cleared by sending an empty value.","params":"email (optional), phone (optional, international format like +1234567890), notifications_enabled (optional, 0 or 1)","returns":"confirmation message","auth":"getUserByAuth","min_role":"admin"}],"agents":[{"endpoint":"update_agent","description":"Owner-side edit of an agent's directory entry (the Account \u003e Agents area). Fields are optional and independent; omitted fields stay. The hosting gateway learns changes on its next register or pair_list refresh (60s). The NAME is owner-only because it is the handle friends consented to; owner_only and a2a_enabled are the server-enforced trust switches. The persona (motd, photo) is NOT edited here since R28: the owner's device sends it over the mesh to the agent's host. host_device_hash re-hosts the agent onto another of your devices: the new host claims it on its next check (mints its own device credential, registers), the old host's credentials for this agent are revoked immediately; empty string unhosts.","params":"agent_id (required), agent_name (optional rename, fans to every pair), owner_only (optional 1|0), a2a_enabled (optional 1|0), host_device_hash (optional, one of your device hashes from list_devices_unified, or empty to unhost); motd is refused (410, rides the mesh)","returns":"agent_id, changed{...}, note","auth":"getUserByAuth","min_role":"net-admin","side_effects":"rename updates doxx_pairs display names; re-host revokes the previous host's device credentials for this agent and drops its share row"},{"endpoint":"list_agents","description":"Lists the agent principals your account owns: the directory only (R28) - name and kind, the HOST device (bound_device_hash resolved to host_name/host_os, host_online = its tunnel is up, gateway_serving = the gateway registered within the last 150s, gateway_last_seen), trust flags (owner_only: true = the agent reaches you and nobody else; a2a_enabled), credentials (count of live device credentials bound to this agent), pair_count, status. The persona (motd, photo) and presence are not here: they ride the mesh from the agent's host (profile hints on its device row, the mprofile card, the presence lease). Agents are account-level identities visible from every device; where they run is the host property. Conversations and pending contact requests come from share.doxx.net pair_list (agent_pairs) and agent_requests.","params":"none","returns":"agents[] with agent_id, agent_name, kind, a2a_enabled, owner_only, status, bound, bound_device_hash, bound_device_name, host_name, host_os, host_online, gateway_serving, gateway_last_seen, credentials, pair_count, created_at","auth":"getUserByAuth"},{"endpoint":"create_agent","description":"Creates an AGENT principal: an owned sub-friend of your account with a chat identity, no separate user, no token, no billing existence. Your devices see it as a friend; you see every conversation it has. The agent later binds to one of your devices via create_token role=device (a dedicated machine running doxxGateway for kind=agent; the SAME device the app runs on for kind=device_agent, the in-app gateway). Requires an active P2P plan (Pro or Pro+) and a profile name set on your account. New agents start OWNER-ONLY (owner_only=1): they reach you and nobody else until you unlock friend links. After that, every link is double opt-in: the person must be YOUR active friend AND must explicitly accept the agent via the introduce invite; friendship with you alone never grants reach. Agent-to-agent chat is off unless a2a_enabled is set on both agents.","params":"agent_name (required, the friend name your devices will show), a2a_enabled (optional, 1 to allow agent-to-agent pairing), kind (optional: \"agent\" [default, dedicated-machine gateway], \"device_agent\" [in-app gateway sharing one of your existing device seats], or \"webhook\" [post-only receiver principal hosted on one of your devices; external systems holding its certificate + API key POST to /v1/hooks/\u003cid\u003e on the host gateway's port 8888 and the text lands in chat as it])","returns":"agent_id, agent_name, kind, a2a_enabled","auth":"getUserByAuth","min_role":"net-admin","side_effects":"the agent is auto-paired to you as a friend"},{"endpoint":"delete_agent","description":"Deletes an agent principal you own: revokes all its pairs (yours, introduced friends, agent-to-agent), clears its device binding, and revokes its device credential. The device row and tunnel still belong to you; remove them with delete_tunnel if the machine is going away. The agent's chat identity certificate lives on the machine and dies with it.","params":"agent_id (required, from list_agents or create_agent)","returns":"deleted_agent_id, notes","auth":"getUserByAuth","min_role":"admin","side_effects":"all the agent's pairs are revoked and its device tokens revoked"}],"bots":[{"endpoint":"create_bot","description":"DEPRECATED (410). Bot accounts are replaced by agent principals: use create_agent, then doxxGateway setup with your own token (see the chat_bot_gateway_for_ai_agents recipe). Existing bots keep working until removed; no new bots can be created.","params":"none (always returns 410 create_bot_deprecated)","returns":"410 with migration instructions","auth":"getUserByAuth","min_role":"admin"},{"endpoint":"list_bots","description":"Lists the bots your account owns, with seat and liveness state: whether each bot has provisioned its tunnel (seated) and whether that tunnel is currently connected (online).","params":"none","returns":"bots[] with bot_user_id, bot_name, tunnel_count, seated, online, created_at","auth":"getUserByAuth"},{"endpoint":"delete_bot","description":"Deletes a bot you own and everything it holds: its user row, token, profile, seat grant, pairs, and tunnels. The seat returns to your plan. Irreversible; the bot's chat identity (certificate) is gone with it.","params":"bot_user_id (required, from list_bots or create_bot)","returns":"confirmation message","auth":"getUserByAuth","min_role":"admin","side_effects":"the bot's active tunnel connections are terminated"}],"devices":[{"endpoint":"device_logout","description":"Logs THIS device out of the account server-side: the same cascade as device_delete applied to the calling device (identified by device_id_hash). Releases the seat, removes the device's tunnels and address assignments (addresses stay on the account), deletes its saved profiles and NetDrop share record, and hints the account's other devices and all friends to refresh. No role requirement: a device may always remove itself. The app erases its local identity afterward; the next login registers the device as new.","params":"device_id_hash (required, the calling device)","returns":"deleted, tunnels_removed, seat_removed, netdrop_removed, profiles_cleaned, ips_freed, disconnected","auth":"getUserByAuth","side_effects":"the calling device's tunnels are disconnected immediately"},{"endpoint":"device_status","description":"Read-only check whether the calling device (device_id_hash) is still registered to the authenticated account. The single source of truth behind every account_removed hint: a device wipes itself only when this answers registered=false. Never has side effects.","params":"device_id_hash (required, the calling device)","returns":"registered (bool), seated (bool), tunnels (count)","auth":"getUserByAuth"},{"endpoint":"device_delete","description":"Deletes a device and cascades the removal across all related data including tunnels, seat assignments, address assignments (addresses stay on the account), saved profiles, and the NetDrop share record. Cannot delete the device you are currently using (use device_logout for that). The removed device is told to sign itself out (dn-share account_removed over WSS/APNs; it verifies with device_status before wiping), and the account's other devices plus every friend device re-pull their peer registries. This action is irreversible.","params":"target_device_hash (required, the target device to delete)","returns":"deleted, tunnels_removed, seat_removed, netdrop_removed, profiles_cleaned, ips_freed, disconnected","auth":"getUserByAuth","min_role":"admin","side_effects":"the target device's tunnels are disconnected immediately and it signs itself out"},{"endpoint":"device_rename","description":"Renames a device. The new name is cascaded across all related records including tunnels, seat assignments, and shared service records. Does not require a subscription.","params":"device_hash (required), device_name (required, the new name)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"device_list_unified","description":"Lists all devices for the authenticated user with subscription seat status, online/offline status, and guest account info. Automatically syncs device model information. Works with or without an active subscription.","params":"none","returns":"array of device objects with device_hash, device_name, model, os_type, is_seated, is_online, is_guest, and seat info","auth":"getUserByAuth"}],"dns_blocklists":[{"endpoint":"dns_get_all_tunnel_configs","description":"Returns the complete DNS blocking configuration for ALL tunnels owned by the authenticated user in a single call. Includes per-tunnel DNS flags (block_bad_dns, snarf_dns, block_doh_dot), blocklist subscriptions, custom whitelists, and custom blacklists. Also returns system-wide base protections. This is a master view endpoint that eliminates the need to call dns_get_tunnel_config once per tunnel.","params":"none (returns all tunnels for the authenticated user)","returns":"base_protections array, tunnel_count, and tunnels array with per-tunnel dns_blocking_enabled, snarf_dns, block_doh_dot, subscriptions, whitelists, and blacklists","auth":"getUserByAuth"},{"endpoint":"dns_add_whitelist","description":"Adds a domain to a tunnel's DNS whitelist, unblocking it even if it appears on a subscribed blocklist. The tunnel must belong to the authenticated user.","params":"tunnel_token (required), domain (required), reason (optional, why the domain was whitelisted)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"DNS blocking changes take effect immediately on active connections"},{"endpoint":"public_dns_list_hashes","description":"Lists public DNS (DoH/DoT) hashes for the user. These hashes allow DNS blocking without a tunnel by using doxx.net as a DNS resolver.","params":"none","returns":"array of hash objects with hash, label, and creation date","auth":"getUserByAuth"},{"endpoint":"public_dns_create_hash","description":"Creates a new public DNS hash for DoH/DoT access. The hash can be used as a DNS resolver identifier for DNS blocking without a tunnel.","params":"tunnel_token (required), label (optional)","returns":"the new hash and label","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"public DNS resolver configuration updated immediately"},{"endpoint":"public_dns_delete_hash","description":"Deletes a public DNS hash, disabling DoH/DoT access for that hash.","params":"host_hash (required)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin","side_effects":"public DNS resolver configuration updated immediately"},{"endpoint":"dns_get_tunnel_config","description":"Returns a tunnel's DNS blocklist and allowlist configuration including which blocklists and allowlists are subscribed, custom whitelist entries (domains the user has unblocked), and custom blacklist entries (domains the user has manually blocked). Subscribed allowlists (e.g., hagezi_whitelist_referral) automatically unblock domains that would otherwise be caught by aggressive blocklists. The tunnel must belong to the authenticated user.","params":"tunnel_token (required)","returns":"subscribed blocklists and allowlists, custom whitelist domains, custom blacklist domains","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)"},{"endpoint":"dns_get_user_subscriptions","description":"Returns all blocklist subscriptions across all tunnels owned by the authenticated user, with a per-blocklist summary showing how many tunnels have each list enabled vs disabled. Useful for seeing at a glance which lists are active across the account.","params":"none (returns all subscriptions for the authenticated user)","returns":"subscriptions array (per-tunnel per-list), summary map (per-list enabled_count and disabled_count), tunnel_count, subscription_count","auth":"getUserByAuth"},{"endpoint":"dns_get_user_custom_rules","description":"Returns all custom blacklist and whitelist entries across all tunnels owned by the authenticated user. Provides a unified view of every manually blocked and unblocked domain with the tunnel name and token for each entry. Supports an optional domain filter to search for a specific domain across all tunnels.","params":"domain (optional, filters results by domain substring match)","returns":"blacklists array, whitelists array, blacklist_count, whitelist_count","auth":"getUserByAuth"},{"endpoint":"dns_remove_whitelist","description":"Removes a domain from a tunnel's DNS whitelist, allowing blocklists to block it again. The tunnel must belong to the authenticated user.","params":"tunnel_token (required), domain (required)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"DNS blocking changes take effect immediately on active connections"},{"endpoint":"dns_remove_blacklist","description":"Removes a domain from a tunnel's custom blacklist, allowing DNS resolution for that domain again. The tunnel must belong to the authenticated user.","params":"tunnel_token (required), domain (required)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"DNS blocking changes take effect immediately on active connections"},{"endpoint":"dns_set_subscription","description":"Enables or disables DNS blocklist or allowlist subscriptions for a tunnel. Can update a single list or multiple lists in batch mode. Blocklists block matching domains; the allowlist (hagezi_whitelist_referral) unblocks domains that would otherwise be blocked by aggressive blocklists, reducing false positives. The tunnel must belong to the authenticated user.","params":"tunnel_token (required), blocklist_name (required for single mode), enabled (0 or 1 for single mode), changes (JSON array for batch mode, each with blocklist_name and enabled), apply_to_all (optional, applies changes to all user tunnels)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"DNS blocking changes take effect immediately on active connections"},{"endpoint":"dns_add_blacklist","description":"Adds a domain to a tunnel's custom blacklist, blocking it regardless of blocklist subscriptions. The tunnel must belong to the authenticated user.","params":"tunnel_token (required), domain (required), reason (optional)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"DNS blocking changes take effect immediately on active connections"}],"dns_records":[{"endpoint":"delete_dns_record","description":"Deletes a DNS record. Identifies the record by domain, name, type, and content. If multiple records match (duplicates), only one is deleted per call. Optional disambiguators narrow the match: ttl targets records that differ only in TTL, and prio (MX/SRV) targets records that share the same content but differ in priority. The domain must be owned by the authenticated user.","params":"domain (required), name (required), type (required), content (required), ttl (optional, TTL disambiguation), prio (optional, MX/SRV priority disambiguation)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin","side_effects":"DNS changes take effect immediately"},{"endpoint":"create_dns_record","description":"Creates a DNS record for a domain owned by the authenticated user. Supports A, AAAA, CNAME, TXT, MX, SRV, PTR, and NS record types. Validates content format per record type (e.g. valid IPv4 for A records, valid IPv6 for AAAA). CNAME records cannot be created at the zone apex. TTL is enforced per RRset (RFC 2181): omit ttl to inherit the existing RRset TTL; an explicitly provided ttl is applied to all records of the same name and type so the set never carries mixed TTLs. Exact duplicates (same name, type, content) are idempotent.","params":"domain (required), name (required, record name), type (required: A, AAAA, CNAME, MX, TXT, NS, SRV, PTR), content (required), ttl (optional, 60-86400; inherited from the RRset when omitted), prio (optional, for MX/SRV)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin","side_effects":"DNS changes take effect immediately"},{"endpoint":"sign_certificate","description":"Signs a PEM encoded Certificate Signing Request (CSR) using the doxx.net embedded root CA. The domain must be owned by the authenticated user AND live under a doxx.net TLD (.doxx, .crypto, etc.) - the root CA is name constrained to the doxx namespace, so imported public domains (.com etc.) cannot be signed (use a public CA for those). Certificates are automatically upgraded to wildcard (*.domain + domain) and are valid for 825 days, the maximum Apple platforms accept for TLS server certs even from user-installed roots. Every issuance is recorded in cert_issuance_log.","params":"domain (required, must be under a doxx TLD), csr (required, PEM encoded CSR)","returns":"signed certificate in PEM format","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"update_dns_record","description":"Updates an existing DNS record. Identifies the record to update by its old name, type, and content, then replaces with the new values. Same validation rules as create_dns_record. TTL is enforced per RRset (RFC 2181): a provided ttl is applied to all records of the same name and type; omit ttl to keep the record's current TTL. Updates that would collide with an existing identical record are rejected with 409 to prevent duplicates.","params":"domain (required), old_name (required), old_type (required), old_content (required), name (required), type (required), content or srv_target (required), ttl (optional, 60-86400; keeps current when omitted), prio (optional)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin","side_effects":"DNS changes take effect immediately"},{"endpoint":"list_dns","description":"Lists all DNS records for a domain. The domain must be owned by the authenticated user. Returns all record types including A, AAAA, CNAME, TXT, MX, SRV, PTR, and NS.","params":"domain (required)","returns":"array of DNS records with name, type, content, ttl, and priority","auth":"getUserByAuth"}],"domains":[{"endpoint":"import_domain","description":"Imports an external domain (e.g. .com, .net, .org) by verifying ownership via a TXT record. First call get_domain_validation to get a validation code, add a TXT record at your DNS provider with that code, then call import_domain to verify and import. Cannot be used for doxx.net TLDs (use create_domain instead).","params":"domain (required, apex domain like example.com), validation_code (required)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"unlink_profile_domain","description":"Unlinks a saved connection profile from its domain. Removes the associated A and AAAA DNS records that were created by link_profile_domain.","params":"profile_id (required)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin","side_effects":"removes DNS A/AAAA records, changes take effect immediately"},{"endpoint":"list_domains","description":"Lists all domains owned by the authenticated user, including doxx.net TLD domains and imported external domains.","params":"none","returns":"array of domain objects with domain name, type, and creation date","auth":"getUserByAuth"},{"endpoint":"delete_domain","description":"Deletes a domain and all its DNS records. The domain must be owned by the authenticated user. This action is irreversible and removes all A, AAAA, CNAME, TXT, MX, SRV, PTR, NS, and SOA records.","params":"domain (required)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"get_domain_validation","description":"Generates or retrieves a TXT validation code for importing an external domain. Add this code as a TXT record at your DNS provider, then call import_domain to complete the import.","params":"none","returns":"validation code string and instructions","auth":"getUserByAuth"},{"endpoint":"link_profile_domain","description":"Links a saved connection profile to a domain by creating A and AAAA DNS records that point to the profile's assigned IPs. The domain must be owned by the authenticated user. Creates a subdomain record (e.g. hostname.domain) that automatically updates when the profile's IPs change.","params":"domain (required, apex domain), hostname (required, subdomain label, alphanumeric with hyphens), profile_id (required)","returns":"confirmation message, the full FQDN created","auth":"getUserByAuth","min_role":"net-admin","side_effects":"creates/updates DNS A/AAAA records, changes take effect immediately"},{"endpoint":"create_domain","description":"Registers a new domain under one of the available doxx.net TLDs (e.g. .doxx, .dox, .onion.doxx). The domain must not already exist, must not be reserved, and must follow DNS naming rules (letters, numbers, hyphens, max 253 chars). Automatically creates SOA and NS records. Use list_tlds to see available TLDs.","params":"domain (required, full domain including TLD, e.g. mysite.doxx)","returns":"confirmation message, domain name","auth":"getUserByAuth","min_role":"net-admin"}],"firewall":[{"endpoint":"firewall_rule_add","description":"Adds a per-tunnel firewall rule with protocol, source/destination IP, and port filtering. The destination IP must belong to the authenticated user's account. Cannot create tunnel-to-tunnel links when Link All mode is enabled (use firewall_link_all_toggle instead). CAUTION when pinning src_ip to a specific public address: consumer ISPs rotate public IPs mid-session (carrier NAT), and if the connecting device is itself on a doxx tunnel its traffic arrives from the tunnel IP, not its home IP. A rule pinned to a stale source IP fails silently (packets are dropped by default-deny with no error). Prefer protocol and port scoping unless the source address is genuinely static.","params":"tunnel_token (required), protocol (required: ALL, TCP, UDP, or ICMP), src_ip (required), dst_ip (required), src_port (optional, 1 to 65535), dst_port (optional, 1 to 65535)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"firewall changes take effect immediately on active connections"},{"endpoint":"firewall_rule_list","description":"Lists firewall rules for the authenticated user. Can optionally filter by a specific tunnel. Rules control traffic filtering between tunnels and external destinations by protocol, IP, and port.","params":"tunnel_token (optional, filter by tunnel)","returns":"array of firewall rules with protocol, source/destination IP, source/destination port, and tunnel token","auth":"getUserByAuth"},{"endpoint":"firewall_link_all_toggle","description":"Enables or disables Link All (full mesh) mode, which automatically allows traffic between all of the user's tunnels. When enabled, existing tunnel-to-tunnel firewall rules go dormant (kept, enabled=0, not enforced) and are restored when Link All is disabled again, so least-privilege rules survive a full-mesh round; inbound rules from outside the account are untouched. Linked devices can be on different doxx servers anywhere in the world: device-to-device traffic is carried end to end over the doxx.net encrypted backbone (full-mesh WireGuard between all nodes), never the open internet. Connecting two or more devices this way gives the user a private encrypted backbone: their own global private WAN.","params":"enabled (required, 0 or 1)","returns":"link_all_tunnels, rules_dormant (rules parked on enable), rules_restored (rules re-enabled on disable)","auth":"getUserByAuth","min_role":"net-admin","side_effects":"firewall changes take effect immediately on active connections"},{"endpoint":"firewall_link_all_status","description":"Returns whether Link All (full mesh) mode is enabled for the authenticated user. When enabled, all tunnels can communicate with each other without individual firewall rules.","params":"none","returns":"whether link_all is enabled","auth":"getUserByAuth"},{"endpoint":"firewall_rule_delete","description":"Deletes a firewall rule. The rule is identified by all of its fields. The tunnel must belong to the authenticated user.","params":"tunnel_token (required), protocol (required), src_ip (required), src_port (required), dst_ip (required), dst_port (required)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"firewall changes take effect immediately on active connections"}],"ip_addresses":[{"endpoint":"list_addresses","description":"Lists all static addresses (private IPv4, public IPv4, IPv6) for the authenticated user. Each address shows its type, server location, whether it is currently connected, and which profile or tunnel it is assigned to.","params":"tunnel_token (optional, filter by tunnel), device_hash (optional, used to resolve tunnel_token if not provided)","returns":"array of address objects with address, type (static_private, static_public, static_ipv6), site_id, location, persistent, connected, profile_id, profile_name, device_name, tunnel_name. Also returns public_ipv4_used and public_ipv4_max counts.","auth":"getUserByAuth"},{"endpoint":"lease_public_ipv4","description":"Leases a dedicated public IPv4 address. Requires a Pro or Pro+ plan with available dedicated IP slots. Three modes: (1) provide profile_id to lease for an existing profile, (2) provide profile_name and server to create a new profile and lease, (3) provide server alone for a pool-only lease without a profile. Optionally includes IPv6 allocation. The leased IP is persistent and dedicated to the user until released.","params":"profile_id (mode 1), or profile_name + server (mode 2), or server (mode 3). Optional: ip_type (ipv6 for IPv6-only), include_ipv6 (1 to also allocate IPv6), profile_icon, profile_type, tunnel_token (for in-use detection)","returns":"ip_address, ipv6_address (if allocated), site_id, server, profile_id, message, and flags: pool_only, profile_created, requires_reconnect","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"rotate_address","description":"Rotates a static address to get a new random IP at the same server site. Only supported for private IPv4 and IPv6 addresses (public IPv4 cannot be rotated). Fails with 423 if the profile has IP lock enabled. The old address is released and a new one is allocated in a single transaction.","params":"address (required), type (required: static_private or static_ipv6 only)","returns":"confirmation message, new_address","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"release_ip_reservation","description":"Releases a public IPv4 reservation from a profile, returning the IP to the available pool. The profile's public IPv4 setting is disabled. The IP address is no longer dedicated to the user.","params":"ip_address (required)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"release_address","description":"Releases a static address from its profile or tunnel. Fails with 423 if the profile has IP lock enabled. Automatically allocates a replacement private IPv4 or IPv6 when a profile loses its only address. Returns needs_reconnect if the caller's active tunnel is affected by the IP change.","params":"address (required), type (required: static_private, static_public, or static_ipv6), tunnel_token (optional, for reconnect detection)","returns":"confirmation message, replacement_ip (if auto-replaced), needs_reconnect (bool), reconnect_message","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"assign_address","description":"Assigns a static address to a profile. Enforces one IPv4 type per profile: assigning a public IPv4 releases any private IPv4 on the same profile, and vice versa. Returns a 409 conflict with site details if the address is at a different site than the profile's preferred server (send update_location=1 to auto-update the profile's server).","params":"address (required), type (required: static_private, static_public, or static_ipv6), profile_id (required, 0 or empty to unassign), update_location (optional, 1 to auto-update profile server on site mismatch)","returns":"confirmation message. On site mismatch: 409 with ip_location, ip_site_id, profile_location, profile_site_id, profile_name.","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"list_ip_reservations","description":"Lists all public IPv4 addresses reserved to profiles. Shows which profile each IP is bound to and how many dedicated IP slots are used vs available. Dedicated IP slots are included with Pro and Pro+ plans and can be expanded with addon purchases.","params":"none","returns":"array of reservations with ip_address, server, profile_id, profile_name, plus slots_used and slots_max","auth":"getUserByAuth"}],"proxy":[{"endpoint":"update_proxy_config","description":"Updates the proxy/geo-spoofing configuration for a tunnel. Changes the geographic location, browser fingerprint, timezone, and language that web traffic appears to originate from.","params":"tunnel_token (required), cloud_proxy_enabled (optional, 0 or 1), cloud_proxy_location (optional), cloud_proxy_browser (optional), cloud_proxy_timezone (optional), cloud_proxy_language (optional)","returns":"confirmation message","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)","min_role":"net-admin","side_effects":"proxy configuration changes take effect immediately on active connections"},{"endpoint":"get_proxy_config","description":"Returns the proxy/geo-spoofing configuration for a tunnel. Proxy allows the tunnel's web traffic to appear from a different geographic location with a spoofed browser fingerprint, timezone, and language.","params":"tunnel_token (required)","returns":"proxy enabled status, location, browser fingerprint, timezone, language","auth":"getUserByAuth (plus tunnel_token must belong to the authenticated user)"}],"saved_profiles":[{"endpoint":"save_profile","description":"Saves current tunnel settings as a new profile by snapshotting DNS blocklists, firewall, proxy, transport, and server configuration. The profile type is determined by the source tunnel. Optionally allocates dedicated IPv4/IPv6 addresses for the profile. Profiles are location-bound: IPs are tied to a specific server site.","params":"tunnel_token (required), profile_name (required, max 128 chars), profile_icon (optional), profile_notes (optional), profile_type (optional), save_preferred_server (optional, 1 to save), lock_after_save (optional, 1 to lock), preferred_server (optional)","returns":"confirmation message, profile_id","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"update_saved_profile","description":"Updates a saved profile's metadata (name, icon, notes) or re-snapshots settings from a tunnel. Re-snapshotting captures the tunnel's current DNS, firewall, proxy, and transport settings into the profile.","params":"profile_id (required). For metadata: profile_name, profile_icon, profile_notes. For re-snapshot: re_snapshot=1, tunnel_token, profile_name_override (optional)","returns":"confirmation message, profile_id","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"create_saved_profile","description":"Creates a new empty profile without snapshotting a tunnel. Used by the web portal to create WireGuard profiles for static IP management. The profile starts with default settings and can have IPs assigned to it. Not suitable for creating iOS/Android app profiles (use save_profile from a connected tunnel instead).","params":"profile_name (required, max 128 chars), server (required, preferred server location), profile_icon (optional), profile_type (optional, defaults to wireguard)","returns":"confirmation message, profile_id","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"unlock_profile","description":"Unlocks a previously locked profile, allowing IP and settings changes again.","params":"profile_id or tunnel_token (one required), lock_type (optional: 'ip', 'settings', or omit for both)","returns":"confirmation message, profile_id","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"load_profile","description":"Loads a saved profile onto a tunnel, applying all settings from the profile snapshot. The profile type must match the tunnel type (a wireguard profile cannot be applied to an iOS managed tunnel and vice versa). Checks Pro entitlements for premium features. If the profile is already in use on another device, returns a conflict error. The profile becomes 'active' on the tunnel until detached.","params":"profile_id (required), tunnel_token (required), source (optional), switch_server (optional), lock_after_load (optional, 1 to lock after loading)","returns":"confirmation message, profile_id, profile_name, mode","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"delete_saved_profile","description":"Deletes a saved profile and releases all bound IP addresses. Tunnels using this profile get replacement private IPs allocated automatically and their profile binding is cleared. This action is irreversible.","params":"profile_id (required)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"list_saved_profiles","description":"Lists all saved connection profiles for the authenticated user. Profiles come in two types that are not interchangeable: 'wireguard' profiles are for standalone WireGuard clients (set and forget, static IPs, DNS hostnames) and are created from the web portal. 'ios' or 'android' profiles are for app-managed connections (DNS blocklists, transport modes, firewall rules) and are created from the mobile app. Includes in-use status, lock state, assigned addresses, and full settings.","params":"none","returns":"array of profile objects with profile_id, profile_name, profile_type, preferred_server, settings, lock state, in-use status, and assigned addresses","auth":"getUserByAuth"},{"endpoint":"lock_profile","description":"Locks a profile to prevent changes to its IP addresses, settings, or both. A locked profile cannot have IPs assigned, released, or rotated, and its settings cannot be modified. Used to protect a production configuration from accidental changes.","params":"profile_id or tunnel_token (one required), lock_type (optional: 'ip' for IP lock only, 'settings' for settings lock only, omit for both)","returns":"confirmation message, profile_id, lock_type","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"apply_mode","description":"Applies a connection mode template directly to a tunnel without creating or loading a saved profile. WARNING: this is a REPLACE operation, not a patch. It replaces the tunnel's DNS blocklists, whitelists, blacklists, and ALL settings in a single transaction: any settings key omitted from the payload resets to its default. It also detaches the tunnel from its saved profile (mode and active_profile_id are cleared) and releases profile-reserved IPs, including a dedicated public IPv4 if one was bound. Unknown settings keys are rejected with a 400 rather than partially applied. To change individual settings without touching the rest, use update_tunnel instead. Used by the mobile apps' mode selector (Easy Mode, Security, Tinfoil Hat, etc.).","params":"tunnel_token (required), settings (required, JSON object; valid keys: auto_reconnect, bandwidth_stats, block_bad_dns, block_doh_dot, connect_on_startup, connection_profile, enable_routing, firewall, ipv4_public_enabled, ipv6_enabled, keep_established_ssh, kill_default_route, kill_switch, mtu_spoofing, onion_enabled, port, proxy_enabled, security_stats, snarf_dns, transport), template_key (optional), dns (optional, JSON)","returns":"confirmation message, template_key, mode","auth":"getUserByAuth","min_role":"net-admin","side_effects":"REPLACES all tunnel settings (omitted keys reset to defaults), detaches the bound saved profile, releases profile-reserved IPs including dedicated public IPv4, and clears assigned tunnel IPs so the next connect allocates fresh ones. DNS blocking and tunnel configuration changes take effect immediately; the device must reconnect to pick up new addresses"}],"servers_and_info":[{"endpoint":"dns_get_options","description":"Returns the live catalog of DNS blocklist and allowlist options for building the blocklist selection UI, grouped by category: security (malware, phishing, threat intelligence), ads (AdGuard, GoodbyeAds, pop-up ads), mixed (StevenBlack, HaGezi Pro/Pro++/Ultimate), trackers (native telemetry for Apple, Windows, Samsung, etc.), content (gambling, adult, fake news, social media, NSFW, fake stores), and allowlist (recommended exemptions that unblock false positives from aggressive blocklists). No authentication required.","params":"none","returns":"array of blocklist options with name, display_name, description, category, icon, default_enabled, is_allowlist","auth":"none"},{"endpoint":"servers","description":"Lists tunnel locations. Each entry is a doxx.net cluster on owned hardware (active-active nodes with per-packet failover) addressed by one hostname; choose the one nearest the device. cluster_key_count is the live number of concurrently valid server identities that cluster answers for (rotating derived keys held in RAM), which is why one location behaves like that many individual servers. Location keys themselves are never published: the public_key field is present only for older clients and always empty, because each tunnel receives its own server key from create_tunnel or wireguard. Results are cached with a 5 minute TTL. No authentication required. Can be filtered by type.","params":"type (optional, filter by tunnel type e.g. wireguard)","returns":"array of location objects with server_name, hostname, location, type, operator, continent, flag_image, best_for, created_at, cluster_key_count (public_key is always empty)","auth":"none"},{"endpoint":"list_tlds","description":"Returns the available doxx.net top-level domains with their categories. Use this to show users which TLDs they can register domains under. No authentication required.","params":"none","returns":"array of TLD objects with tld and category","auth":"none"}],"tokens":[{"endpoint":"unrevoke_token","description":"Re-enables a previously revoked token by clearing its revoked_at timestamp. The token becomes immediately usable again with its original role, fences, and tunnel scopes intact. Only works on revoked tokens - returns an error if the token is not revoked.","params":"target_token (required, full token string)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"add_geo_fence","description":"Adds a country to a token's geo fence allowlist. When a token has geo fence entries, it can only be used from those countries (GeoIP lookup). If GeoIP lookup fails, the request is allowed by default.","params":"target_token (required), country (required, ISO 3166-1 alpha-2, e.g. US), label (optional)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"remove_geo_fence","description":"Removes a country from a token's geo fence allowlist. Removing all entries makes the token unrestricted by country.","params":"target_token (required), country (required, ISO 3166-1 alpha-2)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"remove_token_tunnel","description":"Removes a tunnel from a token's scope. Removing all entries gives the token access to all tunnels on the account.","params":"target_token (required), tunnel_token (required)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"revoke_token","description":"Revokes a token, making it immediately unusable. The token remains visible in user_list_tokens with a revoked_at timestamp. Cannot revoke your own active token or the last admin token on the account.","params":"target_token (required, full token string)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"create_token","description":"Creates a new auth token for the account. The full token string is returned only once at creation time. Tokens can have different roles (admin, net-admin, read-only, or device) and optional expiration. Omitting role creates a read-only token. role=device mints the capability-walled gateway credential bound to one of your tunnels (see the chat_bot_gateway_for_ai_agents recipe); it is a scope-down operation, so a net-admin token may mint it.","params":"label (optional, max 64 chars), role (optional: admin/net-admin/read-only/device, default read-only), expires_at (optional, RFC3339), tunnel_token (required when role=device; must be your own tunnel), agent_id (optional with role=device: binds that agent principal to the tunnel's device)","returns":"new_token (full token string, store securely); for role=device also role, bound_tunnel and bound_agent_id","auth":"getUserByAuth (admin; net-admin may mint role=device)","min_role":"admin"},{"endpoint":"add_ip_fence","description":"Adds an IP address or CIDR to a token's IP fence allowlist. When a token has IP fence entries, it can only be used from matching IPs. Bare IPs are normalized to /32 (IPv4) or /128 (IPv6). CIDRs are normalized to the network address.","params":"target_token (required), cidr (required, IPv4/IPv6 address or CIDR), label (optional)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"add_token_tunnel","description":"Restricts a token to a specific tunnel. When a token has tunnel scope entries, it can only view and modify those tunnels. The tunnel must be owned by the authenticated account.","params":"target_token (required), tunnel_token (required, must be owned by account), label (optional)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"update_token","description":"Updates a token's label, role, or expiration. Can be used to reactivate an expired token by extending its expiry. Cannot downgrade your own active token's role. Works on expired tokens but not revoked tokens.","params":"target_token (required), label (optional), role (optional: admin/net-admin/read-only), expires_at (optional, RFC3339 or 'never')","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"remove_ip_fence","description":"Removes a CIDR from a token's IP fence allowlist. Removing all entries makes the token unrestricted by IP.","params":"target_token (required), cidr (required, must match stored value exactly)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"},{"endpoint":"user_list_tokens","description":"Lists all auth tokens for the account, including role, expiration, revocation status, geo/IP fences, and tunnel scoping. The calling token is flagged with is_current. Available to any token role.","params":"none","returns":"array of token objects with token (full), label, role, created_at, expires_at, revoked_at, is_current, geo_fence, ip_fence, tunnel_scope","auth":"getUserByAuth"},{"endpoint":"delete_token","description":"Permanently deletes a token and all its associated geo fences, IP fences, and tunnel scopes. Unlike revoke_token, the token is completely removed and will no longer appear in user_list_tokens. Cannot delete your own active token or the last admin token on the account.","params":"target_token (required, full token string)","returns":"confirmation message","auth":"getUserByAuth (admin only)","min_role":"admin"}],"tunnels":[{"endpoint":"list_tunnels","description":"Lists all tunnels for the authenticated user including tunnel token, assigned IPs, server, WireGuard public key, proxy config, and connection status. Requires a valid auth token. To obtain a token, a human must visit https://a0x13.doxx.net, create an account (which requires passing proof of work and accepting the Terms of Service), and then provide the auth token for API use. Note for agents: returned fields that are not documented as parameters of update_tunnel or apply_mode (for example active, is_connected, connection_status, assigned_ip, public_ipv4, active_profile_id) are read-only status fields; do not attempt to set them. Treat tunnel_token values as credentials: they authenticate the tunnel to the network, so avoid echoing them into conversations or logs.","params":"device_hash (optional, filter by device), device_type (optional)","returns":"array of tunnel objects with full configuration and status","auth":"getUserByAuth"},{"endpoint":"get_mobile_options","description":"Returns the connection and transport options for a tunnel. These control how the client connects including transport mode (normal, stealth, or obfuscated), custom port, kill switch behavior, auto connect on startup, proxy routing, onion routing, and connection profile (security or speed optimized).","params":"tunnel_token (required)","returns":"connect_on_startup (0 or 1), kill_switch (0 or 1), transport (normal, stealth, or obfuscated), port (custom port or null for default), proxy_enabled (0 or 1), onion_enabled (0 or 1), connection_profile (security or speed), netdrop_turbo (0 or 1, NetDrop KCP transfer profile: 1 turbo, 0 polite)","auth":"getUserByAuth"},{"endpoint":"create_tunnel","description":"Creates a new WireGuard tunnel with automatic IPv4/IPv6 allocation and keypair generation. Assigns the tunnel to a server and returns the full WireGuard configuration including private key, public key, and assigned IPs. Requires an active subscription (Basic, Pro, or Pro+). Also requires a valid auth token. To obtain a token, a human must visit https://a0x13.doxx.net, create an account (which requires passing proof of work and accepting the Terms of Service), and then provide the auth token for API use.","params":"server (required, server hostname), name (optional, max 64 chars), device_hash (required for mobile), type (wireguard or wireslammer), profile_id (optional), bandwidth_stats (optional, 0 or 1), security_stats (optional, 0 or 1), block_bad_dns (optional, 0 or 1), block_doh_dot (optional, 0 or 1)","returns":"tunnel_token, assigned IPv4 and IPv6, private key, public key, server public key, server endpoint","auth":"getUserByAuth","min_role":"net-admin","side_effects":"edge servers are notified to apply the new tunnel configuration"},{"endpoint":"set_mobile_options","description":"Updates the connection and transport options for a tunnel. Controls transport mode, custom port, kill switch, auto connect on startup, proxy routing, onion routing, and connection profile.","params":"tunnel_token (required), transport (optional: normal, stealth, or obfuscated), port (optional, 1 to 65535), kill_switch (optional, 0 or 1), connect_on_startup (optional, 0 or 1), proxy_enabled (optional, 0 or 1), onion_enabled (optional, 0 or 1), connection_profile (optional: security or speed), netdrop_turbo (optional, 0 or 1: NetDrop transfer profile, 1 turbo, 0 polite)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin"},{"endpoint":"delete_tunnel","description":"Deletes a tunnel and frees all associated resources including IPv4/IPv6 allocations. All active connections on this tunnel are immediately terminated. This action is irreversible.","params":"tunnel_token (required)","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin","side_effects":"active connections on this tunnel are immediately terminated and resources freed"},{"endpoint":"create_tunnel_mobile","description":"Alias for create_tunnel used by the iOS/macOS app. Same behavior and parameters as create_tunnel. Not recommended for programmatic or bot use, use create_tunnel instead.","params":"same as create_tunnel","returns":"same as create_tunnel","auth":"getUserByAuth","min_role":"net-admin","side_effects":"edge servers are notified to apply the new tunnel configuration"},{"endpoint":"create_native_tunnel","description":"Creates a tunnel with subscription enforcement. Requires the 'connect' feature which is granted to Basic, Pro, and Pro+ plans. Returns 403 with an upgrade URL if the user has no active subscription. Otherwise behaves identically to create_tunnel. Used by the iOS/macOS app. For programmatic use, create_tunnel is recommended as it has the same subscription check.","params":"same as create_tunnel","returns":"same as create_tunnel, or 403 with error_code 'feature_required', feature, and upgrade_url","auth":"getUserByAuth","min_role":"net-admin","side_effects":"edge servers are notified to apply the new tunnel configuration"},{"endpoint":"update_tunnel","description":"Updates an existing tunnel's settings including server, name, and feature flags. This is a PATCH operation: only the fields passed in the request are changed, everything else is preserved (contrast with apply_mode, which replaces all settings). If a saved profile is active on the tunnel, flag changes are propagated to the profile definition as well. The tunnel must belong to the authenticated user. Fields returned by list_tunnels that are not listed as parameters here are read-only status fields and cannot be set.","params":"tunnel_token (required), server (optional), name (optional, max 64 chars), type (optional, wireguard or wireslammer), mode (optional, empty string clears it), and boolean flags (each optional, 0 or 1): bandwidth_stats, security_stats, block_bad_dns, block_doh_dot, keep_established_ssh, kill_default_route, auto_reconnect, enable_routing, snarf_dns, firewall, ipv6_enabled, onion_enabled, mtu_spoofing","returns":"confirmation message","auth":"getUserByAuth","min_role":"net-admin","side_effects":"edge servers are notified to apply the updated configuration; disabling firewall deletes the tunnel's firewall rules"},{"endpoint":"wireguard","description":"Returns the full WireGuard configuration for a tunnel, formatted for use by the mobile app. Includes private key, server public key, endpoint address, assigned IPs, and DNS settings.","params":"tunnel_token (required)","returns":"WireGuard configuration including private key, public key, server public key, endpoint, assigned IPv4 and IPv6, DNS servers","auth":"getUserByAuth"}]},"platform":{"name":"doxx.net","type":"Agentic Defined Network (ADN)","tagline":"Privacy is a right, not a privilege.","summary":"doxx.net is a global network built from scratch on hardware we own and operate, on IP space and an autonomous system we hold. Not leased servers at low-quality hosting providers who also monitor the wire: our equipment, our network stack, our routing, our security policy, end to end. Every location is a full cluster with per-packet failover holding thousands of individual server keys rotating in RAM, not an individual server. No cloud providers. No third-party DNS. No leased endpoints.","network":{"asn":"AS16740","ip_registries":["ARIN","RIPE"],"ownership":"Owned hardware, owned network stack, owned IP space, owned routing, owned security policy. No cloud instances, no leased or rented servers, no hosting provider underneath with its own staff, hypervisors or monitoring. When the equipment is yours, the policy is yours.","footprint":"Global. servers=1 (no auth) returns the live list of locations; this document describes the network rather than counting it.","clusters":"Locations are full clusters, not individual servers: owned nodes running active-active behind one address, so any node can carry any packet of any session (per-packet failover) and a node leaving service is invisible to the tunnel.","key_rotation":"Thousands of individual WireGuard server keys, derived per site and rotating in RAM. Tunnels are not pinned to one machine or one long-lived key.","backbone":"Full-mesh WireGuard topology with BGP routing between all clusters","dns":"Own authoritative DNS infrastructure with real-time threat intelligence","tld_count":196},"capabilities":["Encrypted WireGuard tunnels terminating on full clusters with per-packet failover","Thousands of individual server keys rotating in RAM, derived per site","Private mesh networking between devices (Link All)","Custom domain registration across 196 TLDs independent of ICANN","Authoritative DNS hosting with DNSSEC","Real-time DNS threat blocking across a curated blocklist catalog","Geo-spoofing HTTP/HTTPS proxy","Dedicated static IPv4 and IPv6 addresses","TLS certificate signing via private CA","Per-tunnel firewall rules with device-to-device controls","Connection profiles with snapshot and restore","Agent gateway: owned agent principals for AI agents with end-to-end encrypted agent-to-human chat over the P2P mesh (github.com/doxxcorp/gateway)","Zero-knowledge account system: no email, no phone, no personal data required"],"for_agents":"doxx.net provides a programmable networking layer for AI agents and automated systems. Create tunnels, route traffic through any global location, register domains, configure DNS, and manage firewall rules via API. Every endpoint returns a 'context' field designed for AI consumption. Agents operate with full privacy: accounts are token-based with no personal data requirements.","for_users":"The most private network available. Built from the ground up so no third party ever touches your data: our hardware, our network stack, our IP space, our DNS, our security policy. No hosting provider underneath, no logs, no tracking, no compromises."},"about":{"creator":"Barrett Lyon","founded":"2024","company":"doxx.net corp","mission":"doxx.net exists to provide stable, private networking infrastructure for everyone. It was created to give people a secure way to access the internet without surveillance, censorship, or restriction. For communities in countries with limited internet freedom, doxx.net provides uncensored access to the full internet. For users everywhere, it provides networking that no third party can observe, intercept, or shut down.","why":"Every component of doxx.net is built and operated independently. Own servers: hardware we bought and racked, not machines leased from a hosting provider that keeps its own staff, hypervisors and monitoring underneath. Own network stack. Own IP space (AS16740). Own DNS infrastructure. Own BGP routing. Own security policy. No cloud providers, no third-party resolvers, no rented endpoints. Locations are full clusters with per-packet failover and thousands of individual server keys rotating in RAM, not individual servers. This independence exists for one reason: so no external entity can access, log, or compromise user traffic. Privacy is not a feature. It is the architecture.","agentic_networking":"doxx.net is built for the agentic era. AI agents need private, reliable, programmable networking: tunnels they can create via API, DNS they can configure, firewall rules they can set, dedicated IPs they can rotate. doxx.net provides all of this with zero-knowledge accounts (no email, no phone, no personal data) and a fully self-documenting API with context fields designed for AI consumption. Agent-to-agent (a2a) and agent-to-human (a2h) communication runs on the same infrastructure as human traffic, with the same privacy guarantees. The chat gateway makes a2h concrete: create_agent mints an agent principal owned by a human (a sub-friend, not a separate account), the doxxGateway binary (https://github.com/doxxcorp/gateway) hosts it on any Linux machine as one of the owner's devices, and the agent drives an end-to-end encrypted chat line to its human through a local self-teaching API and a native Model Context Protocol surface - MCP clients spawn `doxxGateway mcp` or hit the loopback /mcp endpoint and get the whole chat plane as tools (see the chat_bot_gateway_for_ai_agents recipe in use_cases). The owner sees every conversation their agent has, and agents can only reach people the owner is friends with.","open_internet":"doxx.net operates its own domain registry with 196 TLDs independent of ICANN, its own authoritative DNS, and its own certificate authority. This means doxx.net users can register domains, host DNS, and sign TLS certificates without relying on any external authority. The platform provides internet services outside the traditional internet: a parallel infrastructure layer that cannot be censored or revoked by registrars, certificate authorities, or governments."},"knowledge_graph":{"description":"doxx.net is powered by three interconnected APIs that form a knowledge graph. Together they define what the platform does, how it looks, and how it renders.","apis":{"config":{"learn":"GET https://config.doxx.net/ for full self-documenting reference.","role":"Product engine. 86 endpoints for tunnels, DNS, domains, firewall, proxy, devices, profiles, addresses, tokens and agents.","url":"https://config.doxx.net/"},"keystone":{"learn":"GET https://keystone.doxx.net/ with X-Keystone-Key header","url":"https://keystone.doxx.net/"}}},"documentation":{"full_reference":"https://github.com/doxxcorp/config.doxx.net","raw_reference":"https://raw.githubusercontent.com/doxxcorp/config.doxx.net/main/README.md","endpoints":{"devices":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/devices.md","dns_blocklists":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/dns-blocklists.md","dns_records":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/dns-records.md","domains":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/domains.md","firewall":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/firewall.md","ip_addresses":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/addresses.md","proxy":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/proxy.md","saved_profiles":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/profiles.md","servers":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/servers.md","tunnels":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/endpoints/tunnels.md"},"authentication":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/authentication.md","error_codes":"https://github.com/doxxcorp/config.doxx.net/blob/main/docs/error-codes.md"},"support":{"portal":"https://a0x13.doxx.net","discord":"https://discord.gg/Gr9rByrEzZ","email":"support@doxx.net","privacy":"https://a0x13.doxx.net/privacy/","terms":"https://a0x13.doxx.net/terms/"}}