Facilities

Facilities & Units API

Organize your assets with a hierarchical location structure. Define facilities (buildings, plants) and units (production lines, cells, areas) to group machines and track assets by location.

11 FeaturesLocation HierarchyAsset Organization

Overview

Hierarchy

Organization
└── Facility (Building/Plant)
    └── Unit (Line/Cell/Area)
        └── Machine

Use Cases

• Group machines by building
• Filter assets by production line
• Generate location-based reports
• Navigate physical layout

Facilities

Facilities represent physical locations like buildings, plants, or sites where your equipment is located.

GET/v1/facilitiesAuth Required

List Facilities

Get all facilities in the organization.

Parameters

include_unitsboolean

Include nested units

include_machine_countboolean

Include machine counts

Response

Responsejson

{
  "facilities": [
    {
      "id": "fac_001",
      "name": "Main Plant",
      "description": "Primary manufacturing facility",
      "address": "123 Industrial Drive, City, State 12345",
      "coordinates": {
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      "units_count": 5,
      "machines_count": 25,
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "fac_002",
      "name": "West Building",
      "description": "Assembly and testing area",
      "address": "125 Industrial Drive, City, State 12345",
      "units_count": 3,
      "machines_count": 12,
      "created_at": "2024-02-20T14:30:00Z"
    }
  ],
  "total": 2
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/facilities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST/v1/facilitiesAuth Required

Create Facility

Create a new facility location.

Request Body

Requestjson

{
  "name": "East Campus",
  "description": "New expansion facility",
  "address": "500 Technology Parkway, City, State 12345",
  "coordinates": {
    "latitude": 40.7200,
    "longitude": -74.0100
  },
  "metadata": {
    "square_footage": 50000,
    "year_built": 2024
  }
}

Response

Responsejson

{
  "id": "fac_003",
  "name": "East Campus",
  "description": "New expansion facility",
  "address": "500 Technology Parkway, City, State 12345",
  "coordinates": {
    "latitude": 40.7200,
    "longitude": -74.0100
  },
  "metadata": {
    "square_footage": 50000,
    "year_built": 2024
  },
  "created_at": "2024-08-26T15:30:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/facilities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/facilities/{facility_id}Auth Required

Get Facility

Get a specific facility with its units and machines.

Parameters

facility_idstringRequired

Facility identifier

Response

Responsejson

{
  "id": "fac_001",
  "name": "Main Plant",
  "description": "Primary manufacturing facility",
  "address": "123 Industrial Drive, City, State 12345",
  "units": [
    {
      "id": "unit_001",
      "name": "Production Line A",
      "machines_count": 8
    },
    {
      "id": "unit_002",
      "name": "Production Line B",
      "machines_count": 10
    }
  ],
  "total_machines": 25,
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-08-20T12:00:00Z"
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/facilities/{facility_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

PUT/v1/facilities/{facility_id}Auth Required

Update Facility

Update facility information.

Parameters

facility_idstringRequired

Facility identifier

Request Body

Requestjson

{
  "name": "Main Plant - Building A",
  "description": "Updated description",
  "metadata": {
    "shift_count": 3
  }
}

Response

Responsejson

{
  "id": "fac_001",
  "name": "Main Plant - Building A",
  "description": "Updated description",
  "updated_at": "2024-08-26T16:00:00Z"
}

Try it out

cURLbash

curl -X PUT "https://sapienstream.com/api/v1/facilities/{facility_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

DELETE/v1/facilities/{facility_id}Auth Required

Delete Facility

Delete a facility. Fails if facility contains units with machines.

Parameters

facility_idstringRequired

Facility identifier

Response

Responsejson

{
  "deleted": true,
  "facility_id": "fac_003"
}

Try it out

cURLbash

curl -X DELETE "https://sapienstream.com/api/v1/facilities/{facility_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Units

Units are subdivisions within facilities, such as production lines, work cells, or areas.

GET/v1/unitsAuth Required

List Units

Get all units, optionally filtered by facility.

Parameters

facility_idstring

Filter by facility

include_machinesboolean

Include machine list

Response

Responsejson

{
  "units": [
    {
      "id": "unit_001",
      "name": "Production Line A",
      "description": "High-volume CNC machining line",
      "facility_id": "fac_001",
      "facility_name": "Main Plant",
      "machines_count": 8,
      "created_at": "2024-01-20T10:00:00Z"
    },
    {
      "id": "unit_002",
      "name": "Production Line B",
      "description": "Precision parts manufacturing",
      "facility_id": "fac_001",
      "facility_name": "Main Plant",
      "machines_count": 10,
      "created_at": "2024-01-22T14:00:00Z"
    }
  ],
  "total": 8
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/units" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST/v1/unitsAuth Required

Create Unit

Create a new unit within a facility.

Request Body

Requestjson

{
  "facility_id": "fac_001",
  "name": "Assembly Cell C",
  "description": "Final assembly and testing",
  "metadata": {
    "capacity": 5,
    "cell_type": "assembly"
  }
}

Response

Responsejson

{
  "id": "unit_new_001",
  "facility_id": "fac_001",
  "name": "Assembly Cell C",
  "description": "Final assembly and testing",
  "metadata": {
    "capacity": 5,
    "cell_type": "assembly"
  },
  "machines_count": 0,
  "created_at": "2024-08-26T15:30:00Z"
}

Try it out

cURLbash

curl -X POST "https://sapienstream.com/api/v1/units" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/v1/units/{unit_id}Auth Required

Get Unit

Get a specific unit with its machines.

Parameters

unit_idstringRequired

Unit identifier

Response

Responsejson

{
  "id": "unit_001",
  "name": "Production Line A",
  "description": "High-volume CNC machining line",
  "facility": {
    "id": "fac_001",
    "name": "Main Plant"
  },
  "machines": [
    {
      "id": "mach_001",
      "name": "CNC Mill #1",
      "model": "VMC-850"
    },
    {
      "id": "mach_002",
      "name": "CNC Mill #2",
      "model": "VMC-850"
    }
  ],
  "machines_count": 8,
  "created_at": "2024-01-20T10:00:00Z"
}

Try it out

cURLbash

curl -X GET "https://sapienstream.com/api/v1/units/{unit_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

PUT/v1/units/{unit_id}Auth Required

Update Unit

Update unit information.

Parameters

unit_idstringRequired

Unit identifier

Request Body

Requestjson

{
  "name": "Production Line A - High Speed",
  "description": "Updated: High-speed CNC machining line"
}

Response

Responsejson

{
  "id": "unit_001",
  "name": "Production Line A - High Speed",
  "updated_at": "2024-08-26T16:00:00Z"
}

Try it out

cURLbash

curl -X PUT "https://sapienstream.com/api/v1/units/{unit_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

DELETE/v1/units/{unit_id}Auth Required

Delete Unit

Delete a unit. Machines must be reassigned first.

Parameters

unit_idstringRequired

Unit identifier

Response

Responsejson

{
  "deleted": true,
  "unit_id": "unit_003"
}

Try it out

cURLbash

curl -X DELETE "https://sapienstream.com/api/v1/units/{unit_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Machine Location Assignment

PUT/v1/machines/{machine_id}/locationAuth Required

Assign Machine Location

Assign or move a machine to a facility/unit.

Parameters

machine_idstringRequired

Machine identifier

Request Body

Requestjson

{
  "facility_id": "fac_001",
  "unit_id": "unit_001"
}

Response

Responsejson

{
  "machine_id": "mach_001",
  "location": {
    "facility_id": "fac_001",
    "facility_name": "Main Plant",
    "unit_id": "unit_001",
    "unit_name": "Production Line A"
  },
  "previous_location": {
    "facility_id": "fac_002",
    "unit_id": "unit_005"
  },
  "updated_at": "2024-08-26T15:30:00Z"
}

Try it out

cURLbash

curl -X PUT "https://sapienstream.com/api/v1/machines/{machine_id}/location" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Location Hierarchy Example

// Build location tree for facility selector
async function buildLocationTree() {
  const facilities = await fetch('/api/facilities?include_units=true')
    .then(r => r.json());

  return facilities.facilities.map(facility => ({
    id: facility.id,
    label: facility.name,
    type: 'facility',
    children: facility.units?.map(unit => ({
      id: unit.id,
      label: unit.name,
      type: 'unit',
      machineCount: unit.machines_count
    })) || []
  }));
}

// Result:
// [
//   {
//     id: 'fac_001',
//     label: 'Main Plant',
//     type: 'facility',
//     children: [
//       { id: 'unit_001', label: 'Production Line A', type: 'unit', machineCount: 8 },
//       { id: 'unit_002', label: 'Production Line B', type: 'unit', machineCount: 10 }
//     ]
//   }
// ]