Skip to content

CRUD REST APIs

All APIs are available on the /docs (Swagger)

Those tagged 'CRUD' provide simple query capabilities listed hereunder.

Queries

List of bundles

A bundle represents a master set of data initiated by the import of an IFC file

GET /common/bundle-list

Parameters:

  • from_date: YYYY-MM-DD (can be null)
  • to_date: YYYY-MM-DD (can be null)
  • limit: max number of rows returned, default = 100

Details of a Bundle

GET /common/bundle/{bundle_id}

Parameters:

  • bundle_id: id of the bundle

Result example:

{
  "bundle": {
    "source_type": "IFC",
    "header": {
      "type": "ifcJSON",
      "version": "0.0.1",
      "schemaIdentifier": "IFC2X3",
      "originatingSystem": "IFC2JSON_python Version 0.0.1",
      "preprocessorVersion": "IfcOpenShell 0.8.0",
      "timeStamp": "2025-04-14T11:44:41"
    },
    "description": "IfcJson File",
    "active": true,
    "created_at": "2025-04-14T11:44:43.067556",
    "files": {
      "ifcJsonFileURL": "IFCJSON/ad694f29-f520-4f21-97a4-ddc2db47625a_NI.json"
    },
    "bundle_id": 125,
    "parent_id": null,
    "name": "Duplex_A_20110907_optimized",
    "created_by": null,
    "updated_at": null,
    "updated_by": null
  }
}

Bundle Journal

The BundleJournal records the tasks that are performed on a bundle and provides for each one the corresponding xxx_Instruction and xxx_Result. When several instructions are executed, such as in the exemple below, the xxx_Instruction and xxx_Result are not specifically listed in the order of execution.

GET /common/bundle-journal/{bundle_id}/

Parameters:

  • bundle_id: id of the bundle
  • from_date: YYYY-MM-DD (can be null)
  • to_date: YYYY-MM-DD (can be null)
  • limit: max number of rows returned, default = 100

Result example:

{
  "bundleJournalItems": [
    {
      "created_at": "2025-04-14T11:44:43.687499",
      "bundle_id": 125,
      "updated_by": null,
      "operation_json": {
        "operation": "import_and_process_ifc",
        "instruction": {
          "ConvertIfcToIfcJson_Instruction": {
            "sourceFileURL": "http://localhost:8002/IFC_SOURCE_FILES/Duplex_A_20110907_optimized.ifc"
          },
          "StoreIfcJsonInDb_Instruction": {
            "spatialUnitId": "5f2d17b0-43fb-445d-9c67-7dafb3292c33",
            "bundleName": "Duplex_A_20110907_optimized",
            "parentBundleId": null,
            "sourceFileURL": "IFCJSON/ad694f29-f520-4f21-97a4-ddc2db47625a_NI.json"
          }
        },
        "result": {
          "ConvertIfcToIfcJson_Result": {
            "rootObjectId": "7b7032cc-b822-417b-9aea-642906a29bd5",
            "rootObjectType": "IfcProject",
            "rootObjectName": "0001",
            "resultPath": "IFCJSON/ad694f29-f520-4f21-97a4-ddc2db47625a_NI.json",
            "runtime": 1.16
          },
          "StoreIfcJsonInDb_Result": {
            "bundleId": "125",
            "runtime": 1.53
          }
        }
      },
      "proctoken": "1c57e2fb-2d94-4f95-9b7c-f73838d00e81",
      "id": "643bd25d-d37e-4188-82ed-1bed95c8c5a7",
      "created_by": null,
      "updated_at": null
    }
  ]
}

Bundle Journal by proctoken

When a long processing request is submitted, a proctoken is responded that will also will be joined to the complete response when available. The response is provided on the websocket channel but can also be obtained by a rest query with the provided proctoken.

GET /common/bundle-journal-by-token/{proctoken}

Parameters:

  • proctoken: the proctoken provided in the response to the request

Result example:

Same as above

List of SpatialUnits

GET /common/spatial-unit-list/

Parameters:

  • from_date: YYYY-MM-DD (can be null)
  • to_date: YYYY-MM-DD (can be null)
  • limit: max number of rows returned, default = 100

