Access Maturix In-situ data through API

Last update: 23/01/2026
You are here:
In this article

Overview


The Insitu Public API provides programmatic access to your project data, including casts, monitorings, sensor data, and reports. The API is RESTful, returns JSON responses, and supports two versions (v1 and v2) with v2 offering enhanced features and additional data fields.

Key Features:

 

  • Token-based authentication with scope control
  • Real-time access to temperature, maturity, and strength data
  • Project and cast management information
  • Time-series monitoring data with unit conversion
  • CORS-enabled for web applications

Version 1 (v1)

  • Basic resource retrieval
  • Temperature unit conversion (Celsius/Fahrenheit)
  • Strength unit conversion (MPa, N/mm², psi, kg/cm²)
  • Simple response structure

Version 2 (v2) – Recommended

  • All v1 features plus:
  • Enhanced project statistics (cast counts, device/user counts)
  • Latest sensor data embedded in monitoring responses
  • Target information with predictions
  • Ambient temperature data
  • Device channel information
  • Concrete library access
  • Better structured responses with additional metadata

Recommendation: Use v2 for all new integrations.

  1. Ensure that Maturix has allowed your organization to use the public API. 
  2. Ensure the user has sufficient Organisation Permissions to access and setup API Keys (Admin Required)
  3. Add API Key
  4. Select API Key Type (Specific or All Projects)
  5. Use your favourite API Platform / Code for testing your newly generated API key

Authentication

All API requests require a valid authentication token. Tokens are organization-scoped or project-scoped and must be active and not expired.

Passing the Token:

Include the token in every request as a query parameter or in the request body:

				
					GET /v2/project?token=YOUR_TOKEN_HERE

Or in POST body:

				
					{
  "token": "YOUR_TOKEN_HERE"
}

Base URL

				
					https://api.maturix.com

All endpoints are relative to this base URL.

Example full URLs:

				
					https://api.maturix.com/v2/project?token=YOUR_TOKEN
https://api.maturix.com/v1/data/UUID?token=YOUR_TOKEN

Response Format

Success Response (HTTP 200)

				
					[
  {
    "resource_id": "uuid-here",
    "resource_name": "Resource Name",
    ...additional fields...,
    "endpoints": {
      "self": "/v2/resource/uuid",
      "related": "/v2/other-resource/uuid"
    }
  }
]

