Blues Notehub

Rename Notehub devices by module IMEI (batch)

post

Renames Qubitro devices by matching each supplied Notehub module IMEI against the device's stored Notehub id (metadata.note_device). Intended to sync device names from an external source (e.g. an Airtable "IMEI -> title" table) without a human editing each device.

Matching:

• Pass the bare IMEI (e.g. 868531063306018); the dev: prefix Notehub uses is applied automatically.

• Matching is scoped to the authenticated customer (your API key), across all of your projects. If the key is restricted to a single project, only devices in that project are considered.

Behaviour:

• The endpoint never creates devices. A device only exists after Notehub delivers its first packet, so IMEIs whose device has not been created yet return not_found — re-run the sync later and they will be picked up. This makes the endpoint safe to call on a schedule.

• Devices already carrying the requested name and the requested metadata are reported unchanged and are not rewritten.

• metadata, when provided, replaces the device's existing custom metadata (same semantics as PUT device update).

• Sending the same IMEI more than once in a batch is allowed; the last entry wins, and every entry is reported against the device's state as it was before the batch began.

• A batch is capped at 1000 devices. Split larger fleets across sequential requests; there is no cross-request state, so any split is safe.

Per-item status: renamed, unchanged, not_found, ambiguous (more than one device matched the IMEI), invalid (missing imei/name), or error. Treat this set as open — handle unrecognised values gracefully, because new statuses may be introduced.

Identifying devices: every result that resolved to a device — renamed, unchanged and error — carries device_id, project_id and device_url (a direct link to the device in your portal, using your own domain if you are white-labelled). An ambiguous result lists each candidate under matches. not_found and invalid carry no identifiers because no device exists to identify. This means a single request is enough to sync names and collect links; no follow-up lookups are required.

• device_url opens the device's own page in the portal. It is not a link to a Dashboard: dashboards are a separate resource, and a device may have several or none.

• device_url is a best-effort convenience. It may be absent if the link cannot be resolved, and it may redirect if portal routing changes, so treat its absence as "no link available" rather than as information about the device. device_id and project_id are always present for a matched device.

Dry run: send "dry_run": true to get the full per-device report without writing anything. Statuses and counters are identical to a real run, so a dry run is an exact rehearsal of the matching and classification a real run performs — renamed means "would be attempted". It does not prove the write itself would succeed, so error never appears in a dry run. The response always echoes dry_run; check it before trusting a report, because a misspelled flag is simply ignored and the run is real.

Stability: this endpoint is supported and safe to build automations against. Changes will be additive — new fields may appear, but existing fields, status values and semantics will not change or be removed without advance notice to affected customers. matched_device_ids is deprecated in favour of matches and will continue to be returned.

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Body

dry_runbooleanOptional

Report what would happen without writing anything

Responses

200

Per-item rename report

application/json

actionstringOptional

Action that was performed

Example: get blob list

messagestringOptional

Human-readable message (often empty on success)

statusintegerOptional

HTTP status code

Example: 200

successbooleanOptional

Operation completed successfully

Example: true

400

Invalid request body - devices array empty or exceeds 1000

application/json

401

Unauthorized - Invalid or missing API key

application/json

403

Forbidden - API key missing 'update' scope

application/json

post/v2/devices/rename-by-imei

POST /v2/devices/rename-by-imei HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 152

{
  "devices": [
    {
      "imei": "868531063306018",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "name": "D5709 - Georgia Pacific | 12V18AH+25W"
    }
  ],
  "dry_run": true
}

{
  "action": "get blob list",
  "data": {
    "ambiguous": 1,
    "dry_run": true,
    "errors": 1,
    "invalid": 1,
    "not_found": 1,
    "renamed": 1,
    "requested": 1,
    "results": [
      {
        "device_id": "text",
        "device_url": "text",
        "imei": "text",
        "matched_device_ids": [
          "text"
        ],
        "matches": [
          {
            "current_name": "text",
            "device_id": "text",
            "device_url": "text",
            "project_id": "text"
          }
        ],
        "message": "text",
        "name": "text",
        "project_id": "text",
        "status": "text"
      }
    ],
    "unchanged": 1
  },
  "message": "",
  "status": 200,
  "success": true
}