Result example:

{
  "spatialUnitList": [
    {
      "unitGuide": {
        "overview": "this is a test spatial unit"
      },
      "description": "This is a test spatial unit",
      "type": "Building",
      "createdBy": null,
      "name": "AC20-FZK-Haus",
      "id": "b6fc5402-ca87-47ba-a9f4-e29173d51656",
      "createdAt": "2025-02-01T17:07:10.272729",
      "updatedAt": null,
      "updatedBy": null
    },
    {
      "unitGuide": {
        "overview": "this is a test spatial unit"
      },
      "description": "This is a test spatial unit",
      "type": "Office Building",
      "createdBy": null,
      "name": "NordicLCA_Office_Concrete_BuildingPermit",
      "id": "a862104b-7603-4f83-897a-5821fe1e614a",
      "createdAt": "2025-01-25T13:47:55.093273",
      "updatedAt": null,
      "updatedBy": null
    },
    {
      "unitGuide": {
        "overview": "this is a test spatial unit"
      },
      "description": "This is a test spatial unit",
      "type": "Residential Building",
      "createdBy": null,
      "name": "NordicLCA_Housing_Concrete_BuildingPermit_Revit",
      "id": "85020098-d326-4c08-88de-7a32600ec129",
      "createdAt": "2024-11-18T13:50:23.719036",
      "updatedAt": null,
      "updatedBy": null
    },
    {
      "unitGuide": {
        "overview": "this is a test spatial unit"
      },
      "description": "This is a test spatial unit",
      "type": "Residential Building",
      "createdBy": null,
      "name": "IFC Schependomlaan",
      "id": "3693decc-405b-475d-a4ad-e1223de14ef9",
      "createdAt": "2024-10-23T20:57:12.217604",
      "updatedAt": null,
      "updatedBy": null
    },
    {
      "unitGuide": {
        "overview": "this is a test spatial unit"
      },
      "description": "This is a test spatial unit",
      "type": "Residential Building",
      "createdBy": null,
      "name": "Duplex_A_20110907_optimized",
      "id": "5f2d17b0-43fb-445d-9c67-7dafb3292c33",
      "createdAt": "2024-10-02T12:33:52.854345",
      "updatedAt": null,
      "updatedBy": null
    }
  ]
}

Details of a Spatial Unit

GET /common/spatial-unit/{spatial_unit_id}

Parameters:

  • spatial_unit_id: uuid of the Spatial Unit

Result example:

{
  "spatialUnit": {
    "unitGuide": {
      "overview": "this is a test spatial unit"
    },
    "description": "This is a test spatial unit",
    "type": "Office Building",
    "createdBy": null,
    "name": "NordicLCA_Office_Concrete_BuildingPermit",
    "id": "a862104b-7603-4f83-897a-5821fe1e614a",
    "createdAt": "2025-01-25T13:47:55.093273",
    "updatedAt": null,
    "updatedBy": null
  }
}

Root Bundle Unit List for a Spatial Unit

A Spatial Unit can be related to a Bundle (master data set of an IFC file of the construction projet) or to several bundles when more that one IFC file is imported while giving the same Spatial Unit Reference.

Initially, the bundle unit which is associated to the Spatial Unit is the 'Project' (root of the IFC file).

Thereafter, a link can be created between a Spatial Unit, such as an Apartment, an Office, a Parking, ... and the corresponding bundle unit with the IFC data of the Apartment, Office, Parking, ...

GET /common/spatial-unit/{spatial_unit_id}/root-bundle-unit-list

Parameters:

  • spatial_unit_id: uuid of the Spatial Unit

Result example:

{
  "spatialUnitRootBundleUnitList": [
    {
      "spatialunit_id": "a862104b-7603-4f83-897a-5821fe1e614a",
      "spatialunit_name": "NordicLCA_Office_Concrete_BuildingPermit",
      "spatialunit_type": "Office Building",
      "bundle_id": "64",
      "bundleunit_id": "d1ce5c79-6477-4f04-9500-792a06d14987",
      "unit_id": "f2e1a0da-dc31-4d71-825f-082c95f12b5f",
      "unit_type": "IfcProject",
      "unit_name": "TYÖNRO",
      "unit_longname": null
    }
  ]
}

