A read-only bearer-token REST API over your own Nodes, Network, and Workflows. Every endpoint below is real and live today — there is no separate “coming soon” tier.
Getting started
Create a credential at Account → API, then send it as a bearer token on every request:
Authorization: Bearer tn_live_example_key1234567890ab_x9Y8z7W6v5U4t3S2r1Q0pNFormat: tn_live_<key_id>_<secret>. The secret half carries ~256 bits of entropy and is stored only as a SHA-256 hash — it cannot be recovered by TrafficNodes staff or support.
Reveal-once. The full key is shown to you exactly one time, right after creation (or a manual rotation) — copy it immediately. TrafficNodes never stores or displays the raw key again.
Server-side use only. Never embed a key in frontend JavaScript, a public repo, or a client-side app bundle.
An unknown key id, a wrong secret, and a revoked credential all return the same generic 401 unauthorized — there is no way to distinguish them from the response alone (anti-enumeration, by design).
Authorization
Read-only today — every scope below is a read grant, never a write.
nodes:readRead public Node Passport detail.network:readRead your own owned Network assets.workflows:readRead your own Workflows and Runs.Reference
/api/v1/menone (any valid credential)The caller's own account, profile, and capability flags (buyer/seller/admin).
/api/v1/nodes/:idnodes:readOne public Node Passport — the same data /node/[id] renders, RLS-scoped identically.
/api/v1/networknetwork:readThe caller's own owned Network assets, paginated.
/api/v1/network/:idnetwork:readOne of the caller's own Network assets. A foreign or absent id both 404.
/api/v1/workflowsworkflows:readThe caller's own Workflows, paginated.
/api/v1/workflows/:idworkflows:readOne of the caller's own Workflows — step count and kind only, never the full definition JSON.
/api/v1/workflows/:id/runsworkflows:readThe most recent Runs for one Workflow (bounded to 20, no pagination).
/api/v1/workflows/:id/runs/:runIdworkflows:readOne Run. A Run id that belongs to a different Workflow 404s, not just a wrong-owner id.
No write endpoint exists (no POST/PATCH/DELETE) — every mutation (creating a Node, running a Workflow, editing a Stack) stays a signed-in browser action. A future write API is a deliberate, separate decision, not an oversight.
Conventions
List endpoints (/network, /workflows) take an optional limit (1–100, default 20) and an opaque cursor. The response carries the next page in meta.next_cursor.
GET /api/v1/network?limit=20&cursor=eyJjcmVhdGVkX2F0IjoiLi4uIn0Example request and response:
curl https://trafficnodes.com/api/v1/me \
-H "Authorization: Bearer tn_live_example_key1234567890ab_x9Y8z7W6v5U4t3S2r1Q0pN"{
"data": {
"user": { "id": "…", "email": "…" },
"profile": { "displayName": "…", "handle": "…", "status": "active" },
"capabilities": { "buyer": true, "seller": false, "admin": false }
},
"request_id": "…"
}Failure modes
Every error response shares one envelope:
{
"error": { "code": "not_found", "message": "Workflow not found." },
"request_id": "…"
}unauthorized401Missing, malformed, or invalid/revoked credential.forbidden403A valid credential without the required scope.not_found404Absent OR foreign resource — identical response either way.validation_error422A path or query parameter failed validation.rate_limited429Too many requests in the current window (see Rate limits below).internal_error500An unexpected server error.Operations
60 requests per 60 seconds, per credential. Every response carries X-RateLimit-Limit/-Remaining/-Reset, and a 429 adds Retry-After.
This limiter is in-memory, per server process — it resets on every deploy and does not coordinate across multiple instances. Treat it as a guideline today, not a distributed guarantee.
Revoke a credential any time from Account → API. Every request made with a revoked key afterward gets the same generic 401 unauthorized as an unknown or wrong key — no signal distinguishes “revoked” from “never existed.”
Scope
Ready to create your first credential?
Go to Account → API