Dataset Endpoints — Ingest and Delete Sensor Data

Datasets are the core data containers in PrintHeritage — each one represents a named sensor channel attached to a structural monitoring project. The two endpoints below let you ingest time-series readings into a project (creating a new dataset or updating an existing one in place) and permanently remove a dataset by its ID. All requests must carry a valid Bearer token, and the requesting user must already have access to the target project.

Dataset schema

A dataset object is stored as a JSON document inside the project’s datasets array. Every field shown below may be present in both request payloads and responses.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "label": "E1 Displacement",
  "data": [
    {"date": "2024-01-15T10:30:00", "displacement": 0.12},
    {"date": "2024-01-16T10:30:00", "displacement": 0.15}
  ],
  "metadata": {
    "unit": "mm",
    "sensorType": "Vibração",
    "defaultChartType": "Área",
    "supportedChartTypes": ["Linha", "Área"],
    "selectedColumns": ["displacement"]
  }
}

PATCH /projects//data

Adds a new dataset to a project or, if a dataset with the same id or label already exists, updates its readings and merges the supplied metadata over the stored metadata. On success the endpoint returns the canonical dataset_id regardless of whether a create or an update occurred.

This endpoint accepts a free-form JSON body. All fields other than data are optional, but omitting label causes the dataset to be stored under the default name “Novo Sensor”.

Path parameters

project_id

string (UUID)

required

UUID of the project to which the dataset belongs.

Request body fields

label

string

default:"Novo Sensor"

Human-readable name for the sensor or dataset channel. If a dataset with this label already exists in the project, its data will be overwritten rather than a new dataset being created.

data

array of objects

required

Array of time-series reading objects. Each object must contain a date field (ISO 8601 string) plus one or more numeric measurement columns.

Show Reading object fields

date

string (ISO 8601)

required

Timestamp of the reading, e.g. "2024-01-15T10:30:00".

[column]

number

One or more numeric sensor columns, e.g. "displacement", "temperature", "humidity". Column names are user-defined.

metadata

object

Optional metadata describing display and sensor characteristics.

Show Metadata fields

unit

string

Measurement unit, e.g. "mm", "°C", "µm/m".

sensorType

string

Sensor category label, e.g. "Temperatura", "Vibração".

defaultChartType

string

Default chart style used in the dashboard, e.g. "Linha", "Área".

supportedChartTypes

array of strings

List of chart styles supported by this dataset, e.g. ["Linha", "Área"].

selectedColumns

array of strings

Column names that are selected for display by default.

string

Optional client-supplied dataset ID. When provided and a dataset with this exact ID already exists in the project, that dataset is updated rather than a new one being created.

Response

boolean

Always true on success.

dataset_id

string (UUID)

The ID of the dataset that was created or updated.

Example — add a temperature sensor with 3 readings

curl -X PATCH "https://api.printheritage.io/projects/2b9e1f4a-3c5d-4e8f-a012-bc9d1234ef56/data" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "T1 Temperature",
    "data": [
      {"date": "2024-06-01T08:00:00", "temperature": 22.4},
      {"date": "2024-06-01T09:00:00", "temperature": 23.1},
      {"date": "2024-06-01T10:00:00", "temperature": 23.8}
    ],
    "metadata": {
      "unit": "°C",
      "sensorType": "Temperatura",
      "defaultChartType": "Linha",
      "supportedChartTypes": ["Linha", "Área"],
      "selectedColumns": ["temperature"]
    }
  }'

{
  "ok": true,
  "dataset_id": "a3f7c910-22bb-4d5e-9f0a-7812cd34ab10"
}

A side-effect audit log entry with action PROJECT_DATA_ADD is written on every successful call, recording the acting user and the target project ID.

DELETE /projects//datasets/

Permanently removes a single dataset from a project. The caller must hold at least the PROJECT_ADMIN role on the project — users with the VISUALIZER role will receive a 403 error.

Deletion is irreversible. All time-series readings stored inside the dataset are removed immediately and cannot be recovered through the API.

Path parameters

project_id

string (UUID)

required

UUID of the project that owns the dataset.

dataset_id

string

required

ID of the dataset to delete, as returned by PATCH /projects/{project_id}/data.

Response

boolean

true when the dataset was found and deleted, or when the project has no datasets at all (idempotent).

Error responses

Status	Condition
`403`	Caller’s role is `VISUALIZER` — insufficient permissions to delete datasets.
`401`	Missing or invalid Bearer token.

Example

curl -X DELETE "https://api.printheritage.io/projects/2b9e1f4a-3c5d-4e8f-a012-bc9d1234ef56/datasets/a3f7c910-22bb-4d5e-9f0a-7812cd34ab10" \
  -H "Authorization: Bearer <token>"

{
  "ok": true
}

A side-effect audit log entry with action PROJECT_DATA_DELETE is written on every successful deletion, recording the acting user and the target project ID.

Overview

Endpoints

Dataset Endpoints — Ingest and Delete Sensor Data

Dataset schema

PATCH /projects//data

Path parameters

Request body fields

Response

Example — add a temperature sensor with 3 readings

DELETE /projects//datasets/

Path parameters

Response

Error responses

Example

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Dataset schema

​PATCH /projects//data

​Path parameters

​Request body fields

​Response

​Example — add a temperature sensor with 3 readings

​DELETE /projects//datasets/

​Path parameters

​Response

​Error responses

​Example

Build docs developers (and LLMs) love

Dataset schema

PATCH /projects//data

Path parameters

Request body fields

Response

Example — add a temperature sensor with 3 readings

DELETE /projects//datasets/

Path parameters

Response

Error responses

Example