API Endpoints

Overview

The API is organized into three main categories of endpoints, each serving a different purpose:

• Measurements (Time Series) Endpoints: Retrieve actual time-series data points (raw sensor measurements over time).

• Metadata Endpoints: Retrieve descriptive information (metadata) about time series tags (e.g. name, description, units, source of a sensor).

• Statistics Endpoints: Retrieve aggregated statistics (computed metrics) on time-series data over specified time windows.

All endpoint URLs include a domain and an expression as path parameters, which together specify what data you are querying. The domain represents a context or naming schema (for example, a standard for tag names), and the expression is a query string identifying one or many time series within that domain.

Common Headers

There are two common headers:

• the Authorization header is required for all endpoints

• the x-api-version header is optional, but it is strongly encouraged to use this header in production scenaries and specify what API version should be used. Read about versioning here.

Common Path Parameters

Every endpoint path includes {domain}/{expression}:

• domain: The contextual domain or naming scheme for the data. For example: jsmea (Japan Ship Machinery and Equipment Association standard for ISO 19848), raalabs (a flat naming scheme used by Raa Labs), id (the raw UUID of a time series), etc. The domain determines how the API interprets the expression part.

• expression: A query string that identifies the hierarchy or path of the data requested within the chosen domain. This could be a full specific path to a tag or include wildcard characters (*) to match multiple items.

Wildcard Support: You can use * in expressions to match individual levels of the hierarchy (matching multiple hierarchy levels is not supported), allowing broad queries. This is similar to wildcards in MQTT topics. For example:

• Hierarchical Path Example: IMO1234567/411.1/C101.61/S203/meta/qty-mass.flow.rate – a full path locating a specific measurement in the hierarchy (for a given IMO number and subsystem).

• Wildcard Example: IMO1234567/*/qty-mass.flow.rate – uses * to match any value in the second level, returning all measurements ending in qty-mass.flow.rate for the vessel IMO1234567.

When you query data, the domain and expression together determine which time series are returned. You can retrieve a single tag's data or use wildcards to retrieve multiple related tags in one query.

All examples in this documentation use curl with the base URL: https://prism.raalabs.io/{ENVIRONMENT}. Replace {ENVIRONMENT} with your tenant name.