List of Units of a Bundle

The units of bundle can be:

  • the project
  • a Site
  • a Building
  • a Storey
  • a SpatialZone (or a Group or Zone as a proxy of a SpatialZone)
  • a Space
GET /common/bundle/{bundle_id}/bundle-unit-list

Parameters:

  • bundle_id: the id of the bundle
  • unit_type: (can be null)
    • the type of the unit: e.g. IfcSpatialZone
    • can also be a list of types: e.g. IfcProject,IfcSpatialZone

Result example: with Duplex_A_20110907_optimized.ifc after the creation of the SpatialZones

{
  "bundleUnitList": [
    {
      "bundleunit_id": "ffa74974-d80a-5331-aec6-bf9ef62ea1f4",
      "bundle_id": 128,
      "unit_id": "06f07510-c30c-405a-b86f-0708935692d4",
      "unit_type": "IfcSpatialZone",
      "unit_name": "Duplex-B",
      "unit_longname": "Duplex-B",
      "parent_id": "7b7032cc-b822-417b-9aea-642906a29bd4",
      "parent_type": "IfcBuilding",
      "parent_name": null,
      "parent_longname": null,
      "created_at": "2025-04-15T18:22:23.741623",
      "created_by": "",
      "updated_at": null,
      "updated_by": null
    },
    {
      "bundleunit_id": "a0a3ee0a-f009-5188-aa94-ff09a5fa9c97",
      "bundle_id": 128,
      "unit_id": "4e8cd602-9f7c-46f0-a68c-e17c876ff910",
      "unit_type": "IfcSpatialZone",
      "unit_name": "Duplex-A",
      "unit_longname": "Duplex-A",
      "parent_id": "7b7032cc-b822-417b-9aea-642906a29bd4",
      "parent_type": "IfcBuilding",
      "parent_name": null,
      "parent_longname": null,
      "created_at": "2025-04-15T18:22:23.741623",
      "created_by": "",
      "updated_at": null,
      "updated_by": null
    },
    {
      "bundleunit_id": "7db61458-3f42-5e09-a2dc-a7389a71a5e6",
      "bundle_id": 128,
      "unit_id": "d44ff461-cd2e-4e7f-93ba-1f64ef459111",
      "unit_type": "IfcSpatialZone",
      "unit_name": "Roof",
      "unit_longname": "Roof",
      "parent_id": "7b7032cc-b822-417b-9aea-642906a29bd4",
      "parent_type": "IfcBuilding",
      "parent_name": null,
      "parent_longname": null,
      "created_at": "2025-04-15T18:22:23.741623",
      "created_by": "",
      "updated_at": null,
      "updated_by": null
    }
  ]
}

Detail of a Bundle Unit

The Bundle Unit has a json field that records the output of the operations made on the bundle unit. In the example that follows, an extraction of the data of the bundle unit for the IfcSpatialZone 'Duplex-A' has been done and the files produced (ifcJON and IFC) have been recorded in the unitjson.

GET /common/bundle/{bundle_id}/unit/{unit_id}/

Parameters:

  • bundle_id: the id of the bundle
  • unit_id: the uuid of the bundle unit

Result example:

{
  "bundleUnit": {
    "unit_type": "IfcSpatialZone",
    "bundleunit_id": "a0a3ee0a-f009-5188-aa94-ff09a5fa9c97",
    "unit_longname": "Duplex-A",
    "relationship_type": "IfcRelAggregates",
    "parent_type": "IfcBuilding",
    "parent_longname": null,
    "updated_at": "2025-04-15T18:27:59.929045",
    "unit_id": "4e8cd602-9f7c-46f0-a68c-e17c876ff910",
    "unit_name": "Duplex-A",
    "bundle_id": 128,
    "relationship_id": "e07164df-066a-4bbe-aa75-894ea9c6c40d",
    "parent_id": "7b7032cc-b822-417b-9aea-642906a29bd4",
    "parent_name": null,
    "unitjson": {
      "IfcJSON": "IFCJSON/7eafcf9f-4078-406b-9d04-c2a968ddca31_EXTRACT.json",
      "IFC": "JSON2IFC/0508290d-a46f-4103-8ecd-11282857bd61_OUT.ifc"
    },
    "created_at": "2025-04-15T18:22:23.741623",
    "created_by": "",
    "updated_by": null
  }
}

