> For the complete documentation index, see [llms.txt](https://docs.raalabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raalabs.io/docs/api-endpoints.md).

# 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 scenarios and specify what API version should be used. Read about versioning [here](/getting-started/versioning.md).

### Common Path Parameters <a href="#common-path-parameters-domain-and-expression" id="common-path-parameters-domain-and-expression"></a>

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://portal.raalabs.io/{ENVIRONMENT}`. Replace `{ENVIRONMENT}` with your tenant name.