Your first Nodetonet REST API call — list proxies in five lines of curl

Almost everything you can do in the Nodetonet panel — create proxies, rotate IPs, mint tokens, pull usage stats — is also exposed over a plain HTTPS REST API. The panel itself is just a client on top of it. This post is the complete practical minimum: get your key, send one request, understand the response, handle errors, paginate, and know what other endpoints exist. Five lines of curl, no SDKs, no ceremony.

TL;DR: set Authorization: Bearer ntn_live_… on every request to https://nodetonet.com/api/v1/. Every response is {"data": [...], "meta": {...}}. That pattern repeats across every endpoint.

1 · Grab your API key

Open /dashboard and locate the Personal API Key card. Click the eye icon to reveal it, click the copy icon to grab it. The string starts with ntn_live_ and is about forty characters long. Anyone who has it can manage your account and all its proxies, tokens and billing, so treat it exactly like a password.

For the full story on key scopes, rotation and handing read-only copies to customers, see understanding your API key and the comparison of customer API tokens vs personal keys.

Export it as a shell variable so you never paste it into a log or screenshot by accident:

export NTN_KEY="ntn_live_a8c3...f2e1"

2 · Send the request

Every endpoint lives under https://nodetonet.com/api/v1/ and authenticates with a standard Authorization: Bearer header. The simplest possible call lists your proxies:

curl -H "Authorization: Bearer $NTN_KEY" \
  https://nodetonet.com/api/v1/proxies

No content-type header, no body, no version negotiation — just a GET with one header. If you want the response pretty-printed, pipe it through jq . or pass -s | python3 -m json.tool.

3 · The JSON response shape

Every list endpoint returns a consistent envelope with two top-level keys:

{
  "data": [
    {
      "id": "prx_4d7a91",
      "title": "Tunnel #4d7a",
      "protocol": "http",
      "host": "sub42.nodetonet.com",
      "port": 48888,
      "username": "u8x2",
      "password": "p7q1",
      "tokenId": "tok_3kzl8w9",
      "serverId": "srv_de_1",
      "status": "active",
      "createdAt": "2026-04-03T14:21:08.114Z"
    }
  ],
  "meta": {
    "page": 1,
    "perPage": 25,
    "total": 1,
    "totalPages": 1
  }
}

data is always an array — even when you fetch a single resource by ID, it is wrapped in a one-element array. meta carries pagination state. Write your parser once and it covers every list endpoint in the API. The host + port + username + password fields are exactly what you paste into your tool's proxy settings, whether you use SOCKS5 or HTTP/HTTPS.

4 · Status codes you will actually see

Errors always come back as JSON in the same envelope shape so your error handler never needs to branch on content-type:

{
  "error": {
    "code": "unauthorized",
    "message": "API key invalid or rotated"
  }
}

5 · Pagination

Lists default to 25 items per page. Walk a longer list with ?page=2, ?page=3, etc., and stop when meta.page equals meta.totalPages:

curl -H "Authorization: Bearer $NTN_KEY" \
  "https://nodetonet.com/api/v1/proxies?page=2"

Override the page size with ?perPage=50 up to a hard ceiling of 100 — anything above that returns 400. Cursor-based pagination is not yet available; offset pagination handles the scale most accounts work with comfortably.

6 · Filtering and query parameters

Append query parameters to narrow results without fetching the full list. Supported on /proxies:

• ?status=active — only active proxies.
• ?protocol=socks5 — only SOCKS5 proxies.
• ?tokenId=tok_3kzl8w9 — proxies tied to a specific device token.

Parameters can be combined: ?status=active&protocol=http&page=2. The meta.total in the response reflects the filtered count, not the total across all records.

7 · The full endpoint surface

Once you understand the pattern — Bearer auth, consistent envelope, same status codes — every other endpoint is obvious. Here is a map of the most useful ones:

GET    /api/v1/proxies              # list all your proxies
POST   /api/v1/proxies              # create a new proxy
GET    /api/v1/proxies/<id>         # fetch one proxy
PATCH  /api/v1/proxies/<id>         # update title, protocol, etc.
DELETE /api/v1/proxies/<id>         # delete
GET    /api/v1/proxies/<id>/usage   # bytes used, request count

GET    /api/v1/tokens               # device tokens (paired phones)
POST   /api/v1/tokens/<id>/rotate-ip # trigger an IP rotation
GET    /api/v1/servers              # available edge servers
GET    /api/v1/balance              # prepaid credit + recent charges
GET    /api/v1/clients              # per-client proxy credentials

The full OpenAPI 3.1 specification is at /openapi.json. Feed it to any code generator and you will have a typed client in your language of choice within seconds — no hand-written HTTP boilerplate required.

8 · A real-world script in Python

Here is the same idea in Python — list all active proxies, page through results, and print each endpoint. No third-party libraries needed beyond the standard library:

import urllib.request, json, os

NTN_KEY = os.environ["NTN_KEY"]
BASE = "https://nodetonet.com/api/v1"

def api_get(path):
    req = urllib.request.Request(
        BASE + path,
        headers={"Authorization": f"Bearer {NTN_KEY}"}
    )
    with urllib.request.urlopen(req) as r:
        return json.loads(r.read())

page, total_pages = 1, 1
while page <= total_pages:
    body = api_get(f"/proxies?status=active&page={page}")
    total_pages = body["meta"]["totalPages"]
    for px in body["data"]:
        print(px["protocol"], px["host"], px["port"])
    page += 1

For a more complete example including proxy creation and IP rotation, see programmatic tunnel creation in Python. If you are building automation around rotating proxies, the token groups guide shows how to manage device pools programmatically.

9 · Security checklist before you ship

• Never commit the key to source control. Load it from an environment variable or a secrets manager.
• Rotate the key immediately if it leaks — the dashboard invalidates the old one on the spot.
• Use customer tokens for end-user automation so each customer only reaches their own resources. See customer tokens vs personal keys.
• Respect rate limits — 600 requests per minute is generous for most automation, but bulk scripts should back off on 429 rather than hammering through it.
• Validate IDs before acting on them — check meta.total to confirm the list returned what you expected before a destructive PATCH or DELETE.

What to explore next

• Understanding your API key — scopes, rotation and sharing read-only access.
• Programmatic tunnel creation in Python — the same endpoints from a real production script.
• Webhooks for IP-change events — push notifications instead of polling /usage in a loop.
• How to use Nodetonet — the bigger picture: tokens, devices, proxies and billing in one walkthrough.
• All platform features — mobile proxies, rotating pools, geo-targeting, HTTP tunnels and more.