List the properties of a Bundle Unit

There are two types of properties:

  • those that are associated directly to the object (Pset_xxx) and named propertyset
  • those that are associated to the type of an object and then associated to object via the type of the object and named hereunder properties
GET /common/bundle/{bundle_id}/spatialzone/{sz_id}/properties

Parameters:

  • bundle_id: the id of the bundle
  • sz_id: the id of the spatial zone (the term is used here liberally to designate the buidling, the storey, the spatialzone)
  • unit_type: the type of the unit in the sz (e.g. IfcSpace) (can be null)
  • unit_id: the id of the unit (can be null)
  • object_type: the type of object (e.g. IfcDoor)(can be null)
  • propertyset_name: the name of the propertyset (e.g. Pset_DoorCommon)(can be null, should not be given if properties_type is given)
  • properties_type: the type of properties (e.g. IfcDoorLiningProperties)(can be null, should not be given if propertyset_name is given)
  • limit: number of items returned, default = 100

Result example:

For:

  • bundle_id = 128
  • sz_id = '4e8cd602-9f7c-46f0-a68c-e17c876ff910' (uuid of the IfcSpatialZone of the apartment Duplex-A)
  • unit_type = 'IfcSpace'
  • unit_id = '0b74b3fa-1a92-405e-9ac9-d59067be1d42' (uuid of the IfcSpace named A102)
  • object_type = 'IfcWindow'
  • propertyset_name = 'Pset_WindowCommon'

the first item of the result (the rest being removed for brevity)

{
  "bundleUnitProperties": [
    {
      "sz_id": "4e8cd602-9f7c-46f0-a68c-e17c876ff910",
      "object_type": "IfcWindow",
      "properties_type": null,
      "bundle_id": 128,
      "object_name": "M_Fixed:750mm x 2200mm:750mm x 2200mm:182101",
      "properties_name": null,
      "sz_type": "IfcSpatialZone",
      "type_object_id": null,
      "properties_json": {},
      "sz_name": "Duplex-A",
      "type_object_type": null,
      "unit_id": "0b74b3fa-1a92-405e-9ac9-d59067be1d42",
      "type_object_name": null,
      "created_at": "2025-04-15T18:58:00.899452",
      "unit_type": "IfcSpace",
      "propertyset_id": "81de0775-2783-4f79-a69d-a60901d6e721",
      "properties_id": null,
      "id": "4d86e1c9-02e6-435c-beeb-c46cfa38fb72",
      "unit_name": "A102",
      "propertyset_name": "Pset_WindowCommon",
      "created_by": null,
      "object_id": "6f010293-ddb7-4fe4-8ffd-c144d84448e3",
      "propertyset_json": {
        "type": "IfcPropertySet",
        "globalId": "81de0775-2783-4f79-a69d-a60901d6e721",
        "ownerHistory": {
          "type": "IfcOwnerHistory",
          "ref": "39c7d6f2-586f-41ce-8688-f5359e4953e7"
        },
        "name": "Pset_WindowCommon",
        "hasProperties": [
          {
            "type": "IfcPropertySingleValue",
            "name": "Reference",
            "nominalValue": {
              "type": "IfcLabel",
              "value": "M_Fixed:750mm x 2200mm"
            }
          },
          {
            "type": "IfcPropertySingleValue",
            "name": "IsExternal",
            "nominalValue": {
              "type": "IfcBoolean",
              "value": true
            }
          },
          {
            "type": "IfcPropertySingleValue",
            "name": "FireRating",
            "nominalValue": {
              "type": "IfcLabel",
              "value": "FireRating"
            }
          }
        ]
      }
    }
  ]
}

Detail of an object

