Buildings

Manage buildings within a building owner.

List Buildings

GET/building_owners/{buildingOwnerId}/buildings

List all buildings for a building owner. Results are paginated.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID

limitnumberMax results per page (default: 100, max: 1000)
next_tokenstringPagination token — pass the nextToken value from a previous response

200Success
401Missing or invalid API key
404Building owner not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

buildingsBuilding[]Array of building objects
buildings[].idstringUnique identifier
buildings[].namestringBuilding name
buildings[].numberOfFilesnumberTotal number of documents in the building
buildings[].createdAtstringISO 8601 creation timestamp
buildings[].updatedAtstringISO 8601 last update timestamp
nextTokenstring | nullToken for the next page, null if this is the last page

Response

{
  "buildings": [
    {
      "id": "bld-789",
      "name": "Oslo Office Tower",
      "numberOfFiles": 2450,
      "createdAt": "2024-06-01T08:00:00Z",
      "updatedAt": "2025-11-15T12:30:00Z"
    }
  ],
  "nextToken": null
}

Create Building

PUT/building_owners/{buildingOwnerId}/buildings

Create a new building for a building owner. Note: the response is a plain JSON string (the new building ID), not an object.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID

namestringrequiredName for the new building

Request Body Example

{ "name": "Oslo Office Tower" }

200Building created — response is a plain JSON string (the new building ID), not an object
400Invalid request body
401Missing or invalid API key
403API key lacks permission
404Building owner not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

Response

"bld-new-456"

Get Building

GET/building_owners/{buildingOwnerId}/buildings/{buildingId}

Get a single building by ID.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID

200Success
401Missing or invalid API key
404Building not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

idstringUnique identifier
namestringBuilding name
numberOfFilesnumberTotal number of documents
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

Response

{
  "id": "bld-789",
  "name": "Oslo Office Tower",
  "numberOfFiles": 2450,
  "createdAt": "2024-06-01T08:00:00Z",
  "updatedAt": "2025-11-15T12:30:00Z"
}

Update Building

PATCH/building_owners/{buildingOwnerId}/buildings/{buildingId}

Update building details.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID

namestringUpdated building name

Request Body Example

{ "name": "Oslo Office Tower (Renovated)" }

200Building updated
400Invalid request body
401Missing or invalid API key
403API key lacks permission
404Building not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

idstringUnique identifier
namestringUpdated building name
numberOfFilesnumberTotal number of documents
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

Response

{
  "id": "bld-789",
  "name": "Oslo Office Tower (Renovated)",
  "numberOfFiles": 2450,
  "createdAt": "2024-06-01T08:00:00Z",
  "updatedAt": "2026-01-10T09:45:00Z"
}

Delete Building

DELETE/building_owners/{buildingOwnerId}/buildings/{buildingId}

Delete a building and all its documents. Returns 409 if the building has documents currently being processed.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID

200Building deleted
401Missing or invalid API key
403API key lacks permission
404Building not found
409Building has active processing — cannot delete

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

messagestringConfirmation message

Response

{ "message": "Building with ID bld-789 has been deleted successfully" }

Processing Status

GET/building_owners/{buildingOwnerId}/buildings/{buildingId}/status

Get the processing status for a building's documents.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID

200Success
401Missing or invalid API key
404Building not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

total_documentsnumberTotal number of documents
processed_documentsnumberNumber of documents that have been processed
categorized_documentsnumberNumber of documents that have been categorised
extracted_percentagenumberPercentage of documents with extracted text (0-100)
categorized_percentagenumberPercentage of documents that are categorised (0-100)
extracted_textbooleanWhether text extraction is complete
extracted_filebooleanWhether file extraction is complete
uncompressed_packagebooleanWhether package decompression is complete
valid_filebooleanWhether the file is valid
invalid_filebooleanWhether any files are invalid
categorisedbooleanWhether categorisation is complete
skip_extract_filebooleanWhether file extraction was skipped
text_extraction_errorbooleanWhether a text extraction error occurred

Response

{
  "total_documents": 2450,
  "processed_documents": 2430,
  "categorized_documents": 2400,
  "extracted_percentage": 99,
  "categorized_percentage": 98,
  "extracted_text": true,
  "extracted_file": true,
  "uncompressed_package": true,
  "valid_file": true,
  "invalid_file": false,
  "categorised": true,
  "skip_extract_file": false,
  "text_extraction_error": false
}

Deficiency Report

GET/building_owners/{buildingOwnerId}/buildings/{buildingId}/report

Get the deficiency report for a building, including themes and progress details.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID

countrystringCountry code for regulatory framework (e.g. NO, GB)
localestringLocale for the report (e.g. nb, en)

200Success
401Missing or invalid API key
404Building not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

themesReportTheme[]Array of report theme/category objects
themes[].idstringTheme ID
themes[].nameIdstringName identifier
themes[].themestringTheme group
themes[].namestringDisplay name
themes[].descriptionstringTheme description
themes[].lawsstringRelevant laws and regulations
themes[].disciplinestringTechnical discipline
themes[].commentstringAdditional comment
themes[].statusstringCompliance status
themes[].parentIdstring | nullParent theme ID for hierarchy, null for top-level themes
themes[].createdAtstringISO 8601 creation timestamp
themes[].updatedAtstringISO 8601 last update timestamp
progressDetailsProgressDetail[]Progress summary per theme
progressDetails[].themestringTheme name
progressDetails[].progressnumberNumber of items completed
progressDetails[].totalnumberTotal number of items
progressDetails[].percentagenumberCompletion percentage (0-100)

Response

{
  "themes": [
    {
      "id": "theme-001",
      "nameId": "fire-safety",
      "theme": "Safety",
      "name": "Fire Safety",
      "description": "Fire safety documentation and compliance",
      "laws": "TEK17 §11",
      "discipline": "Fire",
      "comment": "",
      "status": "partial",
      "parentId": null,
      "createdAt": "2025-06-15T10:00:00Z",
      "updatedAt": "2025-06-15T10:00:00Z"
    }
  ],
  "progressDetails": [
    {
      "theme": "Fire Safety",
      "progress": 8,
      "total": 12,
      "percentage": 67
    }
  ]
}