---
title: Ingest API Reference
description: "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.…"
url: "https://twinnoverse.com/docs/ingest-api-reference/"
updated: "2025-10-14"
category: "Digital twin / Digital Twin Developer & API"
---

# 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](https://twinnoverse.com/docs-category/widget-system/widget-library-reference/)Reference.

### SingleData Widget

Expects a key with a simple numerical or string value.

- **Widget `DataKey`:** `temperature`

**JSON Payload:**

```
{
  "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
  }
}
```

### 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]
  }
}
```

### 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]
  }
}
```

---

## 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
    }
  }'
```

---

## 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.