Documents
List, upload, and manage documents within buildings.
List Documents
/v1/building_owners/{buildingOwnerId}/buildings/{buildingId}/documentsList all documents in a building. Results are paginated.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer IDbuildingIdstringBuilding ID
next_tokenstringPagination token from previous response. Must use same sort_by/sort_order.limitnumberMaximum results per page. Default: 10. Maximum: 1000.sort_by'createdAt' | 'updatedAt'Sort field. Default: "createdAt".sort_order'asc' | 'desc'Sort direction. Default: "desc".updated_sincestring (ISO 8601)Only return documents with updatedAt >= this value (ISO 8601). Requires sort_by=updatedAt.include_url'true' | 'false'Set to "true" to include url (signed download link to the original file) and previewUrl (signed link to the generated PDF preview, or null) on each document, so you do not need one Get Document call per file. Limits limit to 200. Documents in private folders have no url. Links expire, so download soon after listing.
Examples
# Basic — list documents (default: sorted by createdAt desc)
curl -H "x-api-key: YOUR_API_KEY" \
"https://api.findable.ai/v1/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/v1/building_owners/cust-456/buildings/bld-789/documents?sort_by=updatedAt&sort_order=desc&updated_since=2026-01-01T00:00:00Z&limit=50"
# Include signed download URLs (limit up to 200)
curl -H "x-api-key: YOUR_API_KEY" \
"https://api.findable.ai/v1/building_owners/cust-456/buildings/bld-789/documents?sort_by=updatedAt&updated_since=2026-01-01T00:00:00Z&include_url=true&limit=200"200Success400Invalid query parameters (e.g. updated_since without sort_by=updatedAt)401Missing or invalid API key404Building not found
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
documentsDocument[]Array of document objectsdocuments[].idstringUnique identifierdocuments[].filenamestringDocument filenamedocuments[].titlestringDocument title (if extracted)documents[].originalPathstringOriginal file path from uploaddocuments[].buildingCategorystringAutomatically assigned building categorydocuments[].disciplinestringTechnical disciplinedocuments[].informationTypestringPrimary information typedocuments[].informationTypesstring[]All assigned information typesdocuments[].isDrawingbooleanWhether the document is a drawingdocuments[].isSchemaDrawingbooleanWhether the document is a schema drawingdocuments[].serialNumberstringDocument serial numberdocuments[].sizenumberFile size in bytesdocuments[].md5ChecksumstringMD5 checksum of the filedocuments[].corruptbooleanWhether the file failed processing due to corruptiondocuments[].drawingDatestringDrawing date in YYYY-MM-DD formatdocuments[].originalCreatedAtstringOriginal creation date from file metadatadocuments[].asBuiltbooleanWhether the document is as-builtdocuments[].createdAtstringISO 8601 creation timestampdocuments[].updatedAtstringISO 8601 last update timestampdocuments[].urlstringSigned download URL for the original file. Only with include_url=true.documents[].previewUrlstring | nullSigned URL for the generated PDF preview, or null. Only with include_url=true.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..."
}List Deleted Documents
/v1/building_owners/{buildingOwnerId}/documents/deletedList documents deleted from any of the building owner's buildings since a point in time, oldest first. Use it with List Documents and updated_since to keep a copy in sync without re-reading every document. A key scoped to individual buildings only sees deletions in those buildings, so a page can hold fewer than limit items while nextToken is still set: keep paging until nextToken is null. A restored document leaves this feed and shows up again through updated_since on List Documents. Deletions are kept here while the document is in the archive; one permanently purged from the archive no longer appears, so poll at least daily.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer ID
deleted_sincestring (ISO 8601)requiredRequired. Return documents deleted at or after this time (ISO 8601). Results are oldest first: store the last deletedAt you received and pass it on the next run. Deletions are reported at least once, so treat a repeated id as already handled.limitnumberMaximum results per page. Default: 100. Maximum: 1000.next_tokenstringToken for the next page, from the previous response. Keep deleted_since unchanged while paging.
Examples
curl -H "x-api-key: YOUR_API_KEY" \
"https://api.findable.ai/v1/building_owners/cust-456/documents/deleted?deleted_since=2026-10-01T00:00:00Z&limit=500"200Success400Missing or invalid deleted_since401Missing or invalid API key403The key cannot read this building owner
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
documents[].idstringDeleted document IDdocuments[].buildingIdstringBuilding the document was deleted fromdocuments[].deletedAtstringISO 8601 deletion timestamp (UTC)nextTokenstring | nullToken for the next page, null if this is the last page
Response
{
"documents": [
{
"id": "doc-1",
"buildingId": "bld-789",
"deletedAt": "2026-10-08T03:17:35.123Z"
}
],
"nextToken": null
}Request Upload URL
/v1/building_owners/{buildingOwnerId}/buildings/{buildingId}/documentsRequest a pre-signed URL to upload a new document. After receiving the URL, PUT the file content directly to it. In Findable the document shows your API key's name as its source and uploader. When one API key requests more than 100 upload URLs for the same building within 10 minutes, the documents after the first 100 are processed in batch and can take a few hours longer to finish processing.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer IDbuildingIdstringBuilding ID
filenamestringrequiredName of the file to uploadoriginalCreatedAtstringOriginal creation date of the file (ISO 8601)serialNumberstringDocument serial numberfileSizenumberSize of the file in bytes. The upload URL then only accepts a file of exactly this size. Recommended now; it will become required.
Request Body Example
{
"filename": "maintenance-report.pdf",
"fileSize": 2048576
}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", "fileSize": 2048576}' \
"https://api.findable.ai/v1/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 generated400Invalid request body (missing filename)401Missing or invalid API key403API key lacks permission404Building not found
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
documentIdstringID assigned to the new documentuploadUrlstringPre-signed S3 URL to PUT the file content to
Response
{
"documentId": "doc-new-123",
"uploadUrl": "https://s3.eu-central-1.amazonaws.com/..."
}Get Document
/v1/building_owners/{buildingOwnerId}/buildings/{buildingId}/documents/{documentId}Get a document with a pre-signed URL for the original file and a PDF preview URL when one has been generated.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer IDbuildingIdstringBuilding IDdocumentIdstringDocument ID
200Success401Missing or invalid API key404Document not found
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
idstringUnique identifierfilenamestringDocument filenametitlestringDocument title (if extracted)originalPathstringOriginal file pathbuildingCategorystringAssigned building categorydisciplinestringTechnical disciplineinformationTypestringPrimary information typeinformationTypesstring[]All assigned information typesisDrawingbooleanWhether the document is a drawingisSchemaDrawingbooleanWhether the document is a schema drawingserialNumberstringDocument serial numbersizenumberFile size in bytesmd5ChecksumstringMD5 checksumcorruptbooleanWhether the file failed processing due to corruptiondrawingDatestringDrawing date in YYYY-MM-DD formatoriginalCreatedAtstringOriginal creation date from file metadataasBuiltbooleanWhether the document is as-builturlstringPre-signed download URL (expires after 1 hour)previewUrlstring | nullPre-signed full PDF preview URL (expires after 1 hour), or null when unavailable. A temporary lookup error can also return null.createdAtstringISO 8601 creation timestampupdatedAtstringISO 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
/v1/building_owners/{buildingOwnerId}/buildings/{buildingId}/documents/{documentId}Update document metadata. Returns the updated document object.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer IDbuildingIdstringBuilding IDdocumentIdstringDocument ID
filenamestringUpdated filenamebuildingCategorystringUpdated building category
Request Body Example
{
"filename": "updated-fire-safety-report.pdf",
"buildingCategory": "Fire Safety"
}200Document updated400Invalid request body401Missing or invalid API key403API key lacks permission404Document not found
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
idstringUnique identifierfilenamestringUpdated filenametitlestringDocument title (if extracted)originalPathstringOriginal file pathbuildingCategorystringAssigned building categorydisciplinestringTechnical disciplineinformationTypestringPrimary information typeinformationTypesstring[]All assigned information typesisDrawingbooleanWhether the document is a drawingisSchemaDrawingbooleanWhether the document is a schema drawingserialNumberstringDocument serial numbersizenumberFile size in bytesmd5ChecksumstringMD5 checksumcorruptbooleanWhether the file failed processing due to corruptiondrawingDatestringDrawing date in YYYY-MM-DD formatoriginalCreatedAtstringOriginal creation date from file metadataasBuiltbooleanWhether the document is as-builtcreatedAtstringISO 8601 creation timestampupdatedAtstringISO 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
/v1/building_owners/{buildingOwnerId}/buildings/{buildingId}/documents/{documentId}Delete (archive) a document.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer IDbuildingIdstringBuilding IDdocumentIdstringDocument ID
200Document deleted401Missing or invalid API key403API key lacks permission404Document 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
/v1/building_owners/{buildingOwnerId}/buildings/{buildingId}/documents/{documentId}/statusGet the processing status for a single document.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer IDbuildingIdstringBuilding IDdocumentIdstringDocument ID
200Success401Missing or invalid API key404Document not found
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
document_idstringDocument IDfilenamestringDocument filenamebuilding_idstringBuilding the document belongs tobuilding_categorystring | nullAssigned building categorycorruptbooleanWhether the file failed processing due to corruptionsizenumberFile size in bytesextracted_textbooleanWhether text has been extractedextracted_filebooleanWhether the file has been extracteduncompressed_packagebooleanWhether a compressed package has been decompressedvalid_filebooleanWhether the file is validinvalid_filebooleanWhether the file is invalidcategorisedbooleanWhether the document has been categorisedskip_extract_filebooleanWhether file extraction was skippedtext_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
}