canonical: https://jentic.com/apis/blues.io/blues-io

# Blues Notehub API

Jentic publishes the only available OpenAPI specification for Blues Notehub API, keeping it validated and agent-ready. This blues.io listing covers the broader 81-endpoint Notehub surface, including projects, products, fleets, devices, notes, events, routes, monitors, environment variables, firmware updates, billing accounts, and usage data. Notehub is the cloud counterpart to the Blues Notecard cellular module, and the API supports remote firmware delivery, per-device enable and disable, and full lifecycle management for cellular IoT deployments. Authentication uses Bearer tokens obtained from /oauth2/token.

## For AI agents

Manage Blues Notecard cellular IoT devices end-to-end: provisioning, fleets, environment variables, event routing, firmware, and billing through Notehub.

## Scope

Does not flash firmware locally over USB, send cellular data plans, or expose raw modem AT commands - use for cloud-side fleet, firmware, route, and event management against Notehub only.

## Capabilities

- Provision, enable, and disable individual Notecard devices remotely
- Push environment variables down to a project, fleet, or specific device
- Read and write Notes - the per-device data records exchanged between firmware and cloud
- Configure routes that forward incoming events to AWS, Azure, MQTT, or HTTP targets
- Schedule firmware updates and track deployment progress across a fleet
- Set up monitors that alert on device dropout, route failure, or condition breach
- Read billing account usage to track per-device cellular data consumption

## Use cases

### Remote firmware rollout

Push firmware updates to fielded Notecard devices through Notehub's firmware endpoints. Upload the firmware artifact, target a fleet or specific devices, and monitor rollout progress. The /v1/projects/{projectOrProductUID}/firmware endpoints handle artifact management and assignment, with Notehub coordinating delivery as devices check in. Suitable for OTA rollouts to remote and battery-constrained hardware where in-person updates are impractical.

Example prompt: Upload a firmware binary, then call the firmware assignment endpoint to target a fleet and confirm the rollout was created.

### Per-device troubleshooting

Investigate a single misbehaving Notecard by pulling its events, environment variables, and current state. GET /v1/projects/{projectOrProductUID}/devices/{deviceUID} returns identity and last-seen, while POST /v1/projects/{projectOrProductUID}/devices/{deviceUID}/disable temporarily takes it out of the fleet. Re-enable via the corresponding POST .../enable endpoint after the issue is resolved.

Example prompt: Call GET /v1/projects/{projectOrProductUID}/devices/{deviceUID} for a flagged device, then POST /v1/projects/{projectOrProductUID}/devices/{deviceUID}/disable to take it offline pending investigation.

### Environment-variable-driven feature flags

Roll out feature flags to fielded devices through scoped environment variables. Variables can be set at project, fleet, or device level, with the most specific scope winning. PUT /v1/projects/{projectOrProductUID}/devices/{deviceUID}/environment_variables targets one device; the fleet variant targets a group; the project variant becomes the default. Useful for staged rollouts of firmware behaviour without recompiling.

Example prompt: Call PUT /v1/projects/{projectOrProductUID}/devices/{deviceUID}/environment_variables with {beta_features: 'on'} to enable a beta build's flags on a single device.

### Cellular data cost monitoring

Track cellular data consumption across a deployment by reading billing accounts and usage. GET /v1/billing-accounts lists accounts and limits, and per-project usage endpoints return event and byte counts. Useful for finance and operations teams who need to attribute Blues cellular costs back to specific projects or fleets.

Example prompt: Call GET /v1/billing-accounts and return each account's name, current period consumption, and hard limit.

### AI agent IoT operations assistant

Let an AI agent take operational actions against a Blues fleet - pulling device status, disabling problem units, or rolling environment variables. The agent searches Jentic for the right Notehub operation by intent, loads the schema, and executes with the Bearer token held in your Jentic One instance. Suitable for ops chatbots, customer support copilots, and on-call investigation agents.

Example prompt: Search Jentic for 'disable a Notecard device', load the schema, and execute it for the deviceUID flagged by upstream monitoring.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /oauth2/token | Exchange a Personal Access Token for an OAuth bearer token |
| GET | /v1/projects/{projectOrProductUID}/devices | List devices in a project |
| POST | /v1/projects/{projectOrProductUID}/devices/{deviceUID}/disable | Disable a specific Notecard device |
| POST | /v1/projects/{projectOrProductUID}/devices/{deviceUID}/enable | Re-enable a disabled device |
| PUT | /v1/projects/{projectOrProductUID}/devices/{deviceUID}/environment_variables | Set per-device environment variables |
| POST | /v1/projects/{projectOrProductUID}/fleets | Create a fleet within a project |
| GET | /v1/billing-accounts | List billing accounts and usage |