Get device environment variables from Blues Notehub

get

Retrieves environment variables for a Blues Notehub device. This endpoint proxies the request to the Blues Notehub API using your organization's stored Notehub PAT credential.

Prerequisites:

• Device must be a Blues Notehub device (source_type: "notehub")

• Organization must have a Notehub PAT credential configured in External Credentials

• API key must have "read" scope permission

How it works:

1. Validates your Qubitro API key and extracts your organization

2. Looks up the Notehub PAT credential stored in your organization's external credentials

3. Fetches the device to get its Notehub device UID

4. Proxies the request to Blues Notehub API

5. Returns the environment variables from Notehub

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters

project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7

device_idstringRequired

Device ID (UUID format)

Example: dev-abc123

Responses

200

Environment variables retrieved successfully

application/json

actionstringOptional

Action that was performed

Example: get blob list

messagestringOptional

Human-readable message (often empty on success)

statusintegerOptional

HTTP status code

Example: 200

successbooleanOptional

Operation completed successfully

Example: true

400

Device is not a Blues Notehub device

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Device not found

application/json

424

Notehub PAT credential not configured for this organization

application/json

502

Blues Notehub API returned an error

application/json

get/v2/projects/{project_id}/devices/{device_id}/blues/environment-variables

GET /v2/projects/{project_id}/devices/{device_id}/blues/environment-variables HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "action": "get blob list",
  "data": {
    "environment_variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "message": "",
  "status": 200,
  "success": true
}

Set device environment variables in Blues Notehub

put

Sets environment variables for a Blues Notehub device. This endpoint proxies the request to the Blues Notehub API using your organization's stored Notehub PAT credential.

Prerequisites:

• Device must be a Blues Notehub device (source_type: "notehub")

• Organization must have a Notehub PAT credential configured in External Credentials

• API key must have "update" scope permission

• Notehub PAT must have at least "developer" role permissions

How it works:

1. Validates your Qubitro API key and extracts your organization

2. Looks up the Notehub PAT credential stored in your organization's external credentials

3. Fetches the device to get its Notehub device UID

4. Proxies the request to Blues Notehub API to set the environment variables

5. Returns success if the variables were set

Note: Environment variables set via this endpoint will be synchronized to the Notecard device on its next sync with Notehub.

Authorizations

AuthorizationstringRequired

Enter your API key with the Bearer prefix, e.g. "Bearer QB_your_api_key_here"

Path parameters

project_idstringRequired

Project ID (UUID format)

Example: 3e5c0246-c759-48e8-8345-27db13f11ff7

device_idstringRequired

Device ID (UUID format)

Example: dev-abc123

Body

Responses

200

Environment variables set successfully

application/json

actionstringOptional

Action that was performed

Example: delete device

messagestringOptional

Human-readable success message

Example: Operation completed successfully

statusintegerOptional

HTTP status code

Example: 200

successbooleanOptional

Operation completed successfully

Example: true

400

Invalid request body or device is not a Blues Notehub device

application/json

401

Unauthorized - Invalid or missing API key

application/json

404

Device not found

application/json

424

Notehub PAT credential not configured for this organization

application/json

502

Blues Notehub API returned an error

application/json

put/v2/projects/{project_id}/devices/{device_id}/blues/environment-variables

PUT /v2/projects/{project_id}/devices/{device_id}/blues/environment-variables HTTP/1.1
Host: api.qubitro.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 82

{
  "environment_variables": {
    "firmware_version": "1.2.3",
    "monitoring_interval": "300"
  }
}

{
  "action": "delete device",
  "message": "Operation completed successfully",
  "status": 200,
  "success": true
}