canonical: https://jentic.com/apis/openwisp.org/openwisp # OpenWISP Controller API Jentic publishes the only available OpenAPI specification for OpenWISP Controller API, keeping it validated and agent-ready. The OpenWISP Controller API exposes REST endpoints for the open-source network management stack used by ISPs, communities, and IT teams to operate fleets of routers, access points, and embedded Linux devices. Agents can register devices, push configuration templates, manage VPN servers, send commands to running devices, and inspect IP address management subnets. Authentication is a bearer token obtained from the OpenWISP token endpoint, scoped to a tenant in the OpenWISP installation. ## For AI agents Manage OpenWISP-controlled network devices, configurations, templates, VPN servers, and IPAM subnets through 29 REST endpoints, with bearer token authentication. ## Scope Does not handle radio firmware builds, end-user captive portal authentication, or billing - use for OpenWISP device, template, VPN, and IPAM management only. ## Capabilities - Register network devices and update their configuration via the controller - Apply configuration templates to a device or device group in bulk - Provision and manage VPN servers used to reach remote devices - Send remote shell commands to devices and inspect command history - Allocate next-available IP addresses from managed IPAM subnets - Inspect device monitoring status and network topology graphs ## Use cases ### Fleet provisioning agents Network operators provisioning new sites can use the OpenWISP Controller API to register devices, attach them to a device group, and apply a configuration template in one workflow. The `/controller/device`/ POST creates the device, and `/controller/template`/ exposes the templates that drive its configuration. Agents can run this end-to-end against a fresh OpenWISP install in minutes rather than hand-editing UCI files on every router. Example prompt: POST `/controller/device`/ with a name, MAC address, and group, then POST `/controller/template`/ assignment to apply the standard WireGuard template. ### Remote command and recovery workflows Field-support agents can push commands like reboot, custom shell, or firmware checks to remote devices through `/controller/device/{id}/command/.` The endpoint accepts a command type and arguments, and command history can be retrieved with the matching GET so the agent can confirm whether the operation reached the device. This replaces SSH-by-hand troubleshooting for a fleet that may sit behind NAT or carrier-grade routing. Example prompt: POST `/controller/device/{id}/command`/ with type=reboot and poll the command history endpoint until status returns success. ### IP address management automation Network engineers can use the IPAM endpoints under `/ipam/subnet`/ to keep address allocation in sync with device onboarding. The `/ipam/subnet/{id}/get-next-available-ip`/ endpoint returns the next free address inside a subnet, which agents can wire into device-creation flows so every new device receives a routable IP without manual lookup. Example prompt: GET `/ipam/subnet/{id}/get-next-available-ip`/ to reserve an IP, then include it when calling POST `/controller/device/.` ### AI agent network operator Through Jentic, an AI agent can answer operator questions like 'how many devices are offline in region X' by calling `/controller/device`/ with filters and joining results with `/monitoring/device/{id}/.` The Jentic One instance holds the OpenWISP bearer token per tenant, so multi-tenant managed-service agents can scope each call to the right customer. Example prompt: Search Jentic for 'list openwisp devices and their monitoring status', call `/controller/device`/ then `/monitoring/device/{id}`/, and summarise offline devices. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/controller/device/` | List devices managed by the controller | | POST | `/controller/device/` | Register a new device | | POST | `/controller/device/{id}/command/` | Send a command to a device | | POST | `/controller/template/` | Create a configuration template | | GET | `/ipam/subnet/{id}/get-next-available-ip/` | Reserve the next available IP in a subnet | | GET | `/monitoring/device/{id}/` | Get device monitoring status | ## Key resources - **Devices** — Register, update, and delete network devices managed by the controller - **Templates** — Configuration templates applied to devices or device groups - **VPN** — VPN servers used to reach remote devices - **Commands** — Send shell or system commands to a device and review history - **IPAM** — Subnet management and next-available-IP allocation - **Monitoring** — Device monitoring status and health checks - **Network Topology** — Graph data describing how devices are connected ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 59 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 52 / 100 - Developer Experience & Jentic Compatibility: 61 / 100 - AI-Readiness & Agent Experience: 52 / 100 - Agent Usability: 94 / 100 - Security: 55 / 100 - AI Discoverability: 51 / 100 - **View full report:** https://jentic.com/apis/openwisp.org/openwisp/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the OpenWISP Controller API by hand means pointing at your own controller host, sending its bearer token on every call, and keeping device, template, VPN, and IPAM routes straight. Through Jentic you install once, import the OpenWISP Controller API from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** OpenWISP puts the resource id in the URL path (`/controller/device/{id}/...`), so a rule can pin your agent to one device: it can read that device's monitoring data and nothing else. You choose the operations it may call, so actions like sending a command or creating a template are not included unless you add them. - **Credential handling:** Your OpenWISP bearer token is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list openwisp devices' or 'send a command to a router', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Cisco Meraki Dashboard API** — Commercial cloud-managed networking API for Meraki access points, switches, and security appliances - **Cisco DNA Center API** — Enterprise network controller API for Cisco Catalyst infrastructure - **PagerDuty** — Incident response platform commonly paired with network monitoring ## FAQ ### Why is there no official OpenAPI spec for OpenWISP Controller API? OpenWISP does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call OpenWISP Controller API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the OpenWISP Controller API use? The API accepts an HTTP bearer token obtained from `/api/v1/auth/token`/ on the OpenWISP host. Through Jentic the token is stored encrypted in the vault and injected as the Authorization header at execution time, so the agent never sees the credential. ### Can I push configuration templates to many devices at once with this API? Yes. Create or update a template under `/controller/template`/ and assign it to a device group via `/controller/device-group`/, which applies the template to every device in the group. There is no single bulk endpoint for assigning a template to an arbitrary list of devices - group membership is the standard mechanism. ### What are the rate limits for the OpenWISP Controller API? OpenWISP is self-hosted, so rate limits are governed by the deployment's reverse proxy or Django settings rather than the spec. Treat 429 and 503 responses as backoff signals and tune limits in your own nginx or HAProxy configuration. ### How do I send a remote reboot command through Jentic? Search Jentic for 'send a command to an openwisp device', load the POST `/controller/device/{id}/command`/ operation, and pass type=reboot in the body. Poll the GET form of the same path for command history and final status. ### Does this API include monitoring metrics like CPU and memory? The `/monitoring/device/{id}`/ endpoint returns the rolled-up monitoring status for a device. Detailed time-series metrics live in the OpenWISP Monitoring module's separate endpoints, which are not part of this Controller API specification. ### Can I limit what my agent is allowed to do with the OpenWISP Controller API? Yes. Jentic One runs self-hosted, so your own rules decide which OpenWISP operations and credentials the agent may use. Because OpenWISP puts the resource id in the URL path, such as `/controller/device/{id}`/, you can pin the agent to a single device so it reads that device's monitoring data and nothing else. You also choose the operations it may call, so write actions like POST `/controller/device/{id}/command`/ or creating a template under `/controller/template`/ stay off limits until you add them.