HTTP API

This document describes the NervesHub web API endpoints.

You can also view the latest OpenAPI Spec on Github.

Fetch information about a device.

get

If the device is currently online, there will be firmware_metadata describing active firmware.

Authorizations

Path parameters

idstring · uuidRequired

Responses

application/json

objectOptional

Fetch a device's information. You can learn about the update status of the device via the firmware_metadata and deployment keys.

firmware_metadata map has the UUID and version of the active firmware.

deployment contains information about what firmware version and UUID should eventually be running on the device.

application/json

get

HTTPcURLJavaScriptPython

GET /api/devices/{id} HTTP/1.1
Host: localhost:4000
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "connection_status": "connected",
    "connection_established_at": "2025-04-19T13:22:17.445Z",
    "connection_disconnected_at": "2025-04-19T13:22:17.445Z",
    "connection_last_seen_at": "2025-04-19T13:22:17.445Z",
    "deployment": {
      "name": "production",
      "is_active": true,
      "firmware_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "firmware_version": "1.2.1"
    },
    "description": "A device",
    "firmware_metadata": {
      "architecture": "arm",
      "author": "The Nerves Team",
      "description": "Sensors platform",
      "fwup_version": "1.2.1",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "misc": "text",
      "platform": "rpi",
      "product": "sensors",
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "vcs_identifier": "text",
      "version": "1.2.1"
    },
    "firmware_update_status": "latest",
    "identifier": "NH1234",
    "last_communication": "2025-04-19T13:22:17.445Z",
    "online": true,
    "org_name": "nerveshub",
    "product_name": "sensors",
    "tags": [
      "rpi",
      "production"
    ],
    "updates_blocked_until": "2025-04-19T13:22:17.445Z",
    "updates_enabled": true,
    "version": "1.2.1"
  }
}

List all firmware signing keys for the organization

get

Authorizations

Query parameters

orgstringOptionalExample: nerveshub

Responses

application/json

objectOptional

get

HTTPcURLJavaScriptPython

GET /api/orgs/{org}/keys HTTP/1.1
Host: localhost:4000
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "data": [
    {
      "name": "test",
      "key": "h8L1FcfK8mUSnIvM0rffjoapItsI4fimIU9x9Jq2TdU="
    }
  ]
}

Add a new firmware signing key

post

Authorizations

Query parameters

orgstringOptionalExample: nerveshub

Body

namestringOptionalExample: test

keystringOptionalExample: h8L1FcfK8mUSnIvM0rffjoapItsI4fimIU9x9Jq2TdU=

Responses

application/json

objectOptional

post

HTTPcURLJavaScriptPython

POST /api/orgs/{org}/keys HTTP/1.1
Host: localhost:4000
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "name": "test",
  "key": "h8L1FcfK8mUSnIvM0rffjoapItsI4fimIU9x9Jq2TdU="
}

200

OK

{
  "data": {
    "name": "test",
    "key": "h8L1FcfK8mUSnIvM0rffjoapItsI4fimIU9x9Jq2TdU="
  }
}

View information about the authenticated user

get

Authorizations

Responses

application/json

objectOptional

get

HTTPcURLJavaScriptPython

GET /api/users/me HTTP/1.1
Host: localhost:4000
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

OK

{
  "username": "nerveshub",
  "email": "[e-mail]"
}