Skycase Telemetry POST API

The Skycase Telemetry POST API allows you to post telemetry data from your IoT devices to the Skycase platform. This document provides detailed information on how to use the API, including endpoints, parameters, and example requests.

Endpoint

The endpoint for posting telemetry data is:

POST /api/v1/{deviceToken}/telemetry

Replace {deviceToken} with the unique token of the device you are posting data to.

Headers

Content-Type: application/json

Request Body

The request body should be a JSON object containing one or more key-value pairs, where the keys are the telemetry keys and the values are the telemetry values. The timestamp can be included optionally.

{
     "ts": 1718610066000,
     "values": {
         "temperature": 45.6,
         "humidity": 50
     }
}

temperature (required): The temperature value.
humidity (required): The humidity value.
timestamp (optional): The timestamp in milliseconds. If omitted, the server will use the current time.

Example Request

Here is an example of a request to post telemetry data:

POST /api/v1/ABC123DEF456/telemetry HTTP/1.1
Host: skycase.embien.com
Content-Type: application/json

{
   "temperature": 23.5,
   "humidity": 60
}

Response

A successful request will return a 200 OK status code. No content is returned in the response body.

HTTP/1.1 200 OK

Error Responses

400 Bad Request: The request was invalid or cannot be served. The exact error should be explained in the error payload. For example, if the JSON is malformed or required fields are missing.

{
  "error": "Bad Request",
  "message": "Invalid JSON format."
}

401 Unauthorized: Authentication failed or user does not have permissions for the requested operation.

{
  "error": "Unauthorized",
  "message": "Invalid or missing device token."
}

500 Internal Server Error: An error occurred on the server.

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred."
}

Usage Notes

Ensure that the device token used in the URL is valid and corresponds to the device you want to post telemetry data for.
The timestamp is optional. If you do not provide a timestamp, the server will use the current time when the data is received.
Telemetry keys are case-sensitive and must be unique for each device.

Examples

Example 1: Posting telemetry data with a timestamp:

POST /api/v1/ABC123DEF456/telemetry HTTP/1.1
Host: skycase.embien.com
Content-Type: application/json

{
     "ts": 1718610066000,
     "values": {
         "temperature": 45.6,
         "humidity": 50
     }
}

Example 2: Posting telemetry data without a timestamp:

POST /api/v1/ABC123DEF456/telemetry HTTP/1.1
Host: skycase.embien.com
Content-Type: application/json

{
  "temperature": 23.5,
  "humidity": 60
}

For further details and additional information, please refer to the Skycase API documentation or contact support.