> 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/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](/settings/api-keys.md).
* `X-Organization-Id` — the organization the request operates in; it must match the key's organization. Some operations also require an `organizationId` query parameter. Provide that parameter in addition to the header; it does not replace the header.

All traffic is over TLS. Treat the key like a credential — see [Authentication & API keys](/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](/api/grpc-api.md).

## Workflow

1. Create a scoped key in [Settings → API Keys](/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](/api/examples.md).

## See also

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

For a service move, read the [data and format register](/trust-security-compliance/data-export-deletion-and-switching.md#data-and-format-register). A response from one operation is not a complete export of the service.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.