Swagger API Overview

This API allows EnOcean SmartStudio users to interact with and manage your devices, gateways, and system resources within the platform. It provides a robust set of endpoints to authenticate users, manage devices, retrieve system data, and gateways.

The API is structured to support the automation of device onboarding, real-time telemetry collection, system health checks, and much more. Whether you're building applications for device control, monitoring, or reporting, this API provides the essential tools to integrate seamlessly with the platform.

EnOcean SmartStudio API is accessible from the link below:

EnOcean SmartStudio API

Key Features

  • Authentication: Secure access to the platform using token-based authentication.
  • Device Management: Comprehensive device lifecycle management including adding, updating, and deleting IoT devices.
  • System Operations: Manage and retrieve system backups, restore instances, and check the overall health of the platform.
  • Gateway Monitoring: Access detailed information about gateways, including health, performance, and data statistics.

Sections

This API is divided into four major sections based on functionality:

  1. Auth: Handles user authentication and token management, ensuring secure access to the platform.
    • Endpoints: /auth/login, /auth/logout, /auth/accessToken
  2. System: Allows for system-level operations such as backups, restores, and health checks.
    • Endpoints: /system/backup, /system/restore
  3. Device: Manages IoT devices, including adding, updating, retrieving, and removing devices. It also provides access to device-specific telemetry and signal data.
    • Endpoints: /devices, /devices/{deviceId}, /devices/{deviceId}/telegram, /devices/{deviceId}/telemetry, /devices/{deviceId}/signal
  4. Gateway: Provides gateway management and monitoring capabilities, offering insight into gateway status, health, and performance.
    • Endpoints: /gateways, /gateways/{mac}, /gateways/{mac}/stats, /gateways/{mac}/health

Authentication and Authorization

To interact with most endpoints, users must authenticate using the Auth endpoints.

How to Use the API

  1. Authenticate: Use the /auth/login endpoint to login to the platform.
  2. Perform Operations: Once authenticated, you can interact with devices, gateways, or system operations depending on your needs.
  3. Monitor and Manage: Use device telemetry, signal, and system health endpoints to monitor the health and performance of your platform.

Response Format

All API responses are returned in JSON format. For successful requests, a status code of 200 OK or 201 Created is returned, along with the relevant data. In the event of an error, the response will include an appropriate HTTP status code (e.g., 400 Bad Request, 401 Unauthorized, 404 Not Found) and a descriptive error message.

Status Codes

  • 200 OK: The request was successful.
  • 201 Created: The resource was successfully created.
  • 400 Bad Request: The request contains invalid parameters.
  • 401 Unauthorized: Authentication failed or is required.
  • 404 Not Found: The requested resource could not be found.
  • 500 Internal Server Error: The server encountered an unexpected condition.

Conclusion

This API is designed to provide a flexible and secure way to manage your IoT devices and gateways while monitoring system performance. With a rich set of endpoints, it supports both operational needs and real-time telemetry data.

For detailed information on each endpoint, refer to the specific sections for Auth, System, Device, and Gateway.