REST API Overview

NervesHub provides a REST API covering devices, firmware, deployment groups, products, organizations, signing keys, support scripts and more. Whether you are automating firmware releases in CI or building a custom dashboard, the API lets you integrate NervesHub into any workflow. The Endpoints section in the sidebar is generated directly from the server’s OpenAPI specification, so it always matches what the API actually accepts. This page covers what the specification does not: base URLs, how responses are shaped, and what each status code means.

Base URL

All API requests are made over HTTPS. The base URL depends on how you host NervesHub:

Environment	Base URL
NervesCloud (managed)	`https://manage.nervescloud.com`
Self-hosted	Your server URL, e.g. `https://nerveshub.example.com`

Every endpoint path is appended directly to the base URL:

https://manage.nervescloud.com/api/orgs/{org_name}/products/{product_name}/devices

OpenAPI Specification

The server generates its own OpenAPI document and serves it, so it is never out of step with the running code:

Spec document: https://manage.nervescloud.com/api/openapi
Interactive docs: https://manage.nervescloud.com/api/docs

Both paths are relative to your base URL, so a self-hosted instance serves its own spec at https://nerveshub.example.com/api/openapi. Import it into Postman, Insomnia, a code generator, or anything else that reads OpenAPI.

The endpoint reference in this section is built from NervesCloud’s specification. A self-hosted deployment exposes the same API, but if you are running an older version, fetch the spec from your own instance to see exactly what it offers.

URL Structure

All resource paths follow a consistent hierarchy anchored to an organization and, for most resources, a product:

/api/orgs/{org_name}/products/{product_name}/{resource}

For example:

GET /api/orgs/acme/products/smart-lock/devices
GET /api/orgs/acme/products/smart-lock/firmwares/{uuid}
GET /api/orgs/acme/products/smart-lock/deployments/{name}

Org-level resources (CA certificates, signing keys, products) omit the product segment:

GET /api/orgs/acme/products
GET /api/orgs/acme/ca_certificates
GET /api/orgs/acme/keys

The deployments path manages what the web console calls deployment groups. The path name is kept for backwards compatibility.

Response Format

All responses are JSON. Successful responses wrap the payload in a data key:

{
  "data": {
    "identifier": "device-001",
    "status": "online"
  }
}

List responses return an array under data:

{
  "data": [
    { "identifier": "device-001", "status": "online" },
    { "identifier": "device-002", "status": "offline" }
  ]
}

Error responses return an error or errors key:

{ "error": "unauthorized" }

{
  "errors": {
    "identifier": ["can't be blank"]
  }
}

HTTP Status Codes

Code	Meaning	When it occurs
`200 OK`	Success	Request succeeded; body contains result
`201 Created`	Resource created	POST succeeded; body contains new resource
`204 No Content`	Deleted successfully	DELETE succeeded; no response body
`400 Bad Request`	Invalid request parameters	Malformed JSON, missing required fields
`401 Unauthorized`	Invalid or missing token	No `Authorization` header or expired token
`403 Forbidden`	Insufficient permissions	Token is valid but lacks the required role
`404 Not Found`	Resource not found	Org, product, device, or firmware does not exist
`422 Unprocessable Entity`	Validation errors	Fields present but fail business-logic validation
`500 Internal Server Error`	Server error	Unexpected server-side failure

Before making API calls, you need a Bearer token. See Authentication for instructions on generating and using API tokens.

HTTP API

Endpoints

Device WebSocket

Base URL

OpenAPI Specification

URL Structure

Response Format

HTTP Status Codes

​Base URL

​OpenAPI Specification

​URL Structure

​Response Format

​HTTP Status Codes

Base URL

OpenAPI Specification

URL Structure

Response Format

HTTP Status Codes