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

# dweet.io

Dweet.io is a lightweight machine-to-machine messaging service that lets devices, scripts, and apps publish small JSON payloads (dweets) to a named 'thing' and read the most recent or stored dweets back over plain HTTP. The API supports locking a thing to a key, attaching alert callbacks when a payload condition is met, and listening for new dweets in long-polled streams - all without account setup for public things.

## For AI agents

Publish JSON payloads to a named thing, read recent or stored dweets, and set conditional alerts so agents can wire up quick IoT-style telemetry without managing a backend.

## Scope

Does not provide device provisioning, fleet management, or secure per-device certificates - use for lightweight publish/read of JSON payloads on named things only.

## Capabilities

- Publish a JSON payload to a named thing as a dweet
- Read the latest dweet or the last 5 cached dweets for a thing
- Stream new dweets for a thing via long-polling on `/listen/for/dweets/from/{thing}`
- Lock a thing with a key so only authorised callers can publish to it
- Attach a conditional alert to a thing that fires when the payload matches a condition
- Query stored dweet history for a locked thing for historical analysis

## Use cases

### Lightweight Device Telemetry

A microcontroller or script publishes JSON readings (temperature, battery, status) as dweets to a uniquely named thing, and a dashboard or agent reads them back through `/get/latest/dweet/for/{thing}.` No accounts or broker setup are required for public things, which keeps prototype IoT projects to a single HTTP call per direction.

Example prompt: POST a JSON body {"temp": 21.4, "battery": 88} to `/dweet/for/lab-sensor-01` and then GET `/get/latest/dweet/for/lab-sensor-01` to confirm the reading was stored

### Conditional Alerting on Telemetry

Attach a server-side alert to a locked thing so dweet.io watches incoming payloads and fires the alert when a condition is met (e.g. value above a threshold). The alert endpoint is a one-line registration that replaces a custom watcher service for simple threshold use cases.

Example prompt: GET `/alert/{who}/when/lab-sensor-01/temp`%3E30 to register an alert that fires when the temp field of lab-sensor-01 dweets exceeds 30, and verify with `/get/alert/for/lab-sensor-01`

### Real-Time Listener for Streaming Dashboards

A dashboard backend opens a long-polling connection to `/listen/for/dweets/from/{thing}` and receives each new dweet as it arrives, enabling live charts without running a websocket server or message broker. Combined with stored history, this gives both real-time and replay views from a single API.

Example prompt: Open a long-polling GET on `/listen/for/dweets/from/lab-sensor-01` and forward each received payload to a charting front-end

### Agent-Driven IoT Probes via Jentic

An AI agent debugging a remote device asks Jentic for 'the latest dweet for thing X', and Jentic returns the dweet.io operation. The agent calls `/get/latest/dweet/for/{thing}` with the supplied name, parses the JSON content, and reports the device state without needing any vendor SDK.

Example prompt: Use Jentic to search 'get the latest dweet for a thing', load the operation for `/get/latest/dweet/for/{thing}`, and execute it for thing 'lab-sensor-01'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/dweet/for/{thing}` | Publish a dweet (JSON payload) to a named thing |
| GET | `/get/latest/dweet/for/{thing}` | Read the most recent dweet for a thing |
| GET | `/get/dweets/for/{thing}` | Read the last 5 cached dweets for a thing |
| GET | `/listen/for/dweets/from/{thing}` | Long-poll for new dweets from a thing |
| GET | `/lock/{thing}` | Reserve and lock a thing with a key |
| GET | `/alert/{who}/when/{thing}/{condition}` | Create a conditional alert for a thing |
| GET | `/get/stored/dweets/for/{thing}` | Read stored dweet history for a locked thing |

## Key resources

- **Dweets** — Publish, read latest, read recent five cached, listen for, and read stored dweets for a thing
- **Locks** — Reserve a thing name with a key (`/lock/{thing}`), unlock it (`/unlock/{thing}`), and remove a lock by key (`/remove/lock/{lock}`)
- **Alerts** — Create conditional alerts (`/alert/{who}/when/{thing}/{condition}`), retrieve attached alerts, list stored alerts, and remove alerts for a thing

## Why Jentic

- **Setup:** The dweet.io API needs no auth for public things, but wiring it still means building the publish and read calls and threading each thing name through the path yourself. Through Jentic you install once, import dweet.io from the API Directory, and your agent calls it.
- **Permission scoping:** dweet.io puts the thing name in the URL path (`/dweet/for/{thing}`, `/get/latest/dweet/for/{thing}`), so a rule can pin your agent to one named thing. You choose the operations it may call, so locking a thing or setting an alert is not included unless you add them.
- **Credential handling:** Public dweets require no credentials. For a locked thing, its lock key is stored once, encrypted, by your own Jentic One instance and injected at execution time, so it never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'publish a dweet' or 'get the latest dweet for a thing', and Jentic returns the matching dweet.io operation with its input schema, including the thing path parameter, so the agent calls the right endpoint without browsing the docs.

## Related APIs

- **Dynosend API** — Trigger an email or transactional notification when a dweet alert fires
- **E-goi Marketing API** — Send SMS, email, or push notifications driven by dweet alert events
- **dYdX Indexer API** — Domain-specific telemetry (trading data) - dweet.io is the generic JSON option

## FAQ

### Where does the dweet.io OpenAPI spec come from?

dweet.io published its own machine-readable definition at https://dweet.io/play/definition in Swagger 1.2 format, and this specification descends from it: APIs.guru converted that definition to Swagger 2.0 and republishes it at https://api.apis.guru/v2/specs/dweet.io/2.0/swagger.yaml. Jentic bundles and validates that document so agents can call the 13 operations through structured tooling. The dweet.io domain itself no longer serves the definition or the API. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the dweet.io API use?

Public things require no authentication - any caller can publish or read. To restrict a thing, lock it with `/lock/{thing}`, which returns a key that must then be supplied as a query parameter on subsequent reads of stored dweets and alerts. Through Jentic, that key is stored in the vault and injected at execution time.

### Can I stream new dweets in real time with the dweet.io API?

Yes. GET `/listen/for/dweets/from/{thing}` holds the connection open and returns each new dweet as it is published, so you can drive live dashboards or agents without a websocket server. The endpoint will return the next dweet or time out after the server's idle window.

### What are the rate limits for the dweet.io API?

The OpenAPI spec does not declare numeric rate limits. dweet.io is designed for low-volume telemetry on free things and applies fair-use throttling rather than published quotas - high-throughput callers should lock their things and consider the paid Bug Labs tier.

### How do I publish a dweet through Jentic?

Run pip install jentic, search for 'publish a dweet to a thing', load the operation for POST `/dweet/for/{thing}`, then execute it with the thing name as a path parameter and the JSON body as the payload. No API key is needed for public things.

### Does dweet.io persist data?

By default only the most recent five dweets are cached for a thing and reachable via `/get/dweets/for/{thing}.` Long-term history through `/get/stored/dweets/for/{thing}` requires the thing to be locked under a paid plan; otherwise the stored endpoints return empty results.

### Can I limit what my agent is allowed to do with the dweet.io API?

Yes. Because dweet.io puts the thing name in the URL path, such as `/dweet/for/{thing}` and `/get/latest/dweet/for/{thing}`, a rule in your self-hosted Jentic One can pin your agent to one named thing. You decide which operations the agent may call, so you can allow only publishing and reading while excluding locking a thing or setting an alert unless you explicitly add them. Any lock key for a locked thing is held by your own instance and injected at execution time, so your rules alone govern what the agent can reach.