FindableClient
The main entry point for the SDK. Create an instance and call methods to interact with the Partner API.
Constructor
// Server-side: use API key directly
const client = new FindableClient({
apiKey: 'YOUR_API_KEY', // pragma: allowlist secret
buildingOwnerId: 'cust-456',
});
// Client-side: use a session token (see createSession below)
const client = new FindableClient({
token: 'ft_...',
buildingOwnerId: 'cust-456',
});| Prop | Type | Default | Description |
|---|---|---|---|
apiKey | string | — | Your Findable API key. Provide either apiKey or token. |
token | string | — | A short-lived session token from createSession(). Provide either apiKey or token. |
buildingOwnerId* | string | — | The building owner (customer) ID. |
baseUrl | string | 'https://api.findable.ai' | API base URL override. |
listBuildings()
List every building available to the configured building owner.
const buildings = await client.listBuildings();
// Building[] — { id, name, numberOfFiles, createdAt, updatedAt }getIntegrationStatus()
Integration sync status and document count for every readable building, connected or not. Each building lists one entry per connected integration with its most recent sync run; see the Integrations API for field semantics.
const { buildings, unavailableSources } = await client.getIntegrationStatus();
// buildings: BuildingIntegrationStatus[] — { buildingId, buildingName, externalId,
// numberOfFiles, integrations: [{ source, syncStatus, lastSyncedAt, exportFolder }] }search(options)
Search documents. Omit buildingId to search across all buildings.
const result = await client.search({
query: 'fire safety',
buildingId: 'bld-789', // optional
maxResults: 10, // optional
startIndex: 0, // optional, for pagination
});
// { hits: SearchHit[], numberOfHits: number }assistant(options)
Ask the Findable Assistant a question and receive a complete response (non-streaming).
const response = await client.assistant({
buildingId: 'bld-789',
query: 'What fire safety documents exist?',
language: 'en', // optional: 'en' | 'no' | 'nb' | 'nn'
threadId: 'prev-thread-id', // optional: continue a conversation
attachedDocumentIds: ['doc1'], // optional: focus on specific documents
mode: 'fast', // optional: 'fast' | 'balanced' | 'deep' (default)
});
// { answer, threadId, citations, citedDocuments, followUpSuggestions }assistantAcrossBuildings(options)
Ask a question across one or more buildings. Omit buildingIds to ask across all readable buildings for the building owner.
const response = await client.assistantAcrossBuildings({
query: 'Summarise fire safety across the portfolio',
buildingIds: ['bld-789', 'bld-456'], // optional
language: 'en', // optional
threadId: 'prev-thread-id', // optional
attachedDocumentIds: ['doc1'], // optional
mode: 'balanced', // optional: 'fast' | 'balanced' | 'deep'
});
// { answer, threadId, citations, citedDocuments, followUpSuggestions }assistantStream(options)
Same options as assistant(), but returns an async iterable of streaming events. See the Streaming guide.
const stream = client.assistantStream({ buildingId: 'bld-789', query: '...' });
for await (const event of stream) {
switch (event.event) {
case 'start': // { threadId }
case 'text': // { text }
case 'thinking': // { text }
case 'finish': // { threadId, answer, citations, citedDocuments, followUpSuggestions }
case 'error': // { message }
}
}
// Cancel early:
stream.abort();assistantAcrossBuildingsStream(options)
Streaming variant of assistantAcrossBuildings().
const stream = client.assistantAcrossBuildingsStream({
query: 'Which building has the newest fire report?',
});
for await (const event of stream) {
if (event.event === 'text') process.stdout.write(event.text);
}createSession(options?)
Exchange an API key for a short-lived session token suitable for browser use. Only works when the client was created with an apiKey.
// On your server
const server = new FindableClient({ apiKey: 'fk_live_...', buildingOwnerId: 'cust-456' }); // pragma: allowlist secret
const session = await server.createSession({ expiresIn: 3600 }); // optional, default 1h
// => { token: 'ft_...', expiresAt: '2026-03-20T13:00:00.000Z' }
// Pass session.token to the browser and use it there:
const browser = new FindableClient({ token: session.token, buildingOwnerId: 'cust-456' });| Prop | Type | Default | Description |
|---|---|---|---|
expiresIn | number | — | Token lifetime in seconds (60–86400). Default 3600. |
Deprecated Method Names
The Assistant was previously called Ask. These methods still work and are deprecated, with no removal date.
ask(options)Deprecated name for assistant(options).askAcrossBuildings(options)Deprecated name for assistantAcrossBuildings(options).askStream(options)Deprecated name for assistantStream(options).askAcrossBuildingsStream(options)Deprecated name for assistantAcrossBuildingsStream(options).
Error Handling
All methods throw typed errors:
import { FindableError, AuthError } from '@findable-ai/sdk';
try {
await client.assistant({ ... });
} catch (err) {
if (err instanceof AuthError) {
// 401 — invalid API key
} else if (err instanceof FindableError) {
console.error(err.status, err.message);
}
}