canonical: https://jentic.com/apis/clearblade.com/clearblade

# ClearBlade API

ClearBlade is an industrial IoT platform, and its REST API exposes the platform's full operational surface across systems, devices, collections, code services, message-passing, and developer administration. With over 220 endpoints, the API covers everything from provisioning a new system and registering devices to running data queries, sending MQTT messages, and rotating device keys. Operations are grouped under admin, codes, data, devices, edges, and message-history namespaces, reflecting the platform's multi-tenant edge-and-cloud architecture. It is designed for industrial operators, OEMs, and IoT solution builders who need full programmatic control over a fleet.

## For AI agents

Provision ClearBlade systems, register and update devices, run data collection queries, execute code services, and inspect message history. Useful for industrial IoT fleet management and edge orchestration.

## Scope

Does not handle physical hardware manufacturing, cellular connectivity provisioning, or end-customer billing - use for ClearBlade IoT platform device, system, and code service operations only.

## Capabilities

- Provision and configure ClearBlade systems and developer accounts
- Register, query, update, and delete devices in bulk or individually
- Manage data collections including create, update, and delete operations
- Trigger and inspect server-side code services and triggers
- Rotate device authentication keys for security compliance
- Pull audit logs and device activity history from a system
- Inspect MQTT message history and topic activity

## Use cases

### Bulk device provisioning for a new deployment

When rolling out a new IoT deployment, operations teams need to register hundreds or thousands of devices into the ClearBlade system. POST /admin/devices/{systemKey}/{name} creates devices and POST /admin/devices/keys/{systemKey}/{deviceName} provisions their rotating authentication keys. Running these in batches against the platform avoids manually clicking through the console for each device and keeps the device registry as the canonical source.

Example prompt: For each row in the device manifest CSV, call POST /admin/devices/{systemKey}/{name} then POST /admin/devices/keys/{systemKey}/{deviceName} to create rotating keys

### Audit log export for compliance reporting

Compliance teams in regulated industries need device and platform audit data exported into their SIEM. GET /admin/audit and GET /admin/audit/{systemKey} return the audit log for a system, with /count variants for pagination planning. Scheduling this nightly into a SIEM gives auditors a continuous record without needing console access to ClearBlade.

Example prompt: Each night, call GET /admin/audit/{systemKey} for the production system, paginate based on the /count endpoint, and forward the records to the Splunk HEC endpoint

### Stale device cleanup

Fleets accumulate stale devices that no longer report telemetry. GET /admin/devices/{systemKey} with a query filter identifies devices that have not connected recently, and DELETE /admin/devices/{systemKey} removes them in bulk. Running this monthly keeps device counts and license usage aligned with the active fleet.

Example prompt: Find all devices in the production system with last_active older than 90 days using GET /admin/devices/{systemKey}, then call DELETE /admin/devices/{systemKey} with the matching query

### Code service trigger inspection

When a code service misfires, debugging often starts with checking which triggers reference it and what audit entries describe its recent runs. The admin endpoints expose service-trigger relationships and the audit endpoints expose execution history. Pulling both together gives a clear view of which triggers fire which services and how often they error.

Example prompt: List the code services registered for system 'prod-system' and pull their recent audit entries via GET /admin/audit/{systemKey} to identify the failing trigger

### AI agent integration via Jentic

An IoT operations agent uses Jentic to discover ClearBlade endpoints by intent and orchestrate fleet operations from natural-language requests. Because the API key auth is held in your Jentic One instance, the agent can be deployed to operations engineers without distributing platform credentials. The same agent can register devices, rotate keys, and query audit logs by re-running searches on different intents.

Example prompt: Receive 'rotate keys for device gateway-42' from chat, search Jentic for ClearBlade device key rotation, and execute POST /admin/devices/keys/{systemKey}/{deviceName} for that device

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /admin/devices/{systemKey}/{name} | Create a device in a system |
| GET | /admin/devices/{systemKey} | Query devices in a system |
| POST | /admin/devices/keys/{systemKey}/{deviceName} | Create rotating keys for a device |
| GET | /admin/audit/{systemKey} | Get system audit information |
| POST | /admin/auth | Authenticate developer credentials |
| POST | /admin/collectionmanagement | Create a data collection |
| GET | /admin/allsystems | List all systems |
| DELETE | /admin/devices/{systemKey} | Delete devices using a query |

## Key resources

- **Systems** — ClearBlade systems - top-level multi-tenant containers
- **Devices** — Register, query, update, and delete IoT devices
- **Device Keys** — Provision and rotate device authentication keys
- **Collections** — Data collection management for telemetry storage
- **Audit** — System and device audit logs
- **Code Services** — Server-side code execution and triggers
- **Developers** — Admin developer account management
- **Database Status** — Internal and external database health

## Why Jentic

- **Setup:** Wiring the ClearBlade API by hand means managing its API key auth and threading the system key through calls to platform.clearblade.com across its large IoT operation set. Through Jentic you install once, import ClearBlade from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** ClearBlade puts the system key in the URL path (/admin/devices/{systemKey}), so a rule can pin your agent to one system: it can register and list devices there and nothing else. You choose the operations it may call, so deleting devices is not included unless you add it.
- **Credential handling:** Your ClearBlade API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'register a device' or 'list devices for a system in ClearBlade', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Particle API** — Connected device platform with strong cellular IoT story
- **Samsara API** — Connected operations and fleet telematics platform
- **Adafruit IO API** — Hobbyist and prototyping IoT platform

## FAQ

### What authentication does the ClearBlade API use?

ClearBlade uses an API key passed in request headers, with developer-level authentication issued via POST /admin/auth and verified via POST /admin/checkauth. The OpenAPI spec does not declare the security scheme inline, so the auth header is configured at the request level. Through Jentic, both the platform credentials and per-system tokens are stored in the encrypted vault.

### Can I register devices in bulk through the ClearBlade API?

Yes. POST /admin/devices/{systemKey}/{name} creates a single device, and the corresponding GET, PUT, and DELETE on /admin/devices/{systemKey} accept queries for bulk operations. For new deployments, you typically iterate through your device manifest and call the create endpoint for each entry.

### How do I rotate device authentication keys?

Call POST /admin/devices/keys/{systemKey}/{deviceName} to create a new rotating key, and DELETE /admin/devices/keys/{systemKey}/{deviceName} to revoke an existing one. This is the standard pattern for periodic key rotation in regulated IoT deployments.

### How do I export ClearBlade audit logs through Jentic?

Install the SDK with pip install jentic, search Jentic for 'get clearblade audit logs', load the schema, and execute against GET /admin/audit/{systemKey}. Use the matching /count endpoint to plan pagination, then forward records to your SIEM.

### Does the ClearBlade API expose MQTT message history?

Yes. The platform stores MQTT topic and message history that can be queried through admin endpoints, alongside the data collection endpoints for telemetry storage. This gives you both the realtime broker view and the historical record without leaving the platform.

### Are ClearBlade systems multi-tenant?

Yes. Each system has its own systemKey and admin operations are scoped to that key. Developers with access to multiple systems can iterate via GET /admin/allsystems and act on each system in turn, which is the standard fan-out pattern for managed-service operators.

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

Yes. Because Jentic One is self-hosted and you write the rules, you decide which ClearBlade operations and credentials your agent may use. Since the system key sits in the URL path (/admin/devices/{systemKey}), a rule can pin the agent to a single system so it can register and list devices there and nothing else. Destructive calls like DELETE /admin/devices/{systemKey} stay out of reach unless you explicitly grant them.