Documents

List, upload, and manage documents within buildings.

List Documents

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

List all documents in a building. Results are paginated.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID

limitnumberMax results per page (default: 100, max: 1000)
next_tokenstringPagination token — pass the nextToken value from a previous response. Must use same sort_by/sort_order.
sort_by'createdAt' | 'updatedAt'Sort field (default: 'createdAt')
sort_order'asc' | 'desc'Sort direction (default: 'desc')
updated_sincestringOnly return documents updated at or after this timestamp (ISO 8601). Requires sort_by=updatedAt.

Examples

# Basic — list documents (default: sorted by createdAt desc)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.findable.ai/building_owners/cust-456/buildings/bld-789/documents?limit=10"

# Sort by updatedAt and filter by date
curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.findable.ai/building_owners/cust-456/buildings/bld-789/documents?sort_by=updatedAt&sort_order=desc&updated_since=2026-01-01T00:00:00Z&limit=50"

200Success
400Invalid query parameters (e.g. updated_since without sort_by=updatedAt)
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.

documentsDocument[]Array of document objects
documents[].idstringUnique identifier
documents[].filenamestringDocument filename
documents[].titlestringDocument title (if extracted)
documents[].originalPathstringOriginal file path from upload
documents[].buildingCategorystringAutomatically assigned building category
documents[].disciplinestringTechnical discipline
documents[].informationTypestringPrimary information type
documents[].informationTypesstring[]All assigned information types
documents[].isDrawingbooleanWhether the document is a drawing
documents[].isSchemaDrawingbooleanWhether the document is a schema drawing
documents[].serialNumberstringDocument serial number
documents[].sizenumberFile size in bytes
documents[].md5ChecksumstringMD5 checksum of the file
documents[].corruptbooleanWhether the file failed processing due to corruption
documents[].drawingDatestringDrawing date (if applicable)
documents[].originalCreatedAtstringOriginal creation date from file metadata
documents[].asBuiltbooleanWhether the document is as-built
documents[].createdAtstringISO 8601 creation timestamp
documents[].updatedAtstringISO 8601 last update timestamp
nextTokenstring | nullToken for the next page, null if this is the last page

Response

{
  "documents": [
    {
      "id": "doc-1",
      "filename": "fire-safety-report.pdf",
      "title": "Fire Safety Assessment 2025",
      "originalPath": "/reports/fire-safety/",
      "buildingCategory": "Fire Safety",
      "discipline": "Fire",
      "informationType": "Report",
      "informationTypes": ["Report", "Assessment"],
      "isDrawing": false,
      "isSchemaDrawing": false,
      "serialNumber": null,
      "size": 2048576,
      "md5Checksum": "a3f2b8c1e9d04567890abcdef1234567", // pragma: allowlist secret
      "corrupt": false,
      "drawingDate": null,
      "originalCreatedAt": null,
      "asBuilt": false,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-06-20T14:00:00Z"
    }
  ],
  "nextToken": "eyJsYXN0S2V5Ijo..."
}

Request Upload URL

PUT/building_owners/{buildingOwnerId}/buildings/{buildingId}/documents

Request a pre-signed URL to upload a new document. After receiving the URL, PUT the file content directly to it.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID

filenamestringrequiredName of the file to upload
originalCreatedAtstringOriginal creation date of the file (ISO 8601)
serialNumberstringDocument serial number

Request Body Example

{
  "filename": "maintenance-report.pdf"
}

Examples

# Step 1: Request the upload URL
curl -X PUT \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename": "report.pdf"}' \
  "https://api.findable.ai/building_owners/cust-456/buildings/bld-789/documents"

# Step 2: Upload the file to the returned URL
curl -X PUT \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf \
  "UPLOAD_URL_FROM_STEP_1"

200Upload URL generated
400Invalid request body (missing filename)
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.

documentIdstringID assigned to the new document
uploadUrlstringPre-signed S3 URL to PUT the file content to

Response

{
  "documentId": "doc-new-123",
  "uploadUrl": "https://s3.eu-central-1.amazonaws.com/..."
}

Get Document

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

Get a document with a pre-signed download URL.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID
documentIdstringDocument ID

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

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

