Tools

Five domains of tools. You never call these by hand - you describe the outcome and the agent picks them.

---

​

Account

Needs balance:read for balance, stats:read for usage and history. All read-only - nothing here costs anything or changes anything.

---

​

Geo targeting

Needs geo:read. These turn names you say out loud into the values a connection username expects. Three things constrain what you can ask for:

• Geographic and network targeting are mutually exclusive. Country, state, city and ZIP go together. ISP and ASN go together. Never both in one connection.
• City, state and ZIP need a country. Asking for a city on its own does nothing.
• ISP targeting is mobile proxies only.

---

​

Plans

Needs proxies:read. The agent calls this before creating anything, so you do not have to know which plan you want. Saying “residential” is enough; saying nothing at all is usually also enough.

---

​

Proxy resources

Reading needs proxies:read. Everything else needs proxies:write. What to keep in mind:

• The name is permanent. It is chosen at creation and cannot be changed afterwards, because it forms part of the connection username. Lowercase letters, digits and underscores only - no hyphens, since a hyphen separates parameters in that username.
• One proxy covers every country. The country is set per connection, not per resource, so there is no reason to ask for one proxy per market.
• Deactivation is reversible, deletion is not. If you want the traffic to stop but the resource to survive, say deactivate.
• A new password breaks whatever is connected. Anything using the old one stops immediately.

---

​

Proxy settings

Needs proxies:write.

• Limits come in two flavours: a traffic ceiling or a money ceiling, reset daily or monthly. A limit is not checked at the moment you set it - when usage crosses the line, the proxy is suspended in the background and stops passing traffic.
• The whitelist replaces, it does not append. Say “add 203.0.113.10 to the whitelist” rather than “set the whitelist to 203.0.113.10”, so the agent reads the current list before writing.

---

​

Destructive actions

Two tools are marked destructive in the protocol: deleteProxyResource and regenerateProxyPassword. A well-behaved client shows you what is about to happen and waits for a yes.

---

​

What the agent knows without asking

Alongside the tools, the server publishes a set of documents the agent reads by itself, describing what each tool returns. You never see them and there is nothing to configure. They are the reason an agent connected to this server tends to get things right the first time: it knows what came back, rather than guessing from field names.

---

​

Next steps