Version: 0.1.0

ESP RainMaker Neo Platform API

REST API for the ESP RainMaker Neo platform - everything except sign-up and authentication, which live in the separate ESP RainMaker Neo User API (User_Api_Swagger.yaml).

Covers what an app or admin dashboard does once a user is signed in: groups and sharing, node association, control surfaces (schedules, automations, triggers, time-series), admin operations (bulk node registration, voice-assistant integrations), and the credential exchange used for SigV4-signed requests.

Each endpoint declares its security scheme:

• CognitoAuthorizer - a bearer access token in the Authorization header, from the ESP User OIDC issuer for end users or the admin Cognito pool for admins. Used only by /v1/user/credentials, which also needs the paired id_token in the body.
• gvaAccessToken - an ESP User access_token issued to the voice-assistant client during Google account linking, validated by the Lambda. Used only by /v1/integrations/gva.
• sigv4 - AWS SigV4 signing using the temporary credentials returned by POST /v1/user/credentials. Used by every other endpoint.

Endpoints are organised by tag. End-user-facing surface is listed first (Group Management, Sharing, Node Association, control, telemetry, Matter, Notification Endpoints); admin-only surface follows (Node Administration, Integrations, File Management, Google Voice Assistant).

Authentication

API Key: sigv4

Security Scheme Type:	apiKey
Header parameter name:	Authorization

API Key: CognitoAuthorizer

Bearer access token — ESP User OIDC for end users, admin Cognito pool for admins. Used only by POST /v1/user/credentials, which also needs the paired id_token in the body.

Security Scheme Type:	apiKey
Header parameter name:	Authorization

API Key: gvaAccessToken

ESP User access_token as Bearer <access_token>, issued to the voice-assistant client during Google account linking. Validated by the Lambda, not by an API Gateway authorizer.

Security Scheme Type:	apiKey
Header parameter name:	Authorization

OAuth 2.0: cognitoAuth

Cognito User Pool OAuth2 with tiered scopes. Server-side authorization verifies the custom:super_admin claim for super_admin-scoped operations.

Security Scheme Type:	oauth2
OAuth Flow (implicit):	Authorization URL: https://example.com/oauth2/authorize Scopes: admin: Admin tier user: End-user tier

Contact

esp-rainmaker-support@espressif.com

URL: https://rainmaker.espressif.com

Terms of Service

http://swagger.io/terms/

License

Apache 2.0