canonical: https://jentic.com/apis/golioth.io/golioth

# Golioth API

Jentic publishes the only available OpenAPI specification for Golioth API, keeping it validated and agent-ready. Provision, monitor, and control MCU-based IoT devices through a cloud platform that provides LightDB state storage, LightDB Stream for time-series telemetry, OTA firmware updates via releases and artifacts, device-level RPC calls, and data routing through configurable integrations. The API spans 106 endpoints organized around projects, devices, credentials, blueprints, releases, settings, and cloud-to-device data operations.

## For AI agents

Provision MCU devices, push OTA firmware updates, store and query device state via LightDB, stream telemetry data, and invoke remote procedure calls on Golioth-connected hardware.

## Scope

Does not handle device-side firmware development, RTOS scheduling, or hardware peripheral drivers - use for cloud-side device management, data storage, and OTA orchestration only.

## Capabilities

- Push over-the-air firmware updates to device fleets using releases and artifact management
- Store and retrieve structured device state data via LightDB path-based API
- Stream time-series telemetry from devices and query historical sensor data
- Invoke remote procedure calls on individual MCU devices for on-demand actions
- Route device data to external services through configurable webhook and cloud integrations
- Provision devices with X.509 certificates or pre-shared key credentials for mutual TLS

## Use cases

### AI Agent OTA Firmware Deployment

AI agents orchestrate firmware rollouts across MCU device fleets through Jentic's intent search. An agent searches for 'push firmware update to IoT devices', discovers the POST /v1/projects/{projectId}/releases endpoint, creates a release linked to a pre-uploaded artifact, and monitors device-level firmware logs to confirm successful application. Jentic handles API key authentication and project-scoped resource addressing automatically.

Example prompt: Upload an artifact for firmware v2.1.0, create a release targeting devices with blueprint 'sensor-node', and check firmware logs to confirm 3 devices applied the update

### Device State Management with LightDB

Store and query structured device state using Golioth's LightDB path-based API. Each device exposes a JSON state tree accessible via GET, POST, PUT, PATCH, and DELETE operations on /v1/projects/{projectId}/devices/{deviceId}/data/{path}. Agents can read sensor configurations, set desired state for actuators, and synchronize cloud-side state with device-reported state - enabling digital twin patterns for MCU hardware without custom server infrastructure.

Example prompt: Write the desired state '{"led": "on", "brightness": 80}' to device abc123 at path '/desired/display' and then read back the reported state at '/reported/display' to confirm synchronization

### Time-Series Telemetry Collection

Collect and query historical sensor data through LightDB Stream endpoints. Devices push telemetry via the Golioth SDK, and the cloud API exposes GET /v1/projects/{projectId}/devices/{deviceId}/stream for paginated retrieval and POST /v1/projects/{projectId}/stream for project-wide queries. Data can be routed to external time-series databases through integrations for long-term retention and analytics.

Example prompt: Retrieve the latest 100 telemetry records from device sensor-001's stream and get the most recent reading at path '/temperature'

### Remote Procedure Calls on MCU Devices

Execute on-demand commands on connected MCU devices using the POST /v1/projects/{projectId}/devices/{deviceId}/rpc endpoint. RPC enables cloud-initiated actions like triggering sensor readings, resetting peripherals, or running diagnostics - without waiting for the device's normal reporting interval. The device firmware registers RPC handlers that process the request and return a response payload.

Example prompt: Send an RPC call 'get_diagnostics' to device xyz789 with parameters '{"verbose": true}' and parse the response for battery voltage and signal strength

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /v1/projects/{projectId}/devices | List all devices in a project |
| POST | /v1/projects/{projectId}/devices/{deviceId}/rpc | Invoke a remote procedure call on a device |
| GET | /v1/projects/{projectId}/devices/{deviceId}/data/{path} | Read device state from LightDB |
| PUT | /v1/projects/{projectId}/devices/{deviceId}/data/{path} | Write device state to LightDB |
| POST | /v1/projects/{projectId}/releases | Create a firmware release for OTA deployment |
| GET | /v1/projects/{projectId}/devices/{deviceId}/stream | Get device telemetry stream data |
| POST | /v1/projects/{projectId}/integrations | Create a data routing integration |
| POST | /v1/projects/{projectId}/devices | Provision a new device in a project |

