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

# Merren MerrenIO API

Jentic publishes the only available OpenAPI specification for MerrenIO API, keeping it validated and agent-ready. MerrenIO offers a lightweight IoT backend for registering connected devices, listing the current device fleet, and ingesting telemetry from those devices. The API is intentionally small, exposing the three primitives a device gateway or operations dashboard needs to bootstrap onboarding flows and time-series ingestion without standing up a full IoT platform.

## For AI agents

Register IoT devices, list the fleet, and ingest telemetry through MerrenIO's three-endpoint device-management API.

## Scope

Does not handle firmware OTA, device shadows, alerting, or analytics dashboards - use for MerrenIO device registration, fleet listing, and telemetry ingestion only.

## Capabilities

- Register a new IoT device against the MerrenIO tenant for tracking and telemetry
- List the current fleet of registered devices for inventory and dashboards
- Ingest telemetry payloads from devices into the MerrenIO backend
- Bootstrap device onboarding workflows from a gateway or provisioning script
- Feed an operations dashboard with the latest device roster on demand

## Use cases

### Device Fleet Onboarding

Operations teams rolling out new IoT hardware can register each device with POST /devices and then verify the inventory with GET /devices. This pattern fits manufacturing rollouts, smart-building installs, and field deployments where the registration step happens at install time and the inventory query feeds operations dashboards.

Example prompt: Call POST /devices with the new gateway's identifier and metadata, then GET /devices to confirm the registration succeeded.

### Telemetry Ingestion

Connected devices can stream readings to the MerrenIO backend via POST /telemetry. The endpoint accepts payloads from sensors, gateways, or edge functions, supporting use cases like environmental monitoring, equipment health tracking, and asset utilisation reporting where periodic ingestion drives downstream analytics.

Example prompt: Call POST /telemetry with the device ID and a JSON payload of the latest sensor readings.

### Operations Dashboard Data Source

Internal dashboards that show fleet status can call GET /devices on a schedule to refresh the device roster. This avoids running a separate inventory store and keeps the dashboard aligned with whatever the MerrenIO backend currently knows about, which is the source of truth for registration.

Example prompt: Call GET /devices and render the response as a fleet-status table in the operations dashboard.

### Agent-Driven IoT Operations

An AI agent embedded in an operations workflow can take instructions like 'register the new gateway in zone 4' or 'upload last hour's readings' and call MerrenIO via Jentic. The agent searches Jentic for the device or telemetry operation, loads the schema, and posts the request without writing custom MerrenIO client code.

Example prompt: Search Jentic for 'register an IoT device with MerrenIO', load POST /devices, and execute it with the gateway's identifier and zone metadata.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/devices` | List registered IoT devices |
| POST | `/devices` | Register a new IoT device |
| POST | `/telemetry` | Ingest a device telemetry payload |

## Key resources

- **Devices** — Register and list IoT devices in the tenant
- **Telemetry** — Ingest sensor and gateway telemetry payloads

## Why Jentic

- **Setup:** Wiring the MerrenIO API by hand means placing its apiKey in the Authorization header, shaping the device-registration and telemetry request bodies against api.merren.io, and handling retries yourself. Through Jentic you install once, import the MerrenIO API from the API Directory, store the apiKey once, and your agent calls it.
- **Permission scoping:** The MerrenIO API takes device and telemetry data in the request body rather than as URL path resources, so scope your agent to the operations it needs: limit it to listing devices, registering a device, or ingesting telemetry, and leave out any operation it does not require.
- **Credential handling:** Your MerrenIO apiKey is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'register an IoT device' or 'send telemetry to MerrenIO', and Jentic returns the matching operation such as POST /devices or POST /telemetry with its request schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Particle IoT API** — End-to-end IoT platform with device cloud, OTA, and SDKs
- **Balena Cloud API** — Container-native fleet management for connected devices
- **AWS IoT** — Hyperscale IoT platform with rules engine, shadows, and device defender

## FAQ

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

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

MerrenIO uses an API key sent in the Authorization header. Through Jentic, that key is stored in the credential vault and the agent calls the API with a scoped Jentic token, so the raw MerrenIO key never enters the agent context.

### Can I send a batch of telemetry readings in one call?

POST /telemetry accepts a JSON payload representing one or more device readings. For very large batches the recommended pattern is to chunk by device and post in parallel rather than aggregating all devices into a single body, which keeps the per-request size manageable.

### What are the rate limits for the MerrenIO API?

The OpenAPI spec does not declare rate limits. MerrenIO applies tenant-level throttling on the production endpoint; high-frequency telemetry should batch readings per device and back off on 429 responses rather than streaming one reading per HTTP call.

### How do I register a device with MerrenIO through Jentic?

Install the SDK with pip install jentic, search for 'register an IoT device with MerrenIO', load the POST /devices operation, and execute it with the device identifier and metadata. Jentic handles authentication and posts to api.merren.io.

### How do I get the current list of MerrenIO devices?

Call GET /devices. The endpoint returns the current registered fleet for the authenticated tenant, suitable for refreshing operations dashboards or reconciling against a separate inventory system.

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

Yes. Because you run Jentic One yourself, your own rules decide which MerrenIO operations and credentials the agent can use, and you can grant only the ones a given workflow needs. The MerrenIO API exposes just three operations, so you might allow an agent to list the fleet with GET /devices while withholding POST /devices and POST /telemetry, or let a sensor gateway ingest telemetry without permitting it to register new devices. The stored API key is injected only when an allowed operation runs, so an agent cannot call an endpoint you have not scoped to it.