Reference

Buildings

Sites and buildings — the top of the facility hierarchy.

A building is a site: a factory, a warehouse, an office, a hospital wing. Everything physical in Nexa sits inside one, and most reporting is grouped by them.

If you only need to read the structure, use the hierarchy endpoint rather than walking buildings, then floors, then rooms. It returns the whole tree in one call — which is one request against your rate limit instead of one per floor.

The building object

Field	Type	Description
`id`	uuid	Opaque.
`object`	string	Always "building".
`name`	string	Display name.
`description`	stringnullable	Free text.
`building_type`	string	One of office, residential, commercial, industrial, mixed_use, educational, healthcare, hospitality, warehouse, production_facility, industrial_process_facility, manufacturing_facility, warehouse_and_offices, other.
`physical_address`	string	Street address.
`area_sqm`	stringnullable	A decimal STRING, not a number.
`created_at`	timestamp	ISO 8601, UTC.
`updated_at`	timestamp	ISO 8601, UTC.

iduuid: Opaque.
objectstring: Always "building".
namestring: Display name.
descriptionstring · nullable: Free text.
building_typestring: One of office, residential, commercial, industrial, mixed_use, educational, healthcare, hospitality, warehouse, production_facility, industrial_process_facility, manufacturing_facility, warehouse_and_offices, other.
physical_addressstring: Street address.
area_sqmstring · nullable: A decimal STRING, not a number.
created_attimestamp: ISO 8601, UTC.
updated_attimestamp: ISO 8601, UTC.

{
  "id": "1f0a6e52-4a19-8c33-90ab-12cd34efb7d4",
  "object": "building",
  "name": "Plant 1",
  "description": "Main production site.",
  "building_type": "manufacturing_facility",
  "physical_address": "Zone Industrielle, Ben Arous",
  "area_sqm": "8400.00",
  "created_at": "2023-01-15T08:00:00.000Z",
  "updated_at": "2026-06-02T11:20:00.000Z"
}

Endpoints

List buildings

GET/buildings

Scope buildings:readPaginated

Accepts limit and cursor. See Pagination.

curl https://nexa.com.tn/api/v1/buildings \
  -H "Authorization: Bearer $NEXA_API_KEY"

const response = await fetch(
  "https://nexa.com.tn/api/v1/buildings",
  {
    headers: {
      Authorization: `Bearer ${process.env.NEXA_API_KEY}`,
    },
  },
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['NEXA_API_KEY']}",
}

response = requests.get(
    "https://nexa.com.tn/api/v1/buildings",
    headers=headers,
)
response.raise_for_status()
data = response.json()["data"]

Response

GET /v1/buildings

{
  "data": [
    {
      "id": "1f0a6e52-4a19-8c33-90ab-12cd34efb7d4",
      "object": "building",
      "name": "Plant 1",
      "description": "Main production site.",
      "building_type": "manufacturing_facility",
      "physical_address": "Zone Industrielle, Ben Arous",
      "area_sqm": "8400.00",
      "created_at": "2023-01-15T08:00:00.000Z",
      "updated_at": "2026-06-02T11:20:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "eyJvIjo1MH0"
  }
}

Retrieve a building

GET/buildings/{buildingId}

Scope buildings:read

Path parameters

Name	Type	Description
`buildingId`required	uuid	The building.

buildingIduuidrequired: The building.

curl https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef \
  -H "Authorization: Bearer $NEXA_API_KEY"

const response = await fetch(
  "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef",
  {
    headers: {
      Authorization: `Bearer ${process.env.NEXA_API_KEY}`,
    },
  },
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['NEXA_API_KEY']}",
}

response = requests.get(
    "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef",
    headers=headers,
)
response.raise_for_status()
data = response.json()["data"]

Response

GET /v1/buildings/{buildingId}

{
  "data": {
    "id": "1f0a6e52-4a19-8c33-90ab-12cd34efb7d4",
    "object": "building",
    "name": "Plant 1",
    "description": "Main production site.",
    "building_type": "manufacturing_facility",
    "physical_address": "Zone Industrielle, Ben Arous",
    "area_sqm": "8400.00",
    "created_at": "2023-01-15T08:00:00.000Z",
    "updated_at": "2026-06-02T11:20:00.000Z"
  }
}

Retrieve the full tree under a building

GET/buildings/{buildingId}/hierarchy

Scope buildings:read

Floors, their rooms and the assets in them, in one response. Use this to mirror the structure rather than issuing a request per floor.

Path parameters

Name	Type	Description
`buildingId`required	uuid	The building.

buildingIduuidrequired: The building.

curl https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef/hierarchy \
  -H "Authorization: Bearer $NEXA_API_KEY"

const response = await fetch(
  "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef/hierarchy",
  {
    headers: {
      Authorization: `Bearer ${process.env.NEXA_API_KEY}`,
    },
  },
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['NEXA_API_KEY']}",
}

response = requests.get(
    "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef/hierarchy",
    headers=headers,
)
response.raise_for_status()
data = response.json()["data"]

Response

GET /v1/buildings/{buildingId}/hierarchy