Error Response (HTTP 4xx)

				
					{
  "status": "fail",
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

  • 200 – Success
  • 400 – Bad request (missing parameters, invalid format, or malformed endpoint)
  • 401 – Unauthorized (invalid or missing token)
  • 404 – Resource not found (invalid endpoint or route)

Endpoints

Projects

List All Projects

				
					GET /v1/project?token=YOUR_TOKEN
GET /v2/project?token=YOUR_TOKEN

Get Specific Project

				
					GET /v1/project/{uuid}?token=YOUR_TOKEN
GET /v2/project/{uuid}?token=YOUR_TOKEN

Response Field

Field Type V1 V2 Description
project_id UUID ✓ ✓ Unique project identifier
project_name String ✓ ✓ Project name
project_description String ✓ ✓ Project description
location Object ✓ ✓ Coordinates: {lat: float, lng: float}
start_time Unix timestamp ✓ ✓ Project start time
end_time Unix timestamp ✓ ✓ Project end time
status String ✓ ✓ active or archived
planned_casts Integer ✗ ✓ Number of planned casts (status=0)
active_casts Integer ✗ ✓ Number of active casts (status=1)
finished_casts Integer ✗ ✓ Number of finished casts (status=2)
archived_casts Integer ✗ ✓ Number of archived casts (status=4 or hidden)
devices Integer ✗ ✓ Number of devices in project
users Integer ✗ ✓ Number of users in project
endpoints Object ✓ ✓ Related API endpoints

Sorting: Projects are returned ordered by status first, then alphabetically by name.

Casts

Retrieve cast (concrete pour) information including associated monitorings and sub-reports.

List All Casts

				
					GET /v1/cast?token=YOUR_TOKEN
GET /v2/cast?token=YOUR_TOKEN

# Filter by project
GET /v1/cast?token=YOUR_TOKEN&projectId=PROJECT_UUID
GET /v2/cast?token=YOUR_TOKEN&projectId=PROJECT_UUID

Get Specific Cast

				
					GET /v1/cast/{uuid}?token=YOUR_TOKEN
GET /v2/cast/{uuid}?token=YOUR_TOKEN

Response Fields:

Field Type Description
cast_id UUID Unique cast identifier
cast_name String Cast name
project_id UUID Parent project UUID
project_name String Parent project name
status String planned, active, finished, or archived
monitorings Array Array of monitoring objects (simplified) – hidden monitorings excluded
subreports Array Array of sub-report objects – hidden subreports excluded
concrete_mix Object Concrete mix information: {name: string} (empty if none assigned)
endpoints Object Related API endpoints

Status Mapping:

  • planned: Cast status = 0
  • active: Cast status = 1
  • finished: Cast status = 2
  • archived: Cast is hidden (hide=1) OR status = 4

Filtering:

  • Only casts with hide=0 are returned
  • Within casts, only monitorings and subreports with hide=0 are included
  • Results ordered by status, then by name

Monitoring Data

Retrieve time-series sensor data for a monitoring session.

Get Monitoring Data

				
					GET /v1/data/{uuid}?token=YOUR_TOKEN
GET /v2/data/{uuid}?token=YOUR_TOKEN

# V1 with unit conversion
GET /v1/data/{uuid}?token=YOUR_TOKEN&temperatureunit=fahrenheit
GET /v1/data/{uuid}?token=YOUR_TOKEN&strengthunit=psi

V1 Unit Conversion Parameters:

Parameter Values Description
temperatureunit celcius (default), fahrenheit Temperature display unit
strengthunit mpa (default), npermmsq, psi, kgpercmsq Strength display unit

Note: V2 does not support unit conversion via parameters; data is returned in default units (Celsius, MPa).

Response Structure:

				
					{
  "meta": { /* monitoring metadata object */ },
  "data": [ /* array of time-series data points */ ]
}

Data Point Fields:

Field Type V1 V2 Description
timestamp Unix timestamp ✓ ✓ Data point time
temperature Float ✓ ✓ Concrete temperature
temperature_unit String ✓ ✓ celcius or fahrenheit
maturity Float ✓* ✓* Maturity value (if enabled)
maturity_unit String ✗ ✓* Maturity unit: °C-Hours, °C-Days, etc. (if enabled)
strength Float ✓* ✓* Calculated strength (if enabled)
strength_unit String ✓* ✓* Strength unit: MPa, etc.
ambient_temperature Float ✗ ✓ Ambient/environmental temperature

*Only included if maturity/strength monitoring is enabled for this monitoring session.

Data Time Range:

  • Data is filtered by the monitoring’s start_time and end_time
  • If end_time is 0 or very small (<10), current time is used as the end boundary
  • Only data points between these timestamps are returned
  • Data is ordered chronologically (oldest first)

Concrete Library (V2 only)

Retrieve concrete mix designs from the organization’s material library.

List All Concrete Mixes

				
					GET /v2/concrete?token=YOUR_TOKEN

Returns all concrete mixes accessible to your token.

Get Specific Concrete Mix

				
					GET /v2/concrete/{id}?token=YOUR_TOKEN

Note: The id parameter is a numeric ID (not UUID).

Get Concrete Family (Legacy)

				
					GET /v2/concrete/{id}?token=YOUR_TOKEN&apiAction=legacy

Returns the parent concrete mix and all related variations (children). This endpoint:

  • Requires numeric id (not UUID)
  • Uses apiAction=legacy as a query parameter
  • Returns the concrete family tree based on parentId relationships
  • If the concrete has a parent, returns the parent and all siblings
  • If the concrete has no parent, returns just that concrete (unless it IS a parent with children)

Response Fields:

Field Type Description
concrete_id Integer Numeric concrete ID
concrete_name String Concrete mix name
maturity_function String Arrhenius, Nurse-Saul, or Dutch Weigthed Maturity (note: spelling as-is in API)
parameters Object Maturity function parameters (JSON object)
maturity_data Object Maturity curve data: {unit: "hours", data: {...}}
discontinuedAt Date/null Discontinuation date (if discontinued)
hidden Boolean Whether concrete mix is hidden
parentId Integer/null Parent concrete ID (for mix variations)
endpoints Object Related API endpoints

Further Questions

If after reading this article, you still have questions contact us for support.

    By clicking submit below, you consent to Maturix's Privacy Policy