Skip to content

Documents

List, upload, and manage documents within buildings.

List Documents

GET/v1/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
  • 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"
  • 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 in YYYY-MM-DD format
  • 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
  • documents[].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

GET/v1/building_owners/{buildingOwnerId}/documents/deleted

List 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"
  • 200Success
  • 400Missing or invalid deleted_since
  • 401Missing or invalid API key
  • 403The 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 ID
  • documents[].buildingIdstringBuilding the document was deleted from
  • documents[].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

PUT/v1/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. 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 ID
  • buildingIdstringBuilding ID
  • filenamestringrequiredName of the file to upload
  • originalCreatedAtstringOriginal creation date of the file (ISO 8601)
  • serialNumberstringDocument serial number
  • fileSizenumberSize 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 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/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 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 in YYYY-MM-DD format
  • originalCreatedAtstringOriginal creation date from file metadata
  • asBuiltbooleanWhether the document is as-built
  • urlstringPre-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 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/v1/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 in YYYY-MM-DD format
  • 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/v1/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/v1/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
}