{
  "data": {
    "id": "1f0a6e52-4a19-8c33-90ab-12cd34efb7d4",
    "object": "building",
    "name": "Plant 1",
    "description": "Main production site.",
    "building_type": "manufacturing_facility",
    "physical_address": "Zone Industrielle, Ben Arous",
    "area_sqm": "8400.00",
    "created_at": "2023-01-15T08:00:00.000Z",
    "updated_at": "2026-06-02T11:20:00.000Z",
    "floors": [
      {
        "id": "0a6e524a-198c-4390-ab12-cd34efb7d41f",
        "object": "floor",
        "building_id": "1f0a6e52-4a19-8c33-90ab-12cd34efb7d4",
        "name": "Production hall",
        "level": 0,
        "created_at": "2023-01-15T08:05:00.000Z",
        "updated_at": "2023-01-15T08:05:00.000Z",
        "rooms": [
          {
            "id": "6e524a19-8c33-90ab-12cd-34efb7d41f0a",
            "object": "room",
            "floor_id": "0a6e524a-198c-4390-ab12-cd34efb7d41f",
            "name": "Line 2",
            "created_at": "2023-01-15T08:07:00.000Z",
            "updated_at": "2023-01-15T08:07:00.000Z",
            "assets": []
          }
        ]
      }
    ]
  }
}

Create a building

POST/buildings

Scope buildings:write

Body

Name	Type	Description
`name`required	string	Display name.
`physical_address`required	string	Street address.
`building_type`required	string	One of office, residential, commercial, industrial, mixed_use, educational, healthcare, hospitality, warehouse, production_facility, industrial_process_facility, manufacturing_facility, warehouse_and_offices, other. Anything else returns 400.One of: `office`, `residential`, `commercial`, `industrial`, `mixed_use`, `educational`, `healthcare`, `hospitality`, `warehouse`, `production_facility`, `industrial_process_facility`, `manufacturing_facility`, `warehouse_and_offices`, `other`
`description`	string	Free text.
`area_sqm`	number	Floor area.

namestringrequired: Display name.
physical_addressstringrequired: Street address.
building_typestringrequired: One of office, residential, commercial, industrial, mixed_use, educational, healthcare, hospitality, warehouse, production_facility, industrial_process_facility, manufacturing_facility, warehouse_and_offices, other. Anything else returns 400.
descriptionstring: Free text.
area_sqmnumber: Floor area.

curl -X POST https://nexa.com.tn/api/v1/buildings \
  -H "Authorization: Bearer $NEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "Plant 2",
       "physical_address": "Zone Industrielle, Ben Arous",
       "building_type": "manufacturing_facility"
     }'

const response = await fetch(
  "https://nexa.com.tn/api/v1/buildings",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEXA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
    "name": "Plant 2",
    "physical_address": "Zone Industrielle, Ben Arous",
    "building_type": "manufacturing_facility"
  }),
  },
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['NEXA_API_KEY']}",
}

response = requests.post(
    "https://nexa.com.tn/api/v1/buildings",
    headers=headers,
    json={
        "name": "Plant 2",
        "physical_address": "Zone Industrielle, Ben Arous",
        "building_type": "manufacturing_facility"
    },
)
response.raise_for_status()
data = response.json()["data"]

Response

POST /v1/buildings

{
  "data": {
    "id": "1f0a6e52-4a19-8c33-90ab-12cd34efb7d4",
    "object": "building",
    "name": "Plant 1",
    "description": "Main production site.",
    "building_type": "manufacturing_facility",
    "physical_address": "Zone Industrielle, Ben Arous",
    "area_sqm": "8400.00",
    "created_at": "2023-01-15T08:00:00.000Z",
    "updated_at": "2026-06-02T11:20:00.000Z"
  }
}

Update a building

PATCH/buildings/{buildingId}

Scope buildings:write

Path parameters

Name	Type	Description
`buildingId`required	uuid	The building.

buildingIduuidrequired: The building.

Body

Name	Type	Description
`name`	string	Display name.
`physical_address`	string	Street address.

namestring: Display name.
physical_addressstring: Street address.

curl -X PATCH https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef \
  -H "Authorization: Bearer $NEXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

const response = await fetch(
  "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef",
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.NEXA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  },
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

const { data } = await response.json();

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['NEXA_API_KEY']}",
}

response = requests.patch(
    "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef",
    headers=headers,
    json={},
)
response.raise_for_status()
data = response.json()["data"]

Response

PATCH /v1/buildings/{buildingId}

{
  "data": {
    "id": "1f0a6e52-4a19-8c33-90ab-12cd34efb7d4",
    "object": "building",
    "name": "Plant 1",
    "description": "Main production site.",
    "building_type": "manufacturing_facility",
    "physical_address": "Zone Industrielle, Ben Arous",
    "area_sqm": "8400.00",
    "created_at": "2023-01-15T08:00:00.000Z",
    "updated_at": "2026-06-02T11:20:00.000Z"
  }
}

Delete a building

DELETE/buildings/{buildingId}

Scope buildings:delete

Cascades to its floors and rooms. Assets in them are detached, not deleted.

Path parameters

Name	Type	Description
`buildingId`required	uuid	The building.

buildingIduuidrequired: The building.

curl -X DELETE https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef \
  -H "Authorization: Bearer $NEXA_API_KEY"

const response = await fetch(
  "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef",
  {
    method: "DELETE",
    headers: {
      Authorization: `Bearer ${process.env.NEXA_API_KEY}`,
    },
  },
);

if (!response.ok) {
  const { error } = await response.json();
  throw new Error(`${error.type}: ${error.message}`);
}

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['NEXA_API_KEY']}",
}

response = requests.delete(
    "https://nexa.com.tn/api/v1/buildings/b7d41f0a-6e52-4a19-8c33-90ab12cd34ef",
    headers=headers,
)
response.raise_for_status()

Returns 204 No Content with an empty body.

Developers

The building object

Endpoints

List buildings

Retrieve a building

Retrieve the full tree under a building

Create a building

Update a building

Delete a building