Ingest API Reference

The Twinnoverse Ingest API is a secure REST endpoint designed to receive data from your external systems. By sending a simple HTTP POST request, you can push data to your datasources and see your 3D digital twins update in real-time.

This document provides the technical details needed to interact with this endpoint.

Endpoint Details #

• URL: https://fssn.........
• Method: POST
• Headers:
  • X-API-Key: YOUR_API_KEY

Authentication #

The API uses Token authentication. You must provide the unique API Key from your specific datasource card in the header.

Requests without a valid token will be rejected.

Payload Structure #

The body of your POST request must be a single JSON object. The keys and value structures within this object must correspond to the DataKey and Widget Type you have configured for the widgets linked to your datasource.

The Example Schema field on the datasource card in the Twinnoverse dashboard is the best source of truth, as it generates a precise schema based on your actual linked widgets.

Below are examples for each widget type, you can read more about all the widget type in the Widget System>Widget Library Reference.

SingleData Widget #

Expects a key with a simple numerical or string value.

• Widget DataKey: temperature

JSON Payload:

{
  "temperature": 42.5
}

{
  "temperature": 42.5
}

DoubleData Widget #

Expects a key that points to a nested JSON object containing two sub-keys.

• Widget DataKey: motor_stats
• Widget Settings: primarySubKey: "rpm", secondarySubKey: "vibration"

JSON Payload:

{
  "motor_stats": {
    "rpm": 1500,
    "vibration": 0.75
  }
}

{
  "motor_stats": {
    "rpm": 1500,
    "vibration": 0.75
  }
}

BarChart / LineChart Widget #

Expects a key that points to a nested JSON object containing keys for labels and values.

• Widget DataKey: production_output
• Widget Settings: labelsKey: "machines", valuesKey: "units_per_hour"

JSON Payload:

{
  "production_output": {
    "machines": ["Machine A", "Machine B", "Machine C"],
    "units_per_hour": [112, 124, 98]
  }
}

{
  "production_output": {
    "machines": ["Machine A", "Machine B", "Machine C"],
    "units_per_hour": [112, 124, 98]
  }
}

Combining Multiple DataKeys #

You can send data for multiple widgets linked to the same datasource in a single API call.

JSON Payload:

{
  "temperature": 42.5,
  "motor_stats": {
    "rpm": 1500,
    "vibration": 0.75
  },
  "production_output": {
    "machines": ["Machine A", "Machine B", "Machine C"],
    "units_per_hour": [112, 124, 98]
  }
}

{
  "temperature": 42.5,
  "motor_stats": {
    "rpm": 1500,
    "vibration": 0.75
  },
  "production_output": {
    "machines": ["Machine A", "Machine B", "Machine C"],
    "units_per_hour": [112, 124, 98]
  }
}

Example Request (cURL) #

Here is a complete example of how to send data using the command-line tool cURL.

curl -X POST \
  'https://fssnxnkgywwetopuxsjl.supabase.co/functions/v1/ingest-data' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "temperature": 42.5,
    "motor_stats": {
      "rpm": 1500,
      "vibration": 0.75
    }
  }'

curl -X POST \
  'https://fssnxnkgywwetopuxsjl.supabase.co/functions/v1/ingest-data' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "temperature": 42.5,
    "motor_stats": {
      "rpm": 1500,
      "vibration": 0.75
    }
  }'

Responses #

The API will respond with standard HTTP status codes.

• 200 OK: The data was received and processed successfully.
• 400 Bad Request: The request was malformed. This is often due to invalid JSON in the request body.
• 401 Unauthorized: The request failed because the Authorization header was missing or the API Key was incorrect.
• 403 Forbidden: The provided API Key was valid, but it does not have permission to write to the specified resource.
• 500 Internal Server Error: An unexpected error occurred on the server while processing the data.