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

# Public REST API

Kilo IoT Server Public REST API — primary integration surface over HTTPS/JSON with X-API-Key and X-Organization-Id.

The REST API is the primary way to integrate Kilo IoT Server with external systems over standard HTTPS. Any language or tool that can make an authenticated HTTP request can use it — backend services, data pipelines, reporting jobs, and operational tooling.

Use the [API reference](https://api.kiloiot.io/) for the full list of endpoints, request parameters, response schemas, and required scopes.

## Base endpoint and authentication

Requests go to the secured production endpoint and carry two headers:

* `X-API-Key` — a scoped key created in [Settings → API Keys](/kilo-iot-server/settings/api-keys.md).
* `X-Organization-Id` — the organization the request operates in; it must match the key's organization. Some operations also accept the organization as an `organizationId` query parameter instead of the header.

All traffic is over TLS. Treat the key like a credential — see [Authentication & API keys](/kilo-iot-server/api/authentication-and-api-keys.md).

## What the API can do

REST is the broad, primary surface. Subject to the scopes granted to the key, integrations can work across the platform — for example: read the account/user profile; list and manage devices and their **physical-device configuration** (the client device ID, the connection it binds to, and connection-specific settings), their sensors and sensor mappings, and sensor templates; read sensor **history and last-seen** values; read connector definitions and manage connections; read and manage dashboards and widgets; read organization, membership, and subscription data; read and manage automation **rule definitions, along with their versions and builds**; and define and dispatch **device commands** to control hardware.

For typed service-to-service or on-premise integrations, see [gRPC API](/kilo-iot-server/api/grpc-api.md).

## Workflow

1. Create a scoped key in [Settings → API Keys](/kilo-iot-server/settings/api-keys.md) and store it securely.
2. Find the operation you need in the API reference.
3. Call it with `X-API-Key` and `X-Organization-Id`.
4. Handle standard HTTP status codes and JSON responses.

A minimal authenticated call is in [Examples](/kilo-iot-server/api/examples.md).

## See also

* [gRPC API](/kilo-iot-server/api/grpc-api.md) — when typed clients or service-to-service calls fit better.
* [Authentication & API keys](/kilo-iot-server/api/authentication-and-api-keys.md)
* [API Keys](/kilo-iot-server/settings/api-keys.md) — create and manage keys.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.kiloiot.io/kilo-iot-server/api/public-rest-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.