Search

Authentication

x-api-key header

• buildingOwnerIdstringBuilding owner / customer ID
• buildingIdstringBuilding ID

• querystringrequiredSearch query
• max_resultsnumberMaximum results to return, 1-1000 (default: 20)
• start_indexnumberOffset for pagination (default: 0)
• disciplinestringFilter by discipline (e.g. "Electrical", "HVAC", "Fire")
• document_type"document" | "drawing"Filter by document type
• floorstringFilter by floor level
• sort_by"relevance" | "createdAt" | "updatedAt" | "filename"Field to sort by (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)

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)
• numberOfHitsnumberTotal number of matching documents
• 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
• max_resultsnumberMaximum results to return, 1-1000 (default: 20)
• start_indexnumberOffset for pagination (default: 0)
• disciplinestringFilter by discipline
• document_type"document" | "drawing"Filter by document type
• floorstringFilter by floor level
• sort_by"relevance" | "createdAt" | "updatedAt" | "filename"Field to sort by (default: relevance)
• sort_order"asc" | "desc"Sort order (default: desc)
• include_aggregationsbooleanInclude aggregated facet counts (default: false)

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

• hitsSearchHit[]Array of matching documents (same shape as building search)
• numberOfHitsnumberTotal number of matching documents
• 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
}