This provides the details of an object. This provides data for the representation_ids and the objectPlacement

GET /common/bundle/{bundle_id}/object/{object_id}

Parameters:

  • bundle_id: the id of the bundle
  • object_id: the uuid of the object

Update of an object

This provide the capability to change the details of an object. As such, objects that come from the master IFC file should not be updated. But, this provide a convenient capability to update objects created within the platform, such as e.g. the IfcSpatialZones.

PATCH  /common/bundle/{bundle_id}/object/{object_id}

with  Body = model.UpdateObject

class UpdateObject(BaseModel): # model for the request
    name: str | None = None
    representation_ids: list[str] | None = None
    elementjson: dict | None = None

A patch will also insert the before image of the object in the elementhistory table.

Assign the representation of a space to a spatialzone

This can be use when the master IFC file has spaces to represent spatial units such as is the case for the ARK_NordicLCA_Housing_Concrete_BuildingPermit_Revit.ifc building.

POST /common/assign-space-representation-to-spatialzone

with Body=AssignmentOfSpaceRepresentationToSpatialZone

class AssignmentOfSpaceRepresentationToSpatialZone(BaseModel):
    bundle_id: str
    spatialZoneId: str
    spaceId: str

for:

{
  "bundle_id": "149",
  "spatialZoneId": "af12ccb7-edef-48c3-97c9-3cc14d977859",
  "spaceId": "2d39cdcf-21f9-44c8-b3e9-78c2dd008966"
}

we get an updated SpatialZone with representation_ids and an objectPlacement borrowed from the corresponding space.

{
  "spatialZone": {
    "representation_ids": [
      "32883524-541a-42ef-bfb9-c9de861b7736"
    ],
    "object_id": "af12ccb7-edef-48c3-97c9-3cc14d977859",
    "elementjson": {
      "type": "IfcSpatialZone",
      "globalId": "af12ccb7-edef-48c3-97c9-3cc14d977859",
      "name": "Apartment 02.HSTO.AS2",
      "longName": "Apartment 02.HSTO.AS2",
      "objectType": "Private Parts - Apartment",
      "representation": {
        "type": "IfcProductDefinitionShape",
        "representations": [
          {
            "type": "IfcShapeRepresentation",
            "ref": "32883524-541a-42ef-bfb9-c9de861b7736"
          }
        ]
      },
      "objectPlacement": {
        "type": "IfcLocalPlacement",
        "placementRelTo": {
          "type": "IfcLocalPlacement",
          "placementRelTo": {
            "type": "IfcLocalPlacement",
            "placementRelTo": {
              "type": "IfcLocalPlacement",
              "relativePlacement": {
                "type": "IfcAxis2Placement3D",
                "location": {
                  "type": "IfcCartesianPoint",
                  "coordinates": [
                    0,
                    0,
                    0
                  ]
                },
                "axis": {
                  "type": "IfcDirection",
                  "directionRatios": [
                    0,
                    0,
                    1
                  ]
                },
                "refDirection": {
                  "type": "IfcDirection",
                  "directionRatios": [
                    0.49042092447644936,
                    -0.8714856951411564,
                    0
                  ]
                }
              }
            },
            "relativePlacement": {
              "type": "IfcAxis2Placement3D",
              "location": {
                "type": "IfcCartesianPoint",
                "coordinates": [
                  0,
                  0,
                  0
                ]
              }
            }
          },
          "relativePlacement": {
            "type": "IfcAxis2Placement3D",
            "location": {
              "type": "IfcCartesianPoint",
              "coordinates": [
                0,
                0,
                54930
              ]
            }
          }
        },
        "relativePlacement": {
          "type": "IfcAxis2Placement3D",
          "location": {
            "type": "IfcCartesianPoint",
            "coordinates": [
              0,
              0,
              0
            ]
          }
        }
      }
    },
    "created_at": "2025-05-27T22:01:54.221362",
    "updated_by": null,
    "name": "Apartment 02.HSTO.AS2",
    "bundle_id": 149,
    "type": "IfcSpatialZone",
    "created_by": null,
    "updated_at": "2025-05-30T18:04:41.771571"
  }
}