Nodetonet in Postman — fork the collection, set your token, ship requests

Postman is the right tool when you want to explore an API before writing code, share a working request with a teammate, or smoke-test a production change without spinning up a local environment. The Nodetonet REST API works perfectly in Postman — no special protocol, no signed-URL ceremony, just Bearer auth and JSON.

TL;DR: create one environment with two variables, set the Authorization header once on the collection, then every request inherits it. The whole setup takes about two minutes.

We are publishing a hosted collection at /api/postman-collection.json (ETA Q3 2026). Until it lands, the manual setup below produces a byte-identical workspace. The guide also covers Newman for CI, practical tips, and how Postman connects to the broader Nodetonet developer surface — including HTTP tunnels, rotating proxies and the reseller API.

What the Nodetonet REST API covers

Before you open Postman, it helps to know what the API actually controls. Nodetonet is a self-hosted mobile proxy and rotating proxy platform — the REST API is the programmatic surface for everything you can do in the panel:

Each group maps one-to-one to a Postman folder in the hosted collection. For a narrative walkthrough of the same surface from code, see REST API: your first call and programmatic tunnel creation in Python.

Step 1 — Create the Postman environment

Open Postman and navigate to Environments → Create. Name it nodetonet-prod. Add exactly two variables:

Marking ntn_token as secret masks it in the UI and strips it from shared collection exports. To get your token value, log in and open the API tokens page — create a token with the scopes you need (for read-only testing, proxies:read devices:read is enough). For background on token scopes, see customer API tokens vs personal tokens.

Create a second environment named nodetonet-dev with the same variables but a staging token. Switch between them with the environment dropdown — no risk of POSTing to production when you meant dev.

Step 2 — Configure authorization on the collection

Create a new collection called Nodetonet. In its Authorization tab, select Bearer Token and enter {{ntn_token}} as the value. Every request you add inherits this setting — you never repeat the header per request. This is the single most useful Postman pattern for token-authenticated APIs.

Step 3 — Your first request: list proxies

Add a request to the collection:

GET {{base_url}}/proxies

No body, no extra headers. Hit Send and you get a JSON array of proxy objects. To narrow the results — say, only running proxies — add query params:

GET {{base_url}}/proxies?status=running&limit=50

Add a Tests snippet to assert shape:

pm.test("response is 200", () => pm.response.to.have.status(200));
pm.test("all proxies running", () => {
  pm.response.json().forEach(p => pm.expect(p.status).to.eql("running"));
});

The Tests tab runs after every Send. When you hook this into Newman for CI it becomes a contract test that runs on every PR — see audit logs for what the API records about these calls.

Step 4 — Create a proxy and capture the ID

Add a POST request:

POST {{base_url}}/proxies
Content-Type: application/json

{
  "name": "postman-test",
  "protocol": "http",
  "port": 10200
}

In the Tests tab, capture the returned ID so later requests can reuse it:

const body = pm.response.json();
pm.environment.set("last_proxy_id", body.id);
pm.environment.set("last_proxy_port", body.port);
console.log("created proxy", body.id, "on port", body.port);

{{last_proxy_id}} is now available in any subsequent request. This pattern — capture → reuse — is the core of Postman automation. Combine it with a DELETE call and you have a full create-verify-teardown smoke test. For details on proxy protocols supported (HTTP, HTTPS and SOCKS5), see the features page.

Step 5 — Delete a proxy

DELETE {{base_url}}/proxies/{{last_proxy_id}}

Chain "create → verify → delete" in the Postman Collection Runner for a repeatable smoke test that finishes in a few seconds. Export the collection and environment as JSON files, then drive them headlessly with Newman:

newman run nodetonet.postman_collection.json        -e nodetonet.postman_environment.json        --env-var ntn_token=$NTN_TOKEN        --reporters cli,junit        --reporter-junit-export results.xml

The JUnit reporter output integrates with GitHub Actions, Jenkins or any CI system that reads test XML. See understanding your API key for how to inject NTN_TOKEN as a CI secret.

Step 6 — Working with devices

Devices are Android phones running the Nodetonet agent app — each one is a mobile proxy exit point on a real cellular carrier. The devices API lets you read health, trigger IP rotation, and restart the agent remotely:

GET  {{base_url}}/devices              // list all paired devices
GET  {{base_url}}/devices/{{device_id}} // health, carrier, last-seen
POST {{base_url}}/devices/{{device_id}}/reset-ip  // trigger IP rotation
POST {{base_url}}/devices/{{device_id}}/restart   // restart agent

This is particularly useful when testing rotating proxy pipelines — you can programmatically force an IP change and immediately verify the new exit IP with our free What is my IP tool. You can also verify the new IP through our proxy checker. For the full device lifecycle, read device health: what "Online" means.

Step 7 — Rotating proxy and client management

Rotating proxies (token groups) are the multi-device pooled mode. Key endpoints:

GET  {{base_url}}/rotating-proxies              // list pools
POST {{base_url}}/rotating-proxies              // create a pool
GET  {{base_url}}/rotating-proxies/{{rp_id}}/clients       // list per-customer credentials
POST {{base_url}}/rotating-proxies/{{rp_id}}/clients       // create a client with quota + expiry
PUT  {{base_url}}/rotating-proxies/{{rp_id}}/clients/{{client_id}} // update quota or threads
DELETE {{base_url}}/rotating-proxies/{{rp_id}}/clients/{{client_id}}

If you operate a reseller or white-label setup, the clients API is how you provision sub-accounts programmatically. See proxy clients: per-customer auth, quota limits per client and thread limits per client for field-level docs.

Tips that aren't obvious until you've done it once

• Use pre-request scripts for dynamic values. If an endpoint needs a fresh timestamp or a UUID, generate it in a Pre-request Script with pm.variables.set("ts", Date.now()) — it runs fresh before each send.
• Surface rate-limit headers. Nodetonet returns X-RateLimit-Remaining and X-RateLimit-Reset on every response. Add a Tests snippet that logs them so throttling is visible during exploratory work.
• Postman secrets are not Git secrets. If you sync your workspace to a team, Postman stores secrets in their account too. For team-shared collections, use a CI-scoped token (proxies:read only) and never share production-write tokens.
• Import the OpenAPI spec for full coverage. Postman can import /openapi.json directly via File → Import → Link — auto-regenerated every time we ship a new field. The hand-crafted collection adds curated examples and Tests assertions; the OpenAPI import gives you complete endpoint coverage.
• Use collection variables for shared IDs. Promote last_proxy_id from an environment variable to a collection variable if it's only used within one flow — it keeps your environment cleaner.
• Geo-targeting syntax goes in the username. When calling endpoints that accept proxy username modifiers (like -country-tr, -city-istanbul or -session-XXXX), set them as environment variables so you can switch targets without editing request bodies. See geo-targeting for the full modifier reference.

The hosted collection (Q3 2026)

When it ships, importing the collection via /api/postman-collection.json (or clicking the "Run in Postman" button that will appear on every doc page) drops all eight API groups pre-configured into your workspace — with example responses, 4xx examples, and Tests assertions included. Until then, the manual setup above is functionally identical. Bookmark this page; we'll update it the day the collection goes live.

Ready to make your first call? Create a free account, grab a token, paste the environment snippet above, and hit Send. Your first proxy is one request away.