Search

Authentication

x-api-key header

• buildingOwnerIdstringBuilding owner / customer ID
• buildingIdstringBuilding ID

• querystringrequiredSearch query Minimum length: 1.
• max_resultsnumberMaximum results per page, 1-1000. Larger pages cost little more than small ones and are much faster than paging: prefer a single large request over many sequential ones. Use start_index to page beyond it. Minimum: 1. Maximum: 1000. Default: 20.
• start_indexnumberStarting index for pagination. Offset paging reaches at most 10000 results; past that an empty page is returned alongside the true numberOfHits. Minimum: 0. Default: 0.
• disciplinestringFilter by discipline (e.g., "Electrical", "HVAC")
• document_type'document' | 'drawing'Filter by document type
• floorstringFilter by floor level
• sort_by'relevance' | 'createdAt' | 'updatedAt' | 'filename'Field to sort by. "filename" currently orders on a normalised copy of the name that is lower-cased and has common words removed, so the order can differ noticeably from the displayed filename - a code like "SER" is dropped when it happens to be a word in the document's language. This is being corrected to sort on the stored filename. Default: "relevance".
• sort_order'asc' | 'desc'Sort order (only applies when sort_by is not "relevance") Default: "desc".
• include_aggregationsbooleanInclude aggregated facet counts in response Default: false.
• fuzziness'auto' | 'on' | 'off'Fuzzy-matching mode. "on" always fuzzy-matches (best for prose). "off" matches exactly (best for equipment, system and drawing codes). "auto" (default) keeps fuzzy matching for prose but turns it off when the query looks like an identifier - any token containing a digit, or an all-short query such as "VVS". Default: "auto".

Examples

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.findable.ai/v1/building_owners/cust-456/buildings/bld-789/search?query=fire+safety"

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

• hitsSearchHit[]Array of matching documents
• hits[].idstringDocument ID
• hits[].buildingIdstringBuilding the document belongs to
• hits[].filenamestringDocument filename
• hits[].titlestringDocument title (optional)
• hits[].buildingCategorystringAssigned building category (optional)
• hits[].disciplinestringTechnical discipline (optional)
• hits[].isDrawingbooleanWhether the document is a drawing (optional)
• hits[].asBuiltbooleanWhether this is an as-built drawing (optional)
• hits[].drawingRevisionstringDrawing revision identifier (optional)
• hits[].drawingTypestringType of drawing (optional)
• hits[].drawingDatestringDrawing-specific date (optional)
• hits[].md5ChecksumstringMD5 checksum (optional)
• hits[].originalCreatedAtstringOriginal creation date from file metadata (optional)
• hits[].originalPathstringOriginal file path (optional)
• hits[].sizenumberFile size in bytes (optional)
• hits[].informationTypestringPrimary information type (optional)
• hits[].informationTypesstring[]All assigned information types (optional)
• hits[].createdAtstringISO 8601 creation timestamp
• hits[].updatedAtstringISO 8601 last update timestamp
• hits[].relevanceScorenumberRelevance score from search engine (optional)
• hits[].externalIdsRecord<string, string>External system IDs, e.g. { plania: "guid" } (optional)
• numberOfHitsnumberUpper bound on matching documents. Documents in private folders are counted but not returned, so a page can be shorter than max_results - page until hits is empty rather than until a short page.
• aggregationsAggregationsAggregated facet counts (only when include_aggregations=true)
• aggregations.disciplineArray<{key: string, count: number}>Discipline value counts (optional)
• aggregations.categoryArray<{key: string, count: number}>Category value counts (optional)
• aggregations.extensionArray<{key: string, count: number}>File extension counts (optional)
• aggregations.drawing_floorArray<{key: string, count: number}>Drawing floor value counts (optional)

Response