## Key resources

- **Devices** — Provision, monitor, update, and invoke RPC on connected MCU devices
- **LightDB (State)** — Path-based JSON state store for device configuration and reported values
- **LightDB Stream** — Time-series telemetry ingestion and query for historical sensor data
- **Releases & Artifacts** — Firmware binary management and fleet-wide OTA update orchestration
- **Integrations** — Webhook and cloud service routing for device data forwarding
- **Credentials & Certificates** — X.509 and PSK credential management for device authentication
- **Blueprints** — Device type templates defining firmware, settings, and tag associations

## Why Jentic

- **Setup:** Wiring Golioth by hand means implementing its x-api-key header auth against api.golioth.io, threading the project id through every path, and mapping the device, data, and release endpoints yourself. Through Jentic you install once, import Golioth from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Golioth puts the project id in the URL path (/v1/projects/{projectId}/...), so a rule can pin your agent to one project: it can list devices, read and write device data, and query streams within that project and nothing else. You choose the operations it may call, so ones like creating an integration or a firmware release are not included unless you add them.
- **Credential handling:** Your Golioth 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 'list devices in a project' or 'push a firmware release', and Jentic returns the matching Golioth operation with its input schema so the agent calls the right endpoint without navigating the project hierarchy by hand.

## Related APIs

- **Particle Cloud API** — Vertically integrated hardware+cloud MCU platform vs Golioth's hardware-agnostic SDK approach
- **Balena Cloud API** — Container-based fleet management for Linux SBCs vs Golioth's MCU-native approach
- **ThingsBoard API** — Open-source IoT dashboard and rule engine for advanced telemetry visualization
- **Blynk API** — Mobile app builder and no-code dashboard for IoT device control interfaces

## FAQ

### Why is there no official OpenAPI spec for Golioth API?

Golioth does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Golioth API via structured 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 Golioth API use?

The Golioth API supports two authentication methods: Bearer token (passed in the Authorization header) and API Key (passed in the x-api-key header). Project-scoped API keys are created via POST /v1/projects/{projectId}/apikeys. Through Jentic, these credentials are stored in your encrypted Jentic One instance and agents receive scoped access without handling raw keys.

### Can I invoke a remote command on a specific device?

Yes. Send a POST request to /v1/projects/{projectId}/devices/{deviceId}/rpc with the method name and parameters in the request body. The device must have a registered RPC handler for the specified method in its firmware. The endpoint returns the device's response payload synchronously if the device is online.

### How do I read and write device state through Jentic?

Search Jentic for 'read IoT device state from LightDB' to discover the GET /v1/projects/{projectId}/devices/{deviceId}/data/{path} endpoint. Specify any JSON path to read or write structured state data. PUT replaces the value at a path, PATCH merges with existing data, and DELETE removes a path. This enables digital twin patterns without custom infrastructure.

### How do OTA firmware releases work in the Golioth API?

First upload a firmware binary via POST /v1/artifacts, then create a release with POST /v1/projects/{projectId}/releases linking the artifact to target devices by blueprint or tag. Devices check for pending releases and download artifacts automatically. Monitor rollout progress via GET /v1/projects/{projectId}/firmware/logs.

### Can I route device telemetry to external services?

Yes. Create an integration via POST /v1/projects/{projectId}/integrations specifying the destination (webhook URL, cloud provider, or database). Validate the configuration with POST /v1/projects/{projectId}/integrations/validate before saving, and test with POST /v1/projects/{projectId}/integrations/{integrationId}/test to confirm data flows correctly.

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

Yes. Jentic One runs self-hosted, so your own rules decide which Golioth operations and credentials the agent may use. Because Golioth puts the project id in the URL path, you can pin the agent to a single project and grant only the operations you choose, such as listing devices, reading and writing device data via LightDB, and querying telemetry streams. Higher-impact operations like creating a firmware release or a data integration stay off limits until you explicitly add them.