Findable Assistant
The Findable Assistant provides AI-powered Q&A over building documents. It supports both streaming (SSE) and non-streaming responses. Answers are read-only and drawn from the building's documents: a request can never change data or reach beyond what the API key can read.
/ask and /ask-sharepoint routes take the same requests and return the same responses, and the ask* SDK methods still work. They are deprecated, with no removal date.Each API key can run one Findable Assistant request at a time, across every Assistant endpoint and the old /ask ones, and including session tokens minted from the key. A request sent while another one is still running gets 429 Too Many Requests with a Retry-After header. To ask several questions, send each one after the previous answer has finished. For a streaming request, that is when the stream ends. Closing the connection early does not cancel the answer: the key stays busy until it has finished. If the connection is dropped during a very long answer, the key can stay busy for up to 15 minutes.
/v1/building_owners/{buildingOwnerId}/buildings/{buildingId}/assistantAsk a question about a building's documents. Returns an AI-generated answer with citations.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer IDbuildingIdstringBuilding ID
querystringrequiredThe question to ask (1–5000 characters).language'en' | 'no' | 'nb' | 'nn'Response language.thread_idstring (UUID)Continue an existing conversation thread.stream'true' | 'false'Enable SSE streaming. Default: 'false'.reasoning_effort'low' | 'medium' | 'high'Deprecated: use mode. Default: "medium". "high" behaves like mode=deep; "low" and "medium" both behave like mode=balanced and are indistinguishable. Ignored when mode is set.mode'fast' | 'balanced' | 'deep'How much work goes into the answer. fast: cheapest and quickest, roughly 15x cheaper than balanced and several times faster, with shallower synthesis across many documents; good for lookups and single-document questions. balanced: the default when mode is omitted. deep: most thorough and most expensive. Omit it and requests are answered exactly as before.
attached_document_idsstring[]Up to 50 document IDs to include as context for the question.use_agentic_ragbooleanDeprecated — agentic RAG is always used. Omit this field; sending false is rejected with a 400.
Request Body Example
{
"attached_document_ids": ["doc-1", "doc-2"]
}Examples
curl -X POST \
-H "x-api-key: YOUR_API_KEY" \
"https://api.findable.ai/v1/building_owners/cust-456/buildings/bld-789/assistant?query=What+fire+safety+measures+are+documented%3F"200Success400Invalid query or parameters401Missing or invalid API key404Building not found503Retryable Smart Search transport failure in non-streaming Assistant requests, including a failure while collecting the answer. Streaming Assistant requests send an in-band error instead of changing HTTP status.
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
answerstringThe AI-generated answerthread_idstringConversation thread ID (pass back to continue the conversation)citationsRecord<string, Citation>Numbered citations referenced in the answer textcitations[n].cited_textstringThe cited passage from the source documentcitations[n].document_idstringID of the source documentcitations[n].page_numberstring | number (optional)Source page when the model grounded the citation (common for PDFs; omit when unknown)cited_documentsCitedDocument[]Documents referenced in the answercited_documents[].idstringDocument IDcited_documents[].filenamestringDocument filenamefollow_up_suggestionsstring[]Suggested follow-up questions
Response
{
"answer": "Based on the fire safety documents...",
"thread_id": "550e8400-e29b-41d4-a716-446655440000",
"citations": {
"1": {
"cited_text": "Section 3.2 states...",
"document_id": "doc-1",
"page_number": 12
}
},
"cited_documents": [
{ "id": "doc-1", "filename": "fire-safety-report.pdf" }
],
"follow_up_suggestions": [
"What are the evacuation procedures?",
"Show me the sprinkler system specs"
]
}Assistant Across Buildings
/v1/building_owners/{buildingOwnerId}/assistantAsk a question across one or more buildings for a building owner. Omit building_ids to ask across all readable buildings for the building owner.
Authentication
x-api-key header
buildingOwnerIdstringBuilding owner / customer ID
querystringrequiredThe question to ask (1–5000 characters).language'en' | 'no' | 'nb' | 'nn'Response language.thread_idstring (UUID)Continue an existing conversation thread.stream'true' | 'false'Enable SSE streaming. Default: 'false'.reasoning_effort'low' | 'medium' | 'high'Deprecated: use mode. Default: "medium". "high" behaves like mode=deep; "low" and "medium" both behave like mode=balanced and are indistinguishable. Ignored when mode is set.mode'fast' | 'balanced' | 'deep'How much work goes into the answer. fast: cheapest and quickest, roughly 15x cheaper than balanced and several times faster, with shallower synthesis across many documents; good for lookups and single-document questions. balanced: the default when mode is omitted. deep: most thorough and most expensive. Omit it and requests are answered exactly as before.
attached_document_idsstring[]Up to 50 document IDs to include as context for the question.use_agentic_ragbooleanDeprecated — agentic RAG is always used. Omit this field; sending false is rejected with a 400.building_idsstring[]Up to 100 building IDs to scope the question. Omit to use every readable building.
Request Body Example
{
"building_ids": ["bld-789", "bld-456"],
"attached_document_ids": ["doc-1", "doc-2"]
}Examples
curl -X POST \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"building_ids":["bld-789","bld-456"]}' \
"https://api.findable.ai/v1/building_owners/cust-456/assistant?query=Summarise+fire+safety+across+these+buildings"200Success400Invalid query or parameters401Missing or invalid API key403API key lacks access to one or more buildings404Building owner or building not found503Retryable Smart Search transport failure in non-streaming Assistant requests, including a failure while collecting the answer. Streaming Assistant requests send an in-band error instead of changing HTTP status.
All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.
answerstringThe AI-generated answerthread_idstringConversation thread ID (pass back to continue the conversation)citationsRecord<string, Citation>Numbered citations referenced in the answer textcited_documentsCitedDocument[]Documents referenced in the answerfollow_up_suggestionsstring[]Suggested follow-up questions
Response
{
"answer": "Across the selected buildings, the fire safety documentation includes...",
"thread_id": "550e8400-e29b-41d4-a716-446655440000",
"citations": {
"1": { "cited_text": "Section 3.2 states...", "document_id": "doc-1" }
},
"cited_documents": [
{ "id": "doc-1", "filename": "fire-safety-report.pdf" }
],
"follow_up_suggestions": [
"Which building has the newest fire report?"
]
}Streaming Response
When stream=true, the response is sent as Server-Sent Events (SSE).
| Event | Fields | Description |
|---|---|---|
start | thread_id | Stream started |
text | text | Incremental answer text |
thinking | text | AI reasoning text |
action | state, value, result | Agent progress/action update |
finish | thread_id, answer, citations, cited_documents, follow_up_suggestions | Complete response |
error | message | Error occurred; the stream closes after this event |