{
  "hits": [
    {
      "id": "doc-1",
      "buildingId": "bld-789",
      "filename": "fire-safety-plan-A-101.pdf",
      "title": "Fire Safety Plan - Ground Floor",
      "buildingCategory": "Fire Safety",
      "discipline": "Fire",
      "isDrawing": true,
      "asBuilt": true,
      "drawingRevision": "Rev C",
      "drawingType": "Floor Plan",
      "drawingDate": "2025-01-05T00:00:00Z",
      "md5Checksum": "a3f2b8c1e9d04567890abcdef1234567", // pragma: allowlist secret
      "originalCreatedAt": "2025-01-10T08:00:00Z",
      "originalPath": "/drawings/fire-safety/",
      "size": 2048576,
      "informationType": "Drawing",
      "informationTypes": ["Drawing", "Fire Safety"],
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-06-20T14:00:00Z",
      "relevanceScore": 8.432,
      "externalIds": {
        "plania": "guid-from-plania"
      }
    }
  ],
  "numberOfHits": 42,
  "aggregations": {
    "discipline": [
      { "key": "Fire", "count": 42 },
      { "key": "Electrical", "count": 28 },
      { "key": "HVAC", "count": 15 }
    ],
    "category": [
      { "key": "Fire Safety", "count": 38 },
      { "key": "Building Systems", "count": 47 }
    ],
    "extension": [
      { "key": "pdf", "count": 65 },
      { "key": "dwg", "count": 20 }
    ],
    "drawing_floor": [
      { "key": "1", "count": 25 },
      { "key": "2", "count": 18 }
    ]
  }
}

Authentication

x-api-key header

• buildingOwnerIdstringBuilding owner / customer ID

• querystringrequiredSearch query Minimum length: 1.
• max_resultsnumberMaximum results per page, 1-1000. Larger pages cost little more than small ones and are much faster than paging: prefer a single large request over many sequential ones. Use start_index to page beyond it. Minimum: 1. Maximum: 1000. Default: 20.
• start_indexnumberStarting index for pagination. Offset paging reaches at most 10000 results; past that an empty page is returned alongside the true numberOfHits. Minimum: 0. Default: 0.
• disciplinestringFilter by discipline (e.g., "Electrical", "HVAC")
• document_type'document' | 'drawing'Filter by document type
• floorstringFilter by floor level
• sort_by'relevance' | 'createdAt' | 'updatedAt' | 'filename'Field to sort by. "filename" currently orders on a normalised copy of the name that is lower-cased and has common words removed, so the order can differ noticeably from the displayed filename - a code like "SER" is dropped when it happens to be a word in the document's language. This is being corrected to sort on the stored filename. Default: "relevance".
• sort_order'asc' | 'desc'Sort order (only applies when sort_by is not "relevance") Default: "desc".
• include_aggregationsbooleanInclude aggregated facet counts in response Default: false.
• fuzziness'auto' | 'on' | 'off'Fuzzy-matching mode. "on" always fuzzy-matches (best for prose). "off" matches exactly (best for equipment, system and drawing codes). "auto" (default) keeps fuzzy matching for prose but turns it off when the query looks like an identifier - any token containing a digit, or an all-short query such as "VVS". Default: "auto".

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

• hitsSearchHit[]Array of matching documents (same shape as building search)
• numberOfHitsnumberUpper bound on matching documents. Documents in private folders are counted but not returned, so a page can be shorter than max_results - page until hits is empty rather than until a short page.
• aggregationsAggregationsAggregated facet counts (optional)

Response

{
  "hits": [
    {
      "id": "doc-1",
      "buildingId": "bld-789",
      "filename": "fire-safety-report.pdf",
      "title": "Fire Safety Assessment 2025",
      "buildingCategory": "Fire Safety",
      "discipline": "Fire",
      "isDrawing": false,
      "md5Checksum": "a3f2b8c1e9d04567890abcdef1234567", // pragma: allowlist secret
      "originalCreatedAt": "2025-01-10T08:00:00Z",
      "originalPath": "/reports/fire-safety/",
      "size": 2048576,
      "informationType": "Report",
      "informationTypes": ["Report"],
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-06-20T14:00:00Z",
      "externalIds": {}
    }
  ],
  "numberOfHits": 156
}