# 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 remains the primary way to integrate with Hiboo and covers most use cases (fleet browsing, history, snapshots, reporting). The Kafka API complements it when you need:

* **Real-time data**: events are pushed as soon as they are processed by Hiboo, with no polling delay.
* **Push-based integrations**: ideal for streaming pipelines, data lakes, and event-driven architectures.
* **High-throughput ingestion**: built to handle large fleets without worrying about pagination or rate management.

> If you are 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 specific onboarding.

## Authentication with mTLS

Access to the Kafka API is secured using **mutual TLS (mTLS)**. Unlike the REST API, there are no `x-access-token` headers: 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 **topic** you are authorized to consume

> Treat the private key like any other secret. Store it securely, never commit it to source control, and ask for a new one if you suspect it was exposed.

## Topic & message format

Each customer is provisioned with a **single dedicated topic** on which all their time-series data is published. You do not need to subscribe to multiple topics: every `dataKind` (positions, fault codes, fuel, operating hours, …) 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",
  "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,
  "dataKind": "position"
}
```

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). It can also be **`date`** for daily data kinds.
* **`dataKind`**: the type of data carried by the message. Use it to route messages to the right handler on your side.

## 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 will provision your certificates and share the broker endpoints.
3. You can then connect from any Kafka-compatible client (Java, Python `confluent-kafka`, etc.) configured for mTLS.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hiboo.io/kafka-api-reference/kafka.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.