# PostData

> Free, public sensor-data API: the dweet.io successor. No signup and no API key. Devices send JSON readings over plain HTTP, HTTPS, WebSocket or MQTT-over-WebSocket; anyone can read them back as the latest value, ~92 days of numeric history, a live WebSocket stream, or a live chart in the browser. Everything is public.

Base URL: `http://api.postdata.cloud` (or `https://`). Send a reading:

```
curl -X POST http://api.postdata.cloud/add/amber-otter-4821 -d '{"temp": 21.5, "hum": 60}'
```

Rules an agent should know before writing firmware or code against it:

- Everything is public: anyone can read and write any device. Never send credentials, personal data or precise locations.
- Device names are first come, first served. Get an unused one from `GET /new` instead of inventing `test` or `esp32-sensor`, which someone else is already writing to.
- A reading is a flat JSON object of 1-10 metrics. Numbers keep ~92 days of history; strings keep only their latest value. Keys `ts`/`timestamp` are ignored: the server stamps reception time.
- One message per device per 30 seconds, shared by every transport. Faster sends get `429` with `Retry-After`. Batch metrics into one message.
- Plain `http://` is deliberately supported for boards without TLS. With `https://`, never pin the server certificate (it rotates every 90 days); trust a root CA instead.
- MQTT is MQTT-over-WebSocket only (`ws://api.postdata.cloud/mqtt/{device}`); there is no port 1883 or 8883.
- Errors are JSON with `error`, a `hint` saying how to fix it, and a `docs` link.
- To verify a device works, read `GET /last/{device}` (or the MCP `wait_for_reading` tool) and give the user the live chart: `https://postdata.cloud/device?id={device}`.

## Docs

- [Full API reference and firmware recipes (Markdown)](https://postdata.cloud/llms-full.txt): every endpoint, ESP32/ESP8266/MicroPython/CircuitPython/ESPHome/Python examples, TLS on microcontrollers, MQTT, dweet.io compatibility
- [OpenAPI 3 spec](https://postdata.cloud/api.yaml): machine-readable HTTP API
- [Human docs](https://postdata.cloud/docs): the same reference as a web page

## MCP server

- [Remote MCP server](https://api.postdata.cloud/mcp): Streamable HTTP, no auth. Tools: `new_device_name`, `publish_reading`, `get_latest`, `get_history`, `wait_for_reading`, `list_recent_devices`. Add to Claude Code with `claude mcp add --transport http postdata https://api.postdata.cloud/mcp`.

## Optional

- [Explore recent devices](https://postdata.cloud/explore): real payloads from real devices
- [dweet.io compatibility](https://postdata.cloud/docs#dweet): classic dweet URLs work by swapping the hostname to `api.postdata.cloud`