---
title: "Core concepts"
description: "An overview of our platform entities"
icon: "cubes"
---

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

Every API call references these entities, from your organization down to a device and its
telemetry.

> A related, deeper topic (**how you define device *types* and the data they produce**)
> has its own doc: [Data model](/platform/data-model). This page covers the
> "live" entities; the ontology covers the schema that describes them.

## Overview

Everything nests under your **organization**, which holds:

- **Sites**: physical locations (a kind of "Place"), each with internal levels.
- **Fleets**: logical groups of Things (the other kind of "Place"), such as vehicles.
- **Integrations**: connections to external systems that feed your Things.

A **Thing** (a device or asset) lives in a Site or Fleet. Each Thing is typed by a **Thing
Type Definition**, and it emits **telemetry**: timestamped metric readings.

## Organization

An **Organization** is your account context and the hard isolation boundary. Your
credentials scope you to one organization, and you can only ever see resources within it.
Organizations can be arranged in a hierarchy (a parent org with child orgs), which mirrors
real customer structures.

Everything else (Sites, Fleets, Things, Integrations, type definitions) belongs to an
organization. You rarely pass the org id explicitly: it's derived from your API key or token.

> Behind the scenes there's also a **Tenant** above the organization (the top-level
> account/region container). As an integrator you mostly operate at the organization level;
> tenancy is the platform's outer isolation layer.

## Places

A **Place** is a container that Things belong to. There are two kinds:

### Site

A **physical location**: a depot, charging hub, or building. A Site has internal
structure (**levels** and **level groups**, e.g. floors, zones, or bays), and Things can be
installed at a specific level. A Site has coordinates and an address.

### Fleet

A **logical grouping** of Things, most naturally a set of vehicles. Unlike a Site, a Fleet
isn't tied to one physical location. It's a grouping over a set of devices, and it can span
multiple Sites.

> **Why "Place" matters in the API:** many endpoints are addressed as
> `…/{placeType}/{placeId}/…`, where `placeType` is `site` or `fleet`. A Thing always
> belongs to a Place, and you'll reference that Place when ingesting and querying its data.

## Thing

A **Thing** is the universal model for a device or asset: a battery, swap station, charger,
meter, inverter, solar array, or vehicle. Almost everything in the platform exists to describe
Things, route their data, or act on it.

A Thing carries several kinds of information:

**Identity**

| Field | Meaning |
|-------|---------|
| `thingId` | Globally unique id (`<thingId>`). |
| `thingName` | Friendly name. |
| `thingType` | The device category (e.g. `Battery`, `SwapStation`). |
| `thingDescription`, `address` | Optional human context. |

**Hardware**

| Field | Meaning |
|-------|---------|
| `manufacturer`, `model` | Hardware identity (default to `UNKNOWN`). |
| `thingManufacturerId` | The device's id in the manufacturer's own system. |

**Placement**

| Field | Meaning |
|-------|---------|
| `placeType`, `placeId` | Which Place (Site or Fleet) the Thing belongs to. |
| `levelId` | Which level of a Site it's installed at (optional). |
| `latitude`, `longitude`, `altitude` | Physical location. |

**Configuration & metadata**

| Field | Meaning |
|-------|---------|
| `properties` | Static, pre-defined attributes (e.g. a battery's capacity). Validated against the Thing's type definition. |
| `attributes` | Arbitrary free-form key/value metadata. |
| `isSimulated` | Whether the Thing is real or part of a simulation. |
| `integrationIds` | Which integrations feed this Thing. |

**Type linkage**

| Field | Meaning |
|-------|---------|
| `thingTypeDefIndexId` | The stable id of the Thing's *type* (`tdefi_…`). |
| `thingTypeDefId` | The specific *version* of that type definition the Thing follows. This determines which metric set applies to it. |

The type linkage is the bridge to the next doc: a Thing's **Thing Type Definition** is what
tells the platform which metrics it's allowed to report and which properties it can carry.
See [Data model](/platform/data-model).

## Device categories

Common Thing categories you'll encounter: **Battery**, **SwapStation**, **Charger**,
**Meter**, **Inverter**, and **Solar**. These are broad categories; the precise contract for
each kind of device (its exact metrics and properties) comes from its Thing Type
Definition, which you define and version yourself.

## Telemetry

The measurements a Thing reports are time-series:

- A **data point** is a single reading: a metric (by id/name), a value, and a unit.
  For example `{ "type": "soc", "value": 87, "unit": "%" }`.
- Readings are grouped into timestamped frames and sent in via the Aerovy Platform API.
- Each metric corresponds to a **Metric Definition** in your ontology: that's how a raw
  number gains meaning (e.g. "State of Charge, 87%").

How to send and read these is covered in [Ingesting data](/platform/ingesting-data) and
[Querying data](/platform/querying-data).

## Integrations

An **Integration** is a configured connection to an external system (Geotab,
Zubie, UtilityAPI, and others) that feeds data into your Things (or sends notifications
out). Configure an Integration once and the platform maps external devices onto your Things,
so telemetry arrives without you POSTing it yourself.

## Other terms

| Term | One-liner |
|------|-----------|
| **Level / Level Group** | The internal structure of a Site: floors, zones, bays. |
| **Monitor** | A rule that watches metrics and raises alerts when a condition is met. |
| **Metric / Metric Definition** | A measured quantity and its schema (see the Data model doc). |
| **Transaction** | A business event: payment, battery-swap reservation, control action, invoice. |
| **API Key** | A credential for app-to-app access (see [API fundamentals](/platform/api-fundamentals)). |