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

# Kafka API

Alongside our REST API, Hiboo also exposes a **Kafka API** for customers who need equipment data delivered as a continuous, low-latency stream rather than fetched on demand.

## When to use the Kafka API

The REST API is the primary way to integrate with Hiboo and covers most use cases: fleet browsing, history, snapshots, and reporting. The Kafka API complements it when you need:

* **Real-time data**: events are pushed as soon as Hiboo processes them, with no polling delay.
* **Push-based integrations**: a natural fit for streaming pipelines, data lakes, and event-driven architectures.
* **High-throughput ingestion**: built to handle large fleets without the overhead of pagination or rate management.

> Not sure which one you need? Start with the REST API. The Kafka API is an add-on for streaming use cases and requires a dedicated onboarding.

## Authentication with mTLS

The Kafka API is secured with **mutual TLS (mTLS)**. Unlike the REST API, it uses no `x-access-token` header: the client proves its identity with a certificate issued by Hiboo.

When your Kafka access is provisioned, Hiboo provides:

* A **client certificate** (`.crt`)
* A **private key** (`.key`)
* The **CA certificate** used to verify the broker (`ca.crt`)
* The list of **bootstrap brokers** and the **topic** you are authorized to consume

> Treat the private key like any other secret: store it securely, never commit it to source control, and request a new one if you suspect it has been exposed.

## Topic & message format

Each customer is provisioned with a **single dedicated topic** carrying all of their time-series data. There is no need to subscribe to multiple topics: every `dataKind` (positions, fault codes, fuel, operating hours, and so on) flows through the same stream.

Each message is a JSON object. The `dataKind` field tells you which type of data you are reading.

**Example — position message:**

```json
{
  "assetId": 123456,
  "datetime": "2026-04-22T14:49:07.000Z",
  "dataKind": "position",
  "dataSourceCode": "ocean",
  "latitude": 48.85837,
  "longitude": 2.294481,
  "postalAddress": "5 Av. Anatole France, 75007 Paris, France",
  "timezone": "Europe/Paris",
  "altitude": null,
  "speed": 26,
  "heading": null,
  "precision": null,
  "origin": null
}
```

**Example — battery voltage message:**

```json
{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "battery_voltage",
  "dataSourceCode": "volvotrucks_connect",
  "volts": 12.5
}
```

**Example — fault codes message:**

```json
{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "fault_codes",
  "dataSourceCode": "volvotrucks_connect",
  "level": 2,
  "label": "D1DIG.1",
  "description": "GPMECU - General Purpose Machine Electronic Control Unit 1"
}
```

**Example — sensor boolean message:**

```json
{
  "assetId": 100,
  "datetime": "2024-09-14T13:08:35.000Z",
  "dataKind": "sensor_boolean",
  "dataSourceCode": "samsara",
  "type": "checkEngineLights.stopIsOn",
  "status": false
}
```

Key fields to know:

* **`assetId`**: the Hiboo equipment identifier, matching the `id` returned by the REST fleet endpoints.
* **`datetime`**: the UTC timestamp of the event (ISO 8601). Daily data kinds use **`date`** instead.
* **`dataKind`**: the type of data carried by the message. Use it to route each message to the right handler on your side.
* **`dataSourceCode`**: the source provider of the message.

## Getting access

The Kafka API is not self-service. To request access:

1. Contact us at [support@hiboo.io](mailto:support@hiboo.io?Subject=\[Hiboo%20API]%20Kafka%20access%20request) with your use case and expected volume.
2. Our team provisions your certificates and shares the broker endpoints.
3. Connect from any Kafka-compatible client (Java, Python `confluent-kafka`, and others) configured for mTLS.