Ask

Authentication

x-api-key header

• buildingOwnerIdstringBuilding owner / customer ID
• buildingIdstringBuilding ID

• querystringrequiredThe question to ask (1-5000 characters)
• stream'true' | 'false'Enable SSE streaming. Default: 'false'
• language'en' | 'no' | 'nb' | 'nn'Response language
• thread_idstring (UUID)Continue an existing conversation thread
• reasoning_effort'low' | 'medium' | 'high'AI reasoning effort. Default: 'medium'

• attached_document_idsstring[]Up to 50 document IDs to include as context for the question
• use_agentic_ragbooleanEnable agentic RAG retrieval for this Ask request. Omit to use the API default.

Request Body Example

{
  "attached_document_ids": ["doc-1", "doc-2"],
  "use_agentic_rag": true
}

Examples

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  "https://api.findable.ai/v1/building_owners/cust-456/buildings/bld-789/ask?query=What+fire+safety+measures+are+documented%3F"

• 200Success
• 400Invalid query or parameters
• 401Missing or invalid API key
• 404Building not found

• answerstringThe AI-generated answer
• thread_idstringConversation thread ID (pass back to continue the conversation)
• citationsRecord<string, Citation>Numbered citations referenced in the answer text
• citations[n].cited_textstringThe cited passage from the source document
• citations[n].document_idstringID of the source document
• citations[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 answer
• cited_documents[].idstringDocument ID
• cited_documents[].filenamestringDocument filename
• follow_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"
  ]
}

Authentication

x-api-key header

• buildingOwnerIdstringBuilding owner / customer ID

• querystringrequiredThe question to ask (1-5000 characters)
• stream'true' | 'false'Enable SSE streaming. Default: 'false'
• language'en' | 'no' | 'nb' | 'nn'Response language
• thread_idstring (UUID)Continue an existing conversation thread
• reasoning_effort'low' | 'medium' | 'high'AI reasoning effort. Default: 'medium'

• building_idsstring[]Up to 100 building IDs to scope the question to. Omit to use all readable buildings for the building owner.
• attached_document_idsstring[]Up to 50 document IDs to include as context for the question
• use_agentic_ragbooleanEnable agentic RAG retrieval for this Ask request. Omit to use the API default.

Request Body Example

{
  "building_ids": ["bld-789", "bld-456"],
  "attached_document_ids": ["doc-1", "doc-2"],
  "use_agentic_rag": true
}

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/ask?query=Summarise+fire+safety+across+these+buildings"

• 200Success
• 400Invalid query or parameters
• 401Missing or invalid API key
• 403API key lacks access to one or more buildings
• 404Building owner or building not found

• answerstringThe AI-generated answer
• thread_idstringConversation thread ID (pass back to continue the conversation)
• citationsRecord<string, Citation>Numbered citations referenced in the answer text
• cited_documentsCitedDocument[]Documents referenced in the answer
• follow_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?"
  ]
}