## Key resources

- **Projects** — Top-level container for IoT deployments with members, fleets, and environment variables
- **Products** — Product groupings within a project for managing device classes
- **Fleets** — Logical device groups for targeted configuration, firmware, and monitoring
- **Devices** — Individual Notecard records with state, environment variables, enable/disable, and event history
- **Notes** — Per-device data records exchanged between firmware and cloud
- **Events** — Incoming event stream queryable per project, fleet, or device
- **Routes** — Outbound delivery rules to AWS, Azure, MQTT, or HTTP targets with JSONata transforms
- **Firmware** — Upload and assign firmware artifacts to fleets or devices
- **Monitors** — Conditional alerts on device state and route delivery
- **Billing Accounts** — Cellular data usage and billing summaries

## Why Jentic

- **Setup:** Wiring the Blues Notehub API by hand means exchanging your personal access token at /oauth2/token for a bearer and threading project and device ids through each call yourself. Through Jentic you install once, import Notehub from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Notehub puts the project and device ids in the URL path (/v1/projects/{projectOrProductUID}/devices/{deviceUID}), so a rule can pin your agent to one project or device: it can read devices or set environment variables there and nothing else. You choose the operations it may call, so disabling a device is not included unless you add it.
- **Credential handling:** Your Blues personal access token is stored once, encrypted, by your own Jentic One instance and injected at execution time, and the token exchange runs there too. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list Notehub devices in a project' or 'create a fleet', and Jentic returns the matching Notehub operation with its input schema so the agent calls the right endpoint without browsing dev.blues.io.

## Related APIs

- **Blues Notehub API** — Sister Notehub listing covering the 72-endpoint core surface
- **Blynk** — IoT platform with mobile app and dashboards - alternative for Wi-Fi/BLE prosumer hardware
- **Blueshift** — Customer engagement platform - pair when IoT events should drive customer-facing notifications

## FAQ

### Why is there no official OpenAPI spec for Blues Notehub API?

Blues publishes a Notehub API reference site but does not distribute a maintained OpenAPI 3 file. Jentic generates and maintains this spec so AI agents and developers can call Notehub via standard tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Blues Notehub API use?

Notehub uses HTTP Bearer authentication. Exchange a Personal Access Token for an OAuth bearer token via POST /oauth2/token, then pass it as Authorization: Bearer <token>. Through Jentic, the PAT is held in the encrypted vault and the OAuth exchange happens automatically at execution time.

### Can I push firmware updates through this API?

Yes. Notehub exposes firmware management endpoints that let you upload an artifact and assign it to a fleet or specific devices. Devices fetch the update on their next check-in, and you can monitor rollout state via the firmware status endpoints.

### What are the rate limits for the Blues Notehub API?

Notehub applies per-account rate limits not enumerated in the spec. Published guidance is to keep request volume under roughly 60 requests per minute per token; HTTP 429 responses include backoff hints. Higher limits are available for enterprise customers on request.

### How do I disable a misbehaving device through Jentic?

Search Jentic for 'disable a Notecard device', load the schema for POST /v1/projects/{projectOrProductUID}/devices/{deviceUID}/disable, and execute it with the deviceUID. Install with pip install jentic and call await client.execute(ExecutionRequest(...)).

### How is this listing different from the blues vendor entry?

Both expose the same Blues Notehub API. The blues.io listing covers the broader 81-endpoint surface including firmware, notes, and per-device enable/disable; the blues listing covers a 72-endpoint subset focused on the core project, fleet, device, and routing operations.

### Is the Blues Notehub API free?

Notehub offers a free developer tier sufficient for prototyping with caps on devices, monthly events, and data egress. Paid tiers scale device count and event volume, billed per the active billing account configured in Notehub.

### Can I limit what my agent is allowed to do with the Blues Notehub API?

Yes. Because you run Jentic One yourself, your own rules decide which Notehub operations and credentials the agent may use. Notehub puts the project and device ids in the URL path, such as /v1/projects/{projectOrProductUID}/devices/{deviceUID}, so you can pin the agent to a single project or device and let it read devices or set environment variables there and nothing else. Sensitive operations like disabling a Notecard via POST .../devices/{deviceUID}/disable are only callable if you explicitly add them to the agent's allowed set.