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.

get

/devices/{id}

Authorizations

Path parameters

idstring · uuidrequired

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:4000/api/devices/{id}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

404

200

{
  "data": {
    "connection_status": "connected",
    "connection_established_at": "2025-02-23T12:43:57.764Z",
    "connection_disconnected_at": "2025-02-23T12:43:57.764Z",
    "connection_last_seen_at": "2025-02-23T12:43:57.764Z",
    "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"
    },
    "identifier": "NH1234",
    "last_communication": "2025-02-23T12:43:57.764Z",
    "online": true,
    "org_name": "nerveshub",
    "product_name": "sensors",
    "updates_blocked_until": "2025-02-23T12:43:57.764Z",
    "updates_enabled": true,
    "version": "1.2.1",
    "firmware_update_status": "latest",
    "tags": [
      "rpi",
      "production"
    ]
  }
}

OK

List all firmware signing keys for the organization

get

/orgs/{org}/keys

Authorizations

Query parameters

orgstring

Example: nerveshub

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:4000/api/orgs/{org}/keys' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

200

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

OK

Add a new firmware signing key

post

/orgs/{org}/keys

Authorizations

Query parameters

orgstring

Example: nerveshub

Body

namestring

Example: test

keystring

Example: h8L1FcfK8mUSnIvM0rffjoapItsI4fimIU9x9Jq2TdU=

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'http://localhost:4000/api/orgs/{org}/keys' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"name":"test","key":"h8L1FcfK8mUSnIvM0rffjoapItsI4fimIU9x9Jq2TdU="}'

200

200

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

OK

View information about the authenticated user

get

/users/me

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'http://localhost:4000/api/users/me' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

200

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

OK