---
title: "Sites"
description: "Model physical locations and the devices deployed there."
icon: "location-dot"
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

A **Site** is a physical location: an address with coordinates that groups the devices
deployed there. A Site is one kind of [Place](/platform/core-concepts#places) (the other is a
[Fleet](/console/fleets)). Inside a Site you build a tree of **levels** (for example
Site → Building → Floor → Room), and each device can sit at a specific level.

You can see all the sites in your organization and open any one to view its details: its
metadata, alerts, location, device metrics, and level structure. From a site you add devices,
manage monitors, edit or delete the site, and download aggregate data over a time range.

<Frame>
  <img src="/images/console/sites-detail.png" alt="A site detail page" />
</Frame>

## Configuration

### Site fields

Used when creating or editing a site.

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| Site name | string | Yes | Must be non-empty |
| Address | string | Yes | Must be non-empty |
| Latitude | number | Yes | `-90` to `90` |
| Longitude | number | Yes | `-180` to `180` |
| Displayed metrics | ordered list of metric ids | No | Metrics shown on the site dashboard |

Creating a site provisions its data infrastructure automatically, then opens the new site.

### Levels

Levels give a site internal structure. Each level has a **type** and a **parent**, forming a
tree under a root level.

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| Level type | select | Yes | From the site's defined level types; fixed once created |
| Level name | string | Yes | |
| Parent level | select | Yes (on create) | Limited to valid parent types for the chosen type |
| Description | string | No | |
| Address | string | No | |
| Latitude / Longitude / Altitude | number | No | |
| Attributes | key/value pairs | No | |

You can move a level to a new parent (limited to valid parent types for its type).

### Adding devices

Add a device to a site from its detail page. When the Place is a
site, the device requires a level. There's no separate "assign an existing device" step:
a device's site is its Place.

### Finding sites

Search matches a site's name or id.

## States

A site has **no status, health, or occupancy state**. There's no lifecycle field and no
health rollup.

### Deleting a site or level

Deleting first checks for dependent resources. If any exist, you confirm a **force delete**
that also removes them.

### Metrics summary

The data summary shows whatever metrics are in the site's displayed metrics list, each over
the selected time range. A `Last`-aggregation metric shows the latest reading across all
devices on the site.

## API

Send your API key in the `X-Api-Key` header. A `read` scope covers reads; `write` covers
create, update, and delete. Force delete requires an `admin` scope. Site and level ids are
plain GUIDs, with no prefix.

### Sites

| Method | Path | Purpose | Scope |
|--------|------|---------|-------|
| `GET` | `/v2/sites` | List sites (paginated) | `read` |
| `GET` | `/v2/sites/{placeId}` | Get one site | `read` |
| `POST` | `/v2/sites` | Create a site | `write` |
| `PUT` | `/v2/sites/{placeId}` | Update a site | `write` |
| `DELETE` | `/v2/sites/{placeId}` | Soft-delete a site | `write` |
| `GET` | `/v2/sites/{placeId}/delete-preview` | List what a force delete would remove | `write` |
| `DELETE` | `/v2/sites/{placeId}/force` | Force-delete, cascading dependents | `admin` |

Devices on a site come from the Thing endpoints (see [Devices](/console/devices)):
`GET /v2/sites/{placeId}/things`.

### Levels

<Note>Level management endpoints are **coming soon** to the v2 API.</Note>