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

# REST API

The REST API is how you connect your own scripts and tools to Chirp over normal HTTPS. If you can make an authenticated web request — from Python, a shell, a spreadsheet add-on, or another home-automation platform — you can use it.

Use the [API reference](https://api.chirpwireless.io/) for the full list of calls, their parameters, responses, and required scopes.

## What every request needs

* `X-API-Key` — a key you create in [Settings → API Keys](/settings/api-keys.md).
* `X-Organization-Id` — your home's ID; it has to match the home the key belongs to. A few calls also accept it as an `organizationId` query value instead of the header.

Everything goes over a secure (TLS) connection. Look after the key like a password — see [Authentication & API keys](/api/authentication-and-api-keys.md).

## What the API can do

REST is the broad, everyday way in. Depending on the scopes you give the key, a script can work across your home's data — for example: read your account; list your sensors and manage their setup, including how each one is wired to a connection and which readings it maps to; pull **history and latest readings** (great for spreadsheets and charts); read and change connections; read and build dashboards and widgets; read your home and subscription details; read and manage your automations, including their saved versions; and set up and send **device commands** to control your gear.

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

## Getting started

1. Make a scoped key in [Settings → API Keys](/settings/api-keys.md) and save it somewhere safe.
2. Find the call you want in the API reference.
3. Send it with the two headers above.
4. Read the JSON that comes back.

There's a copy-paste starter in [Examples](/api/examples.md).

## See also

* [gRPC API](/api/grpc-api.md) — only if you specifically need typed clients.
* [Authentication & API keys](/api/authentication-and-api-keys.md)
* [API Keys](/settings/api-keys.md)


---

# 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.chirpwireless.io/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.