> ## Documentation Index
> Fetch the complete documentation index at: https://docs.azalt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Site

> Hierarchy, schema, access, and operations

## Overview

Sites are hierarchical locations inside an organization. They form a tree under a root site (`site-root-*`). All site operations are org-scoped and site-access-scoped.

## Schema (output)

Key fields returned by APIs:

```ts theme={null}
{
  id: string,
  name: string,
  createdAt: Date,
  updatedAt: Date,
  parentSiteId: string | null,
  country: string | null,
  city: string | null,
  address: string | null,
  unLocode: string | null,
  longitude: string | null,
  latitude: string | null,
  numberOfEmployees: number | null,
  floorAreaInM2: number | null,
  tags: string[] | null,
  metadata: Record<string, string> | null,
}
```

Note: `longitude` and `latitude` are strings in responses.

## Hierarchy & Access

* Root site is created per organization; cannot be deleted.
* Effective access for a user = assigned sites + all descendants (via `OrganizationUserSite`).
* Listing (`sites.list`) returns only sites in your accessible set (optionally including root as "Organization").

## Operations

* List sites: `sites.list({ includeRoot?: boolean })`
* Create site: `sites.create({ name, organizationId, parentSiteId?, ... })`
* Update site: `sites.update({ id, name, ... })`
* Delete site: `sites.delete({ id, cascade?: boolean })` (soft-delete; `cascade` to delete descendants)
* Import CSV: `sites.import({ organizationId, csvContent })` (bulk create with validation)

All operations validate organization and site access (RBAC + ABAC) and use RLS.

## CSV Import

Supported columns (header examples):

* `id?`, `name` (required)
* `parentSiteId?` (must exist in DB or in the same CSV)
* `country?`, `city?`, `address?`, `unLocode?`
* `longitude?`, `latitude?`
* `numberOfEmployees?`, `floorAreaInM2?`
* `tags?` (comma or `|` separated)
* `metadata_*` (e.g., `metadata_sapId` → `{ sapId: "..." }`)

Behavior:

* Validates and topologically sorts rows (parents before children); detects cycles.
* Batch inserts per dependency level.
* Returns success/failed counts and detailed errors (with row numbers).

## Best Practices

* Keep the hierarchy shallow; assign region nodes to managers, leaf nodes to collectors.
* Populate `numberOfEmployees` and `floorAreaInM2` for intensity calculations.
* Use `tags` and `metadata_*` for external IDs and filtering.
* Prefer `cascade` delete only when you’re sure about removing descendants.

## Gotchas

* Root site cannot be deleted.
* Coordinates are strings; convert to numbers if you need math.
* Deleting a site is soft-delete (sets `deletedAt`).

## See Also

* Organization (settings, membership)
* Organization User (roles)
* Organization User Site (site assignments and effective access)