API Overview

Overview

The NetStacks Controller exposes a JSON REST API. It is the same API the Admin Console and the NetStacks Terminal (in enterprise mode) use, so anything you can do in the UI is backed by an endpoint you can call from your own scripts and tools.

The API is part of the Controller only. A standalone NetStacks Terminal does not expose this API.

The API Reference section covers:

• Authentication: logging in, tokens, and sessions
• Devices: inventory, sites, imports
• Connection profiles: credentials and secrets
• Templates: config templates and platforms
• Stacks and deployments: stacks, instances, and deployments
• Config backups: config pulls, versions, diffs, and snapshots
• MOPs: MOP review and executions
• Scheduled tasks and jobs
• Administration: users, roles, organizations, audit log, settings
• Errors: error format and status codes

Base URL and TLS

All endpoints live under /api on the same host and port as the Admin Console. With the standard install that is:

https://<controller-host>:3000/api

The API has no version prefix (there is no /v1). It always uses HTTPS.

The Controller generates its own certificate authority (CA) and signs its server certificate with it. To make curl and other clients trust it, download the CA certificate once (no login needed) and pass it to your client:

# Download the Controller's CA certificate (public endpoint)
curl -k -o netstacks-ca.pem https://controller.example.com:3000/api/tls/ca-certificate

# Use it for later calls
curl --cacert netstacks-ca.pem https://controller.example.com:3000/api/health

Interactive reference (Swagger UI)

Every Controller serves an OpenAPI description of its API:

In the Admin Console, open the Help menu (the question-mark icon in the header) and choose API Docs to open the Swagger UI.

The Swagger UI groups endpoints by tag. To try calls from the browser, click Authorize and paste an access token from a login. Swagger UI adds the Bearer prefix for you.

Quick start

Log in, save the access token, and call an endpoint:

NS=https://controller.example.com:3000

# 1. Log in (local NetStacks user)
TOKEN=$(curl -s --cacert netstacks-ca.pem -X POST "$NS/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"automation","password":"<password>"}' | jq -r .access_token)

# 2. Call the API with the token
curl -s --cacert netstacks-ca.pem "$NS/api/devices?limit=10" \
  -H "Authorization: Bearer $TOKEN" | jq '.devices[] | {name, host}'

There are no long-lived API keys. Scripts log in as a NetStacks user and use the refresh token to keep going. See Authentication.

Conventions

• JSON in, JSON out. Send Content-Type: application/json on requests with a body. The CSV device import is the one text upload.
• IDs are UUIDs. Timestamps are ISO 8601 / RFC 3339 in UTC (for example 2026-10-12T14:03:22Z).
• Pagination. Most list endpoints take limit and offset query parameters. The default limit is 50, and most lists cap it at 100. The audit log uses page and limit instead.
• Create calls usually return 201 Created with the new object. Delete calls usually return 204 No Content.
• Organization scope. Every request works inside the organization carried in your access token. You can't see or change another organization's devices, templates, and so on. Platform administrators can switch organizations (see Switching organization).
• Partial updates. PUT endpoints on devices, templates, stacks, users, and profiles only change the fields you send. Leave a field out to keep its current value.
• Rate limits apply only to the /api/auth/* endpoints. See Login rate limits.

Permissions

Endpoints check the permissions granted by the caller's roles (see Roles and permissions). The API checks these permission keys:

The * permission (the built-in admin role) grants everything inside its organization except platform.admin. A call without the needed permission returns 403 with {"error":"Insufficient permissions"}.

The endpoint tables on each page show the permission each endpoint checks.

Resource groups

Main base paths, all under /api:

Health endpoints

These endpoints need no token and are handy for load balancers and monitoring:

GET /api/admin/health (token required) returns a per-component view: the database (with latency), the task scheduler, the credential vault, Valkey, and the overall uptime. It backs the Platform Health page.