idstringUnique identifier
filenamestringDocument filename
titlestringDocument title (if extracted)
originalPathstringOriginal file path
buildingCategorystringAssigned building category
disciplinestringTechnical discipline
informationTypestringPrimary information type
informationTypesstring[]All assigned information types
isDrawingbooleanWhether the document is a drawing
isSchemaDrawingbooleanWhether the document is a schema drawing
serialNumberstringDocument serial number
sizenumberFile size in bytes
md5ChecksumstringMD5 checksum
corruptbooleanWhether the file failed processing due to corruption
drawingDatestringDrawing date (if applicable)
originalCreatedAtstringOriginal creation date from file metadata
asBuiltbooleanWhether the document is as-built
urlstringPre-signed download URL (expires after 1 hour)
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

Response

{
  "id": "doc-1",
  "filename": "fire-safety-report.pdf",
  "title": "Fire Safety Assessment 2025",
  "originalPath": "/reports/fire-safety/",
  "buildingCategory": "Fire Safety",
  "discipline": "Fire",
  "informationType": "Report",
  "informationTypes": ["Report", "Assessment"],
  "isDrawing": false,
  "isSchemaDrawing": false,
  "serialNumber": null,
  "size": 2048576,
  "md5Checksum": "a3f2b8c1e9d04567890abcdef1234567", // pragma: allowlist secret
  "corrupt": false,
  "drawingDate": null,
  "originalCreatedAt": null,
  "asBuilt": false,
  "url": "https://s3.eu-central-1.amazonaws.com/...",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-06-20T14:00:00Z"
}

Update Document

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

Update document metadata. Returns the updated document object.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID
documentIdstringDocument ID

filenamestringUpdated filename
buildingCategorystringUpdated building category

Request Body Example

{
  "filename": "updated-fire-safety-report.pdf",
  "buildingCategory": "Fire Safety"
}

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

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

idstringUnique identifier
filenamestringUpdated filename
titlestringDocument title (if extracted)
originalPathstringOriginal file path
buildingCategorystringAssigned building category
disciplinestringTechnical discipline
informationTypestringPrimary information type
informationTypesstring[]All assigned information types
isDrawingbooleanWhether the document is a drawing
isSchemaDrawingbooleanWhether the document is a schema drawing
serialNumberstringDocument serial number
sizenumberFile size in bytes
md5ChecksumstringMD5 checksum
corruptbooleanWhether the file failed processing due to corruption
drawingDatestringDrawing date (if applicable)
originalCreatedAtstringOriginal creation date from file metadata
asBuiltbooleanWhether the document is as-built
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

Response

{
  "id": "doc-1",
  "filename": "updated-fire-safety-report.pdf",
  "title": "Fire Safety Assessment 2025",
  "originalPath": "/reports/fire-safety/",
  "buildingCategory": "Fire Safety",
  "discipline": "Fire",
  "informationType": "Report",
  "informationTypes": ["Report", "Assessment"],
  "isDrawing": false,
  "isSchemaDrawing": false,
  "serialNumber": null,
  "size": 2048576,
  "md5Checksum": "a3f2b8c1e9d04567890abcdef1234567", // pragma: allowlist secret
  "corrupt": false,
  "drawingDate": null,
  "originalCreatedAt": null,
  "asBuilt": false,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2026-01-10T09:45:00Z"
}

Delete Document

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

Delete (archive) a document.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID
documentIdstringDocument ID

200Document deleted
401Missing or invalid API key
403API key lacks permission
404Document not found

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

successbooleanAlways true on success

Response

{ "success": true }

Document Processing Status

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

Get the processing status for a single document.

Authentication

x-api-key header

buildingOwnerIdstringBuilding owner / customer ID
buildingIdstringBuilding ID
documentIdstringDocument ID

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

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

document_idstringDocument ID
filenamestringDocument filename
building_idstringBuilding the document belongs to
building_categorystring | nullAssigned building category
corruptbooleanWhether the file failed processing due to corruption
sizenumberFile size in bytes
extracted_textbooleanWhether text has been extracted
extracted_filebooleanWhether the file has been extracted
uncompressed_packagebooleanWhether a compressed package has been decompressed
valid_filebooleanWhether the file is valid
invalid_filebooleanWhether the file is invalid
categorisedbooleanWhether the document has been categorised
skip_extract_filebooleanWhether file extraction was skipped
text_extraction_errorbooleanWhether text extraction failed

Response

{
  "document_id": "doc-1",
  "filename": "fire-safety-report.pdf",
  "building_id": "bld-789",
  "building_category": "Fire Safety",
  "corrupt": false,
  "size": 2048576,
  "extracted_text": true,
  "extracted_file": true,
  "uncompressed_package": false,
  "valid_file": true,
  "invalid_file": false,
  "categorised": true,
  "skip_extract_file": false,
  "text_extraction_error": false
}