Book a demo

Swift Fox API

Read your network's devices, backhauls, CPEs, issues and metrics, and run live tests from your pingboxes.

Getting an API key

Make one in Swift Fox. My Account → API keys makes a key that acts as you, for your own scripts and AI tools. For an integration, an admin makes the key on a service account in User Admin → API keys, so it keeps working when staff change.

You choose what the key can do (reading is always included; running live tests and seeing subscriber names are optional), which ISP it covers, and when it expires. The key is shown once, so copy it somewhere safe. Either way, a key can never see or do more than its owner.

Your first request

Every request sends the key in the Authorization header. This one lists the ISPs your key can reach:

curl -H "Authorization: Bearer $SWIFTFOX_KEY" https://api.swiftfox.net/v1/isps
{
  "isps": [
    { "ispcode": "yourisp", "name": "Your Wireless Co." }
  ]
}

How it works

Authentication. Send an API key in the Authorization header: Authorization: Bearer sfk_…. Never put a key in the URL: a request with one there is refused (400) without the key being checked.

ISPs. Most endpoints take isp, an ISP code from GET /isps. Leave it out when your key reaches exactly one ISP.

CSV. Every list endpoint also returns CSV: add format=csv, or send Accept: text/csv. Columns follow the JSON field order, and nested fields are flattened with dots (ap.name).

Paging. Lists return next_cursor, plus a Link: <…>; rel="next" header. Pass it back as cursor to get the next page; it's null on the last one. Treat cursors as opaque.

Errors. Every error is application/problem+json (RFC 9457) with a non-2xx status, so wget and curl --fail exit non-zero instead of saving an error as data. Branch on type; detail is written for people.

Scopes. A key carries scopes: read for every GET, actions for the POST endpoints (live tests and config collection), and pii to see subscriber names in CPE results. A key can never do more than the user or service account that owns it.

Rate limits. Per key, 120 reads and 10 actions a minute; per ISP, 600 reads a minute. Over a limit you get 429 with Retry-After.

Versioning. New fields, endpoints and optional parameters aren't breaking changes, so ignore fields you don't recognise. Fields documented as "more may be added" (a pingbox's status, for example) can gain new values, so handle ones you don't recognise. A breaking change means a new version, with at least 12 months of overlap.

The full machine-readable description is at https://api.swiftfox.net/v1/openapi.json (OpenAPI 3.1), for code generators and tools like Postman.

Reference

  • ISPs and sites — The ISPs a key can access, their sites, and the regions the sites belong to.
  • Devices — Infrastructure devices (routers, APs, backhaul radios, switches): detail, live health and config history
  • Backhauls — Backhaul links: endpoints, capacity, usage and cross-link pings
  • CPEs — Customer radios: plan, signal, shaping and live health
  • Issues — Issues and alerts, open and resolved
  • Network — The RF channel plan, what changed around a time, and everything known about an IP address.
  • Pingboxes — The vantage points inside your network that ping your devices and run live tests
  • Live tests — Ping and traceroute from a pingbox inside the network