API Reference
Everything an app, a script or a dashboard does against ESP RainMaker Neo goes through one of three API surfaces. This page says what each one is for and which to reach for; the pages under it are the endpoint-by-endpoint reference.
The authentication is not what you would guess — almost every endpoint is SigV4-signed rather than Bearer-token-authenticated, so a "log in and send the JWT" client will get 403s. Getting Started is the shortest path to a working call.
The three surfaces
Auth & Accounts — identity. Registration, email or
phone verification, login, token refresh, sign-out and the password flows, under
/v1/user/auth/*. Administrators have their own equivalents under /v1/admin/auth/*, against a
separate user pool. This is the only surface that takes a username and password.
Platform API — everything a signed-in caller does afterwards: nodes and their configuration, groups and subgroups, sharing, schedules, triggers, automations, time series, notifications, Matter fabrics and file management. The reference splits it by audience, because the two halves have different readers:
- End-user APIs — what a phone app or a user-facing client calls on behalf of one signed-in user
- Admin APIs — fleet-wide operations: registering nodes in bulk, node administration, scoping credentials to a group
MQTT — live state. Nodes publish and subscribe here, and so can an app that wants updates without polling. Documented as two topic contracts, one from the node's side and one from the user's.
Which one you need
| You are | Start with |
|---|---|
| Building a phone or web app | Auth & Accounts, then End-user APIs |
| Wanting live updates without polling | MQTT (user) |
| Writing device firmware | MQTT (node) |
| Operating a fleet | Admin APIs |
| Automating from a script | End-user APIs with awscurl |
Base URLs are per deployment
There is no shared hostname. Every deployment publishes its own API Gateway endpoints in its client configuration file, and each endpoint page here lets you point Base URL at yours before using Try it out. Deployment Details shows where that file is published.
How these pages are produced
The reference is generated at build time from the specifications the backend ships — OpenAPI for the two REST surfaces, AsyncAPI for MQTT. That means the pages track the deployed API rather than a hand-maintained copy: a wrong description or a missing field is fixed in the source specification, and the fix flows through to these pages on the next build.
Related
- Getting Started — the auth chain, SigV4, and a working
curlexample - Building custom apps — what a client needs from a deployment
- ESP RainMaker Neo SDK — the SDK that performs the auth chain for you
- Security model — how identity and access are enforced