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.

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

GEThttp://localhost:4000/api/devices/{id}

Path parameters

id*string (uuid)

Response

200404

OK

Body

application/json

datadevice (object)

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:4000/api/devices/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200404

{
  "data": {
    "connection_status": "connected",
    "connection_established_at": "2024-11-21T10:58:29.236Z",
    "connection_disconnected_at": "2024-11-21T10:58:29.236Z",
    "connection_last_seen_at": "2024-11-21T10:58:29.236Z",
    "deployment": {
      "name": "production",
      "is_active": false,
      "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": "2024-11-21T10:58:29.236Z",
    "online": false,
    "org_name": "nerveshub",
    "product_name": "sensors",
    "tags": [
      "rpi",
      "production"
    ],
    "updates_blocked_until": "2024-11-21T10:58:29.236Z",
    "updates_enabled": false,
    "version": "1.2.1"
  }
}

List all firmware signing keys for the organization

GEThttp://localhost:4000/api/orgs/{org}/keys

Query parameters

Response

200

OK

Body

application/json

dataarray of object

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:4000/api/orgs/{org}/keys', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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

Add a new firmware signing key

POSThttp://localhost:4000/api/orgs/{org}/keys

Query parameters

Body

application/json

namestring

Example: "test"

keystring

Example: "h8L1FcfK8mUSnIvM0rffjoapItsI4fimIU9x9Jq2TdU="

Response

200

OK

Body

application/json

datafirmware_key (object)

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:4000/api/orgs/{org}/keys', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

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

View information about the authenticated user

GEThttp://localhost:4000/api/users/me

Response

200

OK

Body

application/json

usernamestring

Example: "nerveshub"

emailstring

Example: "[e-mail]"

Request

JavaScriptCurlPython

const response = await fetch('http://localhost:4000/api/users/me', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

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