---
title: I3x Interoperability Api Guide 
description: The Timebase Historian implements the CESMII i3X API — a standard data exchange interface developed by the Clean Energy Smart Manufacturing Innovation Institute (CESMII).
---

[Skip to content](https://docs.timebase.flow-software.com/knowledge-base/i3x-interoperability-api-guide-#main-content)

[More support](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new?hsLang=en)

[![FlowEmailHeader](https://docs.timebase.flow-software.com/hs-fs/hubfs/FlowEmailHeader.png?width=120&height=33&name=FlowEmailHeader.png)](https://flow-software.com/)

Open main navigation

Close main navigation

- [More support](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new)
- [Open a Support Ticket](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new)

[Open a Support Ticket](https://docs.timebase.flow-software.com/knowledge-base/kb-tickets/new?hsLang=en)

 Search all Timebase documentation

- There are no suggestions because the search field is empty.

1. [Timebase Knowledge Base](https://docs.timebase.flow-software.com/knowledge-base?hsLang=en)
2. [Timebase Historian](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian?hsLang=en)

# I3x Interoperability Api Guide 

## The Timebase Historian implements the CESMII i3X API — a standard data exchange interface developed by the Clean Energy Smart Manufacturing Innovation Institute (CESMII).

#### Overview

The Timebase Historian implements the **CESMII i3X API** — a standard data exchange interface developed by the Clean Energy Smart Manufacturing Innovation Institute (CESMII). If you are using a platform that supports i3X (such as the CESMII Smart Manufacturing Platform), you can connect it directly to the Historian without writing any custom integration.

The i3X API gives those platforms a standard way to:

- **Browse** datasets and tags (Explore endpoints)
- **Read** the current value of any tag (Query — last known value)
- **Read** historical data for any tag over a time range (Query — history)

The i3X API is separate from the Historian's primary REST API and has its own documentation page at `/i3x/help`.

#### How to use the i3X API

### Finding the API

The i3X API is available at:

```
http://<historian>:4511/i3x/
```

Replace `<historian>` with the hostname or IP address of your Historian.

An interactive API documentation page (Swagger UI) is available at:

```
http://<historian>:4511/api/help/index.html
```

You can use the Swagger page to explore and test all i3X endpoints directly from your browser. Remeber to select the i3x definition in the swagger documents 

### Tag identifiers — ElementId

The i3X standard identifies every piece of data with an **ElementId**. In Timebase, the ElementId for a tag is:

```
{dataset}:{tagname}
```

For example, a tag named `131-TT-001.PV` in a dataset named `OPCUA Demo` has the ElementId:

```
OPCUA Demo:131-TT-001.PV
```

The colon (`:`) is the separator. Dataset names cannot contain a colon, so the separator is always unambiguous.

### Endpoints

All endpoints are under the `/i3x/` base path. The API is divided into two categories:

#### Explore — browse your data

| Endpoint | Method | What it returns |
| --- | --- | --- |
| `/i3x/namespaces` | GET | All datasets (each dataset is a namespace in i3X) |
| `/i3x/objects` | GET | All tags across all datasets |
| `/i3x/objects/list` | POST | Look up specific tags by ElementId |
| `/i3x/objecttypes` | GET | The single tag type definition used by all Timebase tags |
| `/i3x/relationshiptypes` | GET | Relationship types (always empty — Timebase tags are flat) |
| `/i3x/objects/related` | POST | Related objects (always empty — Timebase tags have no relationships) |

#### Query — read values

| Endpoint | Method | What it returns |
| --- | --- | --- |
| `/i3x/objects/value` | POST | The last known value for one or more tags |
| `/i3x/objects/history` | POST | Historical values for one or more tags over a time range |

### Reading the current value of a tag

Send a POST request to `/i3x/objects/value` with the ElementId of the tag you want:

```
POST /i3x/objects/valueContent-Type: application/json{  "elementId": "OPCUA Demo:131-TT-001.PV"}
```

To read multiple tags in one request, use `elementIds` instead:

```
POST /i3x/objects/valueContent-Type: application/json{  "elementIds": ["OPCUA Demo:131-TT-001.PV", "OPCUA Demo:131-PT-002.PV"]}
```

The response wraps results in a standard i3X batch format:

```
{  "results": [    {      "elementId": "OPCUA Demo:131-TT-001.PV",      "success": true,      "data": {        "elementId": "OPCUA Demo:131-TT-001.PV",        "isComposition": false,        "value": {          "value": 56.79,          "quality": "GOOD",          "timestamp": "2026-04-29T10:30:00.000Z"        }      },      "error": null    }  ],  "totalRequested": 1,  "totalSuccess": 1,  "totalFailed": 0}
```

### Reading historical data

Send a POST request to `/i3x/objects/history` with the ElementId and the time range you want. Both `startTime` and `endTime` are required:

```
POST /i3x/objects/historyContent-Type: application/json{  "elementId": "OPCUA Demo:131-TT-001.PV",  "startTime": "2026-04-29T00:00:00Z",  "endTime": "2026-04-29T01:00:00Z"}
```

Timestamps must be in ISO 8601 / RFC 3339 format (e.g., `2026-04-29T14:30:00Z`). The response contains an array of VQT (Value-Quality-Timestamp) records for the requested period.

### Quality values

The i3X API returns quality as a string rather than a numeric code. The mapping from Timebase quality codes is:

| Timebase quality code | i3X quality string |
| --- | --- |
| 192 (Good) | `GOOD` |
| 64 (Uncertain) | `UNCERTAIN` |
| 0 (Bad) | `BAD` |

### Batch requests — single vs. multiple tags

All query and look-up endpoints support both single and batch requests. Use exactly one of:

- `"elementId": "..."` — for a single tag
- `"elementIds": ["...", "..."]` — for multiple tags

Providing both, or neither, returns a `422 Unprocessable Entity` error.

In batch responses, each tag's result appears separately in the `results` array. If one tag is not found, its entry shows `"success": false` with an error message — the other tags in the same request are still returned successfully.

### Authentication

As of Timebase 1.3.1, authentication is not yet enforced on the i3X API endpoints. CORS is enabled, so cross-origin browser requests work without additional configuration. Authentication enforcement will be added in a future release.

#### Troubleshooting

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| HTTP 422 — "elementId and elementIds are mutually exclusive" | Both `elementId` and `elementIds` were provided in the same request body | Use only one: `elementId` for a single tag, or `elementIds` for multiple. Never both in the same request |
| HTTP 422 — "startTime or endTime missing" | The `/objects/history` endpoint requires both `startTime` and `endTime` in the request body | Add both fields to your request body as ISO 8601 timestamps (e.g., `2026-04-29T00:00:00Z`) |
| Result shows `"success": false` with "ElementId not found" | The dataset name, tag name, or separator in the ElementId does not match exactly | Check the ElementId format: `{dataset}:{tagname}`. The dataset name and tag name are case-sensitive. Use `GET /i3x/namespaces` to list dataset names and `GET /i3x/objects` to list tag ElementIds |
| History endpoint returns an empty `data` array for a tag that has data | The requested time range does not overlap with the period when data was recorded for that tag | Widen the time range. Confirm the tag has data by opening it in the Historian's Tag Data View. Check that the `startTime` and `endTime` are in UTC, not local time |
| Cannot reach `/i3x/help` Swagger page | The Historian is not running, or the port is blocked by a firewall | Confirm the Historian is running via the Services Starter (`localhost:4510`). The i3X API uses the same port as the Historian (default 4511). Check that port 4511 is open from your machine to the Historian host |

- [Software Releases](https://docs.timebase.flow-software.com/knowledge-base/software-releases?hsLang=en)
- [Timebase Quick Start](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#main-content)

    - [Start Here!](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#start-here)
    - [System Requirements](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#system-requirements)
    - [Advanced Topics](https://docs.timebase.flow-software.com/knowledge-base/timebase-quick-start?hsLang=en#advanced-topics)
- [Timebase Historian](https://docs.timebase.flow-software.com/knowledge-base/timebase-historian?hsLang=en)
- [Timebase Data Collectors](https://docs.timebase.flow-software.com/knowledge-base/timebase-data-collectors?hsLang=en)
- [Timebase Explorer](https://docs.timebase.flow-software.com/knowledge-base/timebase-explorer?hsLang=en)
- [Timebase Pulse](https://docs.timebase.flow-software.com/knowledge-base/timebase-pulse?hsLang=en)
- [Windows Services Starter](https://docs.timebase.flow-software.com/knowledge-base/windows-services-starter?hsLang=en)

Copyright © 2025, Flow Software