Function: useApi()

useApi(options?): { API: LowLevelApi; broadcast: (event) => Promise<any>; broadcastToWebviews: (event) => Promise<any>; enterFullscreen: () => Promise<any>; exitFullscreen: () => Promise<any>; getRequestTypes: () => Promise<any>; isFullscreen: () => Promise<any>; logout: () => Promise<any>; off: (type, callback) => void; on: (type, callback) => void; quitInstance: () => Promise<any>; subscribe: () => Promise<any>; unsubscribe: () => Promise<any>; aiComplete: Promise<AICompleteResult>; aiGetCapabilities: Promise<AIRuntimeCapabilities>; appsDbDeleteEntry: Promise<void>; appsDbGetEntries: Promise<AppsDbEntriesResult>; appsDbPsql: Promise<AppsDbEntriesResult>; appsDbUpsertEntry: Promise<AppsDbEntry>; assignCanvasTheme: Promise<{ canvas_id: string; theme_id: string; }>; close: Promise<any>; createCanvas: Promise<CanvasRetrieve>; createFile: Promise<FileRetrieve>; createFolder: Promise<FolderRetrieve>; crmCreate: Promise<any>; crmDescribe: Promise<any>; crmLayout: Promise<any>; crmQuery: Promise<any>; crmQueryAdaptive: Promise<any>; crmSmartDeleteObjects: Promise<any>; crmSmartObjectLayout: Promise<any>; crmSmartObjectMetadata: Promise<any>; crmSmartObjectValidationRules: Promise<any>; crmSmartQuery: Promise<any[]>; crmSmartUpsertObjects: Promise<any>; crmUpsert: Promise<any>; deleteCanvas: Promise<CanvasRetrieve>; deleteFile: Promise<string>; deleteFolder: Promise<void>; deleteLocalFile: Promise<void>; downloadFile: Promise<null>; fetchDocumentInfo: Promise<{[key: string]: unknown; pageCount: number; }>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getCanvasRecommendedFiles: Promise<CanvasRecommendedFiles>; getCanvasTheme: Promise<CanvasThemeRetrieve | null>; getCoreFolders: Promise<CoreFolderContentsRetrieve>; getEnv: Promise<PitcherEnv>; getFile: Promise<FileRetrieve>; getFileRevisionData: Promise<FileRetrieve>; getFileRevisions: Promise<FileRevision[]>; getFiles: Promise<PaginatedFileList>; getFolder: Promise<FolderRetrieve>; getFolders: Promise<PaginatedFolderList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getSectionsByIds: Promise<{ sections: CanvasSection[]; }>; getThemes: Promise<CanvasThemeRetrieve[]>; getUsers: Promise<PaginatedData<User>>; isOffline: Promise<boolean>; moveFolderItems: Promise<FolderRetrieve>; notify: Promise<void>; open: Promise<string>; openExternalUrl: Promise<void>; openWebViewAlwaysOnTop: Promise<void>; patchCoreFolder: Promise<CoreFolderContentsRetrieve>; piaSearchAnswer: Promise<PiaSearchAnswerResult>; postJsonWithTimeout: Promise<T>; query: Promise<any>; refreshAccessToken: any; refreshServiceToken: Promise<RefreshServiceTokenResponse>; renderPageAsImage: Promise<ArrayBuffer>; search: Promise<any>; selectDeviceFile: Promise<DeviceFile>; share: Promise<ShareResponse>; shareCanvas: Promise<SharedLink>; showPeerSession: Promise<void>; showSyncbox: Promise<void>; slideSearch: Promise<SlideSearchResult>; sttAvailability: Promise<SttAvailabilityResult>; sttErrorCode: SttErrorCode | undefined; sttStart: Promise<void>; sttStop: Promise<SttStopResult>; sttWarmup: Promise<void>; submitUserFeedback: Promise<any>; toast: Promise<void>; track: Promise<any>; triggerNonFilesSync: Promise<void>; ttsErrorCode: TtsErrorCode | undefined; ttsSpeak: Promise<TtsSpeakResult>; ttsStop: Promise<void>; ttsWarmup: Promise<void>; unassignCanvasTheme: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateCanvasIndicators: Promise<CanvasRetrieve>; updateFile: Promise<FileRetrieve>; updateFolder: Promise<FolderRetrieve>; updateMyUser: Promise<User>; weeklyFocusRank: Promise<WeeklyFocusRankResult>; } | { on: (type, handler) => Promise<() => void>; toast: (payload) => Promise<void>; captureAppError: Promise<void>; close: Promise<void>; createCanvas: Promise<CanvasRetrieve>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getEnv: Promise<AdminEnv>; getFile: Promise<File>; getFiles: Promise<PaginatedFileList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getUsers: Promise<PaginatedData<User>>; open: Promise<void>; openCanvasOverlay: Promise<void>; openCollectionPlayerOverlay: Promise<void>; selectAgendaContent: Promise<AdminSelectAgendaResponse>; selectCanvases: Promise<AdminSelectCanvasesResponse>; selectCollectionContent: Promise<AdminSelectCollectionPlayerResponse>; selectContent: Promise<AdminSelectContentResponse>; updateCanvas: Promise<CanvasRetrieve>; } | { API: LowLevelApi; broadcast: (event) => Promise<any>; broadcastToWebviews: (event) => Promise<any>; enterFullscreen: () => Promise<any>; exitFullscreen: () => Promise<any>; getRequestTypes: () => Promise<any>; impact: { API: LowLevelApi; broadcast: (event) => Promise<any>; broadcastToWebviews: (event) => Promise<any>; enterFullscreen: () => Promise<any>; exitFullscreen: () => Promise<any>; getRequestTypes: () => Promise<any>; isFullscreen: () => Promise<any>; logout: () => Promise<any>; off: (type, callback) => void; on: (type, callback) => void; quitInstance: () => Promise<any>; subscribe: () => Promise<any>; unsubscribe: () => Promise<any>; aiComplete: Promise<AICompleteResult>; aiGetCapabilities: Promise<AIRuntimeCapabilities>; appsDbDeleteEntry: Promise<void>; appsDbGetEntries: Promise<AppsDbEntriesResult>; appsDbPsql: Promise<AppsDbEntriesResult>; appsDbUpsertEntry: Promise<AppsDbEntry>; assignCanvasTheme: Promise<{ canvas_id: string; theme_id: string; }>; close: Promise<any>; createCanvas: Promise<CanvasRetrieve>; createFile: Promise<FileRetrieve>; createFolder: Promise<FolderRetrieve>; crmCreate: Promise<any>; crmDescribe: Promise<any>; crmLayout: Promise<any>; crmQuery: Promise<any>; crmQueryAdaptive: Promise<any>; crmSmartDeleteObjects: Promise<any>; crmSmartObjectLayout: Promise<any>; crmSmartObjectMetadata: Promise<any>; crmSmartObjectValidationRules: Promise<any>; crmSmartQuery: Promise<any[]>; crmSmartUpsertObjects: Promise<any>; crmUpsert: Promise<any>; deleteCanvas: Promise<CanvasRetrieve>; deleteFile: Promise<string>; deleteFolder: Promise<void>; deleteLocalFile: Promise<void>; downloadFile: Promise<null>; fetchDocumentInfo: Promise<{[key: string]: unknown; pageCount: number; }>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getCanvasRecommendedFiles: Promise<CanvasRecommendedFiles>; getCanvasTheme: Promise<CanvasThemeRetrieve | null>; getCoreFolders: Promise<CoreFolderContentsRetrieve>; getEnv: Promise<PitcherEnv>; getFile: Promise<FileRetrieve>; getFileRevisionData: Promise<FileRetrieve>; getFileRevisions: Promise<FileRevision[]>; getFiles: Promise<PaginatedFileList>; getFolder: Promise<FolderRetrieve>; getFolders: Promise<PaginatedFolderList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getSectionsByIds: Promise<{ sections: CanvasSection[]; }>; getThemes: Promise<CanvasThemeRetrieve[]>; getUsers: Promise<PaginatedData<User>>; isOffline: Promise<boolean>; moveFolderItems: Promise<FolderRetrieve>; notify: Promise<void>; open: Promise<string>; openExternalUrl: Promise<void>; openWebViewAlwaysOnTop: Promise<void>; patchCoreFolder: Promise<CoreFolderContentsRetrieve>; piaSearchAnswer: Promise<PiaSearchAnswerResult>; postJsonWithTimeout: Promise<T>; query: Promise<any>; refreshAccessToken: any; refreshServiceToken: Promise<RefreshServiceTokenResponse>; renderPageAsImage: Promise<ArrayBuffer>; search: Promise<any>; selectDeviceFile: Promise<DeviceFile>; share: Promise<ShareResponse>; shareCanvas: Promise<SharedLink>; showPeerSession: Promise<void>; showSyncbox: Promise<void>; slideSearch: Promise<SlideSearchResult>; sttAvailability: Promise<SttAvailabilityResult>; sttErrorCode: SttErrorCode | undefined; sttStart: Promise<void>; sttStop: Promise<SttStopResult>; sttWarmup: Promise<void>; submitUserFeedback: Promise<any>; toast: Promise<void>; track: Promise<any>; triggerNonFilesSync: Promise<void>; ttsErrorCode: TtsErrorCode | undefined; ttsSpeak: Promise<TtsSpeakResult>; ttsStop: Promise<void>; ttsWarmup: Promise<void>; unassignCanvasTheme: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateCanvasIndicators: Promise<CanvasRetrieve>; updateFile: Promise<FileRetrieve>; updateFolder: Promise<FolderRetrieve>; updateMyUser: Promise<User>; weeklyFocusRank: Promise<WeeklyFocusRankResult>; }; isFullscreen: () => Promise<any>; logout: () => Promise<any>; off: (type, callback) => void; on: <T>(type, handler) => Promise<() => void>; onAppSetData: (handler) => Promise<() => void>; onAppUpdateData: (handler) => Promise<() => void>; onCanvasUpdated: (handler) => Promise<() => void>; onMeetingCanceled: (handler) => Promise<() => void>; onSectionListUpdated: (handler) => Promise<() => void>; quitInstance: () => Promise<any>; subscribe: () => Promise<any>; ui: { on: <T>(type, handler) => Promise<() => void>; onAppSetData: (handler) => Promise<() => void>; onAppUpdateData: (handler) => Promise<() => void>; onCanvasUpdated: (handler) => Promise<() => void>; onMeetingCanceled: (handler) => Promise<() => void>; onSectionListUpdated: (handler) => Promise<() => void>; uiBroadcast: { }; appFullscreenChange: Promise<void>; appLoaded: Promise<void>; appResize: Promise<void>; cancelMeeting: Promise<void>; canvasNavigateNextPage: Promise<void>; canvasNavigatePage: Promise<void>; canvasNavigatePreviousPage: Promise<void>; captureAppError: Promise<void>; closeCanvasDrawer: Promise<void>; closeCanvasSectionExecution: Promise<void>; closeGlobalPopup: Promise<void>; completePostcall: Promise<void>; disablePostcallSubmit: Promise<void>; embeddableReady: Promise<void>; enablePostcallSubmit: Promise<void>; open: Promise<void>; openCanvasOverlay: Promise<void>; openCollectionPlayerOverlay: Promise<void>; openGlobalPopup: Promise<UiOpenGlobalPopupResponse>; openSharingSettings: Promise<UiOpenSharingSettingsResponse>; preselectSfdcMeetingId: Promise<UiPreselectSfdcMeetingIdResponse>; printCanvas: Promise<UiPrintCanvasResponse>; promptPia: Promise<UiPromptPiaResponse>; resumeMeeting: Promise<void>; selectAgendaContent: Promise<UiSelectAgendaResponse>; selectCanvases: Promise<UiSelectCanvasesResponse>; selectCollectionContent: Promise<UiSelectCollectionPlayerResponse>; selectContent: Promise<UiSelectContentResponse>; setPostcallStyle: Promise<void>; stopMeeting: Promise<void>; toast: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateLocation: Promise<any>; }; uiBroadcast: { }; unsubscribe: () => Promise<any>; aiComplete: Promise<AICompleteResult>; aiGetCapabilities: Promise<AIRuntimeCapabilities>; appFullscreenChange: Promise<void>; appLoaded: Promise<void>; appResize: Promise<void>; appsDbDeleteEntry: Promise<void>; appsDbGetEntries: Promise<AppsDbEntriesResult>; appsDbPsql: Promise<AppsDbEntriesResult>; appsDbUpsertEntry: Promise<AppsDbEntry>; assignCanvasTheme: Promise<{ canvas_id: string; theme_id: string; }>; cancelMeeting: Promise<void>; canvasNavigateNextPage: Promise<void>; canvasNavigatePage: Promise<void>; canvasNavigatePreviousPage: Promise<void>; captureAppError: Promise<void>; close: Promise<any>; closeCanvasDrawer: Promise<void>; closeCanvasSectionExecution: Promise<void>; closeGlobalPopup: Promise<void>; completePostcall: Promise<void>; createCanvas: Promise<CanvasRetrieve>; createFile: Promise<FileRetrieve>; createFolder: Promise<FolderRetrieve>; crmCreate: Promise<any>; crmDescribe: Promise<any>; crmLayout: Promise<any>; crmQuery: Promise<any>; crmQueryAdaptive: Promise<any>; crmSmartDeleteObjects: Promise<any>; crmSmartObjectLayout: Promise<any>; crmSmartObjectMetadata: Promise<any>; crmSmartObjectValidationRules: Promise<any>; crmSmartQuery: Promise<any[]>; crmSmartUpsertObjects: Promise<any>; crmUpsert: Promise<any>; deleteCanvas: Promise<CanvasRetrieve>; deleteFile: Promise<string>; deleteFolder: Promise<void>; deleteLocalFile: Promise<void>; disablePostcallSubmit: Promise<void>; downloadFile: Promise<null>; embeddableReady: Promise<void>; enablePostcallSubmit: Promise<void>; fetchDocumentInfo: Promise<{[key: string]: unknown; pageCount: number; }>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getCanvasRecommendedFiles: Promise<CanvasRecommendedFiles>; getCanvasTheme: Promise<CanvasThemeRetrieve | null>; getCoreFolders: Promise<CoreFolderContentsRetrieve>; getEnv: Promise<PitcherEnv>; getFile: Promise<FileRetrieve>; getFileRevisionData: Promise<FileRetrieve>; getFileRevisions: Promise<FileRevision[]>; getFiles: Promise<PaginatedFileList>; getFolder: Promise<FolderRetrieve>; getFolders: Promise<PaginatedFolderList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getSectionsByIds: Promise<{ sections: CanvasSection[]; }>; getThemes: Promise<CanvasThemeRetrieve[]>; getUsers: Promise<PaginatedData<User>>; isOffline: Promise<boolean>; moveFolderItems: Promise<FolderRetrieve>; notify: Promise<void>; open: Promise<void>; openCanvasOverlay: Promise<void>; openCollectionPlayerOverlay: Promise<void>; openExternalUrl: Promise<void>; openGlobalPopup: Promise<UiOpenGlobalPopupResponse>; openSharingSettings: Promise<UiOpenSharingSettingsResponse>; openWebViewAlwaysOnTop: Promise<void>; patchCoreFolder: Promise<CoreFolderContentsRetrieve>; piaSearchAnswer: Promise<PiaSearchAnswerResult>; postJsonWithTimeout: Promise<T>; preselectSfdcMeetingId: Promise<UiPreselectSfdcMeetingIdResponse>; printCanvas: Promise<UiPrintCanvasResponse>; promptPia: Promise<UiPromptPiaResponse>; query: Promise<any>; refreshAccessToken: any; refreshServiceToken: Promise<RefreshServiceTokenResponse>; renderPageAsImage: Promise<ArrayBuffer>; resumeMeeting: Promise<void>; search: Promise<any>; selectAgendaContent: Promise<UiSelectAgendaResponse>; selectCanvases: Promise<UiSelectCanvasesResponse>; selectCollectionContent: Promise<UiSelectCollectionPlayerResponse>; selectContent: Promise<UiSelectContentResponse>; selectDeviceFile: Promise<DeviceFile>; setPostcallStyle: Promise<void>; share: Promise<ShareResponse>; shareCanvas: Promise<SharedLink>; showPeerSession: Promise<void>; showSyncbox: Promise<void>; slideSearch: Promise<SlideSearchResult>; stopMeeting: Promise<void>; sttAvailability: Promise<SttAvailabilityResult>; sttErrorCode: SttErrorCode | undefined; sttStart: Promise<void>; sttStop: Promise<SttStopResult>; sttWarmup: Promise<void>; submitUserFeedback: Promise<any>; toast: Promise<void>; track: Promise<any>; triggerNonFilesSync: Promise<void>; ttsErrorCode: TtsErrorCode | undefined; ttsSpeak: Promise<TtsSpeakResult>; ttsStop: Promise<void>; ttsWarmup: Promise<void>; unassignCanvasTheme: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateCanvasIndicators: Promise<CanvasRetrieve>; updateFile: Promise<FileRetrieve>; updateFolder: Promise<FolderRetrieve>; updateLocation: Promise<any>; updateMyUser: Promise<User>; weeklyFocusRank: Promise<WeeklyFocusRankResult>; } | { broadcast: (event) => Promise<any>; on: (type, handler) => Promise<() => void>; close: Promise<void>; embeddableReady: Promise<void>; getAppConfig: Promise<Record<string, any>>; getEnv: Promise<DsrEnv>; getFile: Promise<File>; }

This method returns an object containing the API methods that are available to you in a given environment, whether that be the Canvas, UI, Admin or DSR.

• CatalogIQ UI - the method will return an object containing methods available in both usePitcherApi and useUi
• CatalogIQ DSR - the method will return the same result as useDsr
• CatalogIQ Admin - the method will return the same result as useAdmin

import { useApi } from '@pitcher/js-api'

const api = useApi()

Parameters

Parameter	Type
options?	ApiOptions

Returns

Type Literal

{ API: LowLevelApi; broadcast: (event) => Promise<any>; broadcastToWebviews: (event) => Promise<any>; enterFullscreen: () => Promise<any>; exitFullscreen: () => Promise<any>; getRequestTypes: () => Promise<any>; isFullscreen: () => Promise<any>; logout: () => Promise<any>; off: (type, callback) => void; on: (type, callback) => void; quitInstance: () => Promise<any>; subscribe: () => Promise<any>; unsubscribe: () => Promise<any>; aiComplete: Promise<AICompleteResult>; aiGetCapabilities: Promise<AIRuntimeCapabilities>; appsDbDeleteEntry: Promise<void>; appsDbGetEntries: Promise<AppsDbEntriesResult>; appsDbPsql: Promise<AppsDbEntriesResult>; appsDbUpsertEntry: Promise<AppsDbEntry>; assignCanvasTheme: Promise<{ canvas_id: string; theme_id: string; }>; close: Promise<any>; createCanvas: Promise<CanvasRetrieve>; createFile: Promise<FileRetrieve>; createFolder: Promise<FolderRetrieve>; crmCreate: Promise<any>; crmDescribe: Promise<any>; crmLayout: Promise<any>; crmQuery: Promise<any>; crmQueryAdaptive: Promise<any>; crmSmartDeleteObjects: Promise<any>; crmSmartObjectLayout: Promise<any>; crmSmartObjectMetadata: Promise<any>; crmSmartObjectValidationRules: Promise<any>; crmSmartQuery: Promise<any[]>; crmSmartUpsertObjects: Promise<any>; crmUpsert: Promise<any>; deleteCanvas: Promise<CanvasRetrieve>; deleteFile: Promise<string>; deleteFolder: Promise<void>; deleteLocalFile: Promise<void>; downloadFile: Promise<null>; fetchDocumentInfo: Promise<{[key: string]: unknown; pageCount: number; }>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getCanvasRecommendedFiles: Promise<CanvasRecommendedFiles>; getCanvasTheme: Promise<CanvasThemeRetrieve | null>; getCoreFolders: Promise<CoreFolderContentsRetrieve>; getEnv: Promise<PitcherEnv>; getFile: Promise<FileRetrieve>; getFileRevisionData: Promise<FileRetrieve>; getFileRevisions: Promise<FileRevision[]>; getFiles: Promise<PaginatedFileList>; getFolder: Promise<FolderRetrieve>; getFolders: Promise<PaginatedFolderList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getSectionsByIds: Promise<{ sections: CanvasSection[]; }>; getThemes: Promise<CanvasThemeRetrieve[]>; getUsers: Promise<PaginatedData<User>>; isOffline: Promise<boolean>; moveFolderItems: Promise<FolderRetrieve>; notify: Promise<void>; open: Promise<string>; openExternalUrl: Promise<void>; openWebViewAlwaysOnTop: Promise<void>; patchCoreFolder: Promise<CoreFolderContentsRetrieve>; piaSearchAnswer: Promise<PiaSearchAnswerResult>; postJsonWithTimeout: Promise<T>; query: Promise<any>; refreshAccessToken: any; refreshServiceToken: Promise<RefreshServiceTokenResponse>; renderPageAsImage: Promise<ArrayBuffer>; search: Promise<any>; selectDeviceFile: Promise<DeviceFile>; share: Promise<ShareResponse>; shareCanvas: Promise<SharedLink>; showPeerSession: Promise<void>; showSyncbox: Promise<void>; slideSearch: Promise<SlideSearchResult>; sttAvailability: Promise<SttAvailabilityResult>; sttErrorCode: SttErrorCode | undefined; sttStart: Promise<void>; sttStop: Promise<SttStopResult>; sttWarmup: Promise<void>; submitUserFeedback: Promise<any>; toast: Promise<void>; track: Promise<any>; triggerNonFilesSync: Promise<void>; ttsErrorCode: TtsErrorCode | undefined; ttsSpeak: Promise<TtsSpeakResult>; ttsStop: Promise<void>; ttsWarmup: Promise<void>; unassignCanvasTheme: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateCanvasIndicators: Promise<CanvasRetrieve>; updateFile: Promise<FileRetrieve>; updateFolder: Promise<FolderRetrieve>; updateMyUser: Promise<User>; weeklyFocusRank: Promise<WeeklyFocusRankResult>; }

API

API: LowLevelApi

broadcast

broadcast: (event) => Promise<any>

Broadcast an event to CatalogIQ.

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcast({
    type: "canvas_updated",
    body: { context: { myContextProperty: 'test' } },
  })
  .then(function (result) {
    useUi().toast({
      message: "Canvas Populated.",
      type: "info",
    })
  })

broadcastToWebviews

broadcastToWebviews: (event) => Promise<any>

Broadcast an event to webviews only (iOS only).

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcastToWebviews({
    type: "canvas_updated",
    body: { context: { myContextProperty: 'test' } },
  })
  .then(function (result) {
    useUi().toast({
      message: "Canvas Populated.",
      type: "info",
    })
  })

enterFullscreen

enterFullscreen: () => Promise<any>

Make the entire CatalogIQ fullscreen.

Returns

Promise<any>

Example

usePitcherApi().enterFullscreen()

exitFullscreen

exitFullscreen: () => Promise<any>

Exit fullscreen mode.

Returns

Promise<any>

Example

usePitcherApi().exitFullscreen()

getRequestTypes

getRequestTypes: () => Promise<any>

Get the request types.

Returns

Promise<any>

isFullscreen

isFullscreen: () => Promise<any>

Return is CatalogIQ in fullscreen.

Returns

Promise<any>

Example

usePitcherApi().isFullscreen()

logout

logout: () => Promise<any>

Log out the current user.

Returns

Promise<any>

Example

usePitcherApi().logout()

off

off: (type, callback) => void

Unsubscribe from a given event type by its key and the attached callback reference.

Parameters

Parameter	Type	Description
type	string	The event type to unsubscribe from.
callback	(payload) => void	The callback function reference to remove.

Returns

void

Example

const callback = (event: object) => {
  // handle event
}
usePitcherApi().on('entered_fullscreen', callback)
// later
usePitcherApi().off('entered_fullscreen', callback)

on

on: (type, callback) => void

Subscribe to a given event type by its key.

Parameters

Parameter	Type	Description
type	string	The event type to subscribe to.
callback	(payload) => void	The callback function to handle the event.

Returns

void

Nothing. To unsubscribe, pass the same callback reference to off().

Example

usePitcherApi().on('entered_fullscreen', (event: object) => {
  // handle event
})

quitInstance

quitInstance: () => Promise<any>

Quit the current instance and go to the instance selection screen.

Returns

Promise<any>

Example

usePitcherApi().quitInstance()

subscribe

subscribe: () => Promise<any>

Subscribe to updates.

Returns

Promise<any>

unsubscribe

unsubscribe: () => Promise<any>

Unsubscribe from updates.

Returns

Promise<any>

aiComplete()

aiComplete(payload): Promise<AICompleteResult>

Run an AI completion on the on-device model (iOS only). On web the host rejects with a clear error — use piaSearchAnswer (or the next-core AI routes) for online inference instead.

The payload is the EXACT iOS wire contract: { prompt, max_tokens?, stream? } → { text, tokens_generated, elapsed_seconds, time_to_first_token_seconds }.

Parameters

Parameter	Type	Description
payload	AICompletePayload	The completion payload.

Returns

Promise<AICompleteResult>

• Promise resolving with the completion.

Example

const completion = await api.aiComplete({ prompt: 'Summarize ...', max_tokens: 256 })
console.log(completion.text)

aiGetCapabilities()

aiGetCapabilities(): Promise<AIRuntimeCapabilities>

Capabilities of the AI completion runtime on the current platform.

On iOS this asks the native on-device bridge (ai.get_capabilities); on web it resolves statically to the online (Bedrock) runtime — no postMessage round-trip.

Returns

Promise<AIRuntimeCapabilities>

• Promise resolving with the runtime capabilities.

Example

const capabilities = await api.aiGetCapabilities()
if (capabilities.available) { ... }

appsDbDeleteEntry()

appsDbDeleteEntry(payload): Promise<void>

Deletes an AppsDB entry (soft delete server-side), adapting to the platform:

• Web: DELETE to the next-core AppsDB REST API.
• Native (iPad or desktop): the appsdb_delete_entry bridge request deletes on the server and removes the entry from the local offline mirror. Offline it rejects with code = offline_write_not_supported.

Parameters

Parameter	Type
payload	AppsDbDeleteEntryPayload

Returns

Promise<void>

Example

await api.appsDbDeleteEntry({ id: '01H5ZXE7YP2JR6Q1Z2G3K4H5J6' })

appsDbGetEntries()

appsDbGetEntries(payload): Promise<AppsDbEntriesResult>

Lists AppsDB entries of a type, adapting to the platform:

• Web: GET to the next-core AppsDB REST API.
• Native (iPad or desktop): reads the local offline mirror via the appsdb_get_entries bridge request. Types not allowlisted in the offline_appsdb_types setting fail with code = type_not_synced and automatically fall back to the network.

Parameters

Parameter	Type
payload	AppsDbGetEntriesPayload

Returns

Promise<AppsDbEntriesResult>

Example

const { entries } = await api.appsDbGetEntries({ type: 'favorite' })

appsDbPsql()

appsDbPsql(payload): Promise<AppsDbEntriesResult>

Runs a PSQL (SQL-like) query against AppsDB: POST to the next-core /appsdb/psql endpoint whenever the network is available.

On a native host the local offline mirror (appsdb_get_entries + client-side evaluation of simple field = literal AND-chains) serves the query ONLY while the device is offline, or when an online fetch fails at the connection level. Online queries are always answered by the server: Hub flows use psql results to decide between creating and updating an entry, and the mirror can lag the server by a sync cycle (multi-device) — a stale empty read would turn an update into a duplicate create. Offline that same stale read is harmless because AppsDB writes are rejected offline anyway.

Parameters

Parameter	Type
payload	AppsDbPsqlPayload

Returns

Promise<AppsDbEntriesResult>

Example

const { entries } = await api.appsDbPsql({
  query: "SELECT * FROM personalfolders WHERE user_id = 1 AND data.custom_domain = 'acme.my.pitcher.com'",
})

appsDbUpsertEntry()

appsDbUpsertEntry(payload): Promise<AppsDbEntry>

Creates or updates (deep-merges) an AppsDB entry, adapting to the platform:

• Web: POST (create) or PUT (update, when id is set) to the next-core AppsDB REST API.
• Native (iPad or desktop): the appsdb_upsert_entry bridge request writes on the server and mirrors the authoritative result locally. Offline it rejects with code = offline_write_not_supported — AppsDB writes are online-only.

The data blob is sent verbatim (no key-casing transformation), and all appsDb* responses are likewise returned verbatim — even for casing: 'camel' consumers — so bridge and REST results are identical.

Parameters

Parameter	Type
payload	AppsDbUpsertEntryPayload

Returns

Promise<AppsDbEntry>

Example

const entry = await api.appsDbUpsertEntry({ type: 'favorite', user_id: 1, data: { file_id: 'abc' } })

assignCanvasTheme()

assignCanvasTheme(payload): Promise<{ canvas_id: string; theme_id: string; }>

Parameters

Parameter	Type
payload	{ canvas_id: string; theme_id: string; }
payload.canvas_id	string
payload.theme_id	string

Returns

Promise<{ canvas_id: string; theme_id: string; }>

close()

close(): Promise<any>

Returns

Promise<any>

createCanvas()

createCanvas(payload): Promise<CanvasRetrieve>

Parameters

Parameter	Type
payload	Omit<CanvasCreateRequest, "instance_id">

Returns

Promise<CanvasRetrieve>

createFile()

createFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	Omit<AllFileCreateRequest, "instance_id">

Returns

Promise<FileRetrieve>

createFolder()

createFolder(payload): Promise<FolderRetrieve>

Creates a new folder.

Parameters

Parameter	Type	Description
payload	Omit<FolderCreateRequest, "instance_id">	The folder creation request payload, excluding the instance_id.

Returns

Promise<FolderRetrieve>

A promise that resolves to the created folder.

crmCreate()

crmCreate(payload): Promise<any>

Creates new records in CRM (Web only). Uses Salesforce REST API to create records.

Parameters

Parameter	Type	Description
payload	CRMCreatePayload	The create payload containing sobject type and records.

Returns

Promise<any>

• Promise resolving with the result of the create operation.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to create CRM records.
api.crmCreate({
  sobject: 'Order__c',
  records: [
    { Account__c: '001xx000003DGbQAAW', Order_Date__c: '2024-01-15' },
    { Account__c: '001xx000003DGbRABW', Order_Date__c: '2024-01-16' }
  ]
})

crmDescribe()

crmDescribe(payload): Promise<any>

Retrieves metadata/describe for a CRM object (Web only). Uses Salesforce REST API to fetch object metadata including fields and picklist values.

Parameters

Parameter	Type	Description
payload	CRMDescribePayload	The describe payload containing the sobject name.

Returns

Promise<any>

• Promise resolving with the object metadata including fields and picklist values.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to get CRM object metadata.
api.crmDescribe({ sobject: 'Account' })
  .then(metadata => {
    // Access fields
    console.log(metadata.fields)
    // Access picklist values for a specific field
    const industryField = metadata.fields.find(f => f.name === 'Industry')
    console.log(industryField.picklistValues)
  })

crmLayout()

crmLayout(payload): Promise<any>

Retrieves layout information for a CRM object (Web only). Uses Salesforce REST API to fetch object layout including sections, fields arrangement, and form factors.

Parameters

Parameter	Type	Description
payload	CRMLayoutPayload	The layout payload containing the sobject name and optional layout parameters.

Returns

Promise<any>

• Promise resolving with the object layout information.

Throws

• Throws an error if the payload is invalid.

Examples

// Web only method to get CRM object layout.
api.crmLayout({ sobject: 'Account' })
  .then(layout => {
    // Access layout sections
    console.log(layout.editLayoutSections)
  })

// Get layout with specific form factor, mode, and record type.
api.crmLayout({
  sobject: 'Account',
  form_factor: 'Large',
  mode: 'Edit',
  record_type_id: '012xx0000004ABC'
})

crmQuery()

crmQuery(payload): Promise<any>

Parameters

Parameter	Type
payload	CRMQueryPayload

Returns

Promise<any>

crmQueryAdaptive()

crmQueryAdaptive(payload): Promise<any>

Executes a CRM query with automatic iOS/SmartStore adaptation.

On iOS devices with the 'sfdc_offline_enabled' LaunchDarkly flag enabled, this function automatically converts SOQL queries to SmartStore Smart SQL format and uses the local SmartStore for offline data access. On other platforms or when the flag is disabled, it uses the standard CRM query API.

Parameters

Parameter	Type	Description
payload	CRMQueryPayload	The query payload containing the SOQL query string.

Returns

Promise<any>

• Promise resolving with query results.

Example

// Works on all platforms - automatically adapts for iOS with sfdc_offline_enabled LD flag
const result = await crmQueryAdaptive({ query: 'SELECT Id, Name FROM Account WHERE Active = true' })

crmSmartDeleteObjects()

crmSmartDeleteObjects(payload): Promise<any>

Deletes CRM objects from local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to delete records. Each object in the payload specifies a table name and an array of IDs to delete.

Parameters

Parameter	Type	Description
payload	CRMSmartDeleteObjectsPayload	The delete payload containing an array of CRMDeleteObject items.

Returns

Promise<any>

• Promise resolving with the result of the delete operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to delete CRM objects.
api.crmSmartDeleteObjects({
  objects: [
    {
      table_name: 'Account',
      ids: ['001xx000003DGbQAAW', '001xx000003DGbRABW']
    },
    {
      table_name: 'Contact',
      ids: ['003xx000004TmiQAAS']
    }
  ]
})

crmSmartObjectLayout()

crmSmartObjectLayout(payload): Promise<any>

Retrieves layout information for a CRM smart object (iOS only). Fetches object layout metadata from the Salesforce Mobile SDK cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectLayoutPayload	The payload containing the object name and optional layout parameters.

Returns

Promise<any>

• Promise resolving with the object layout metadata.

Throws

• Throws an error if the object name is not provided.

Examples

// iOS only method to retrieve CRM object layout.
api.crmSmartObjectLayout({ object: 'Account' })

// Get layout with specific form factor and mode.
api.crmSmartObjectLayout({ object: 'Account', form_factor: 'Large', mode: 'Edit' })

crmSmartObjectMetadata()

crmSmartObjectMetadata(payload): Promise<any>

Retrieves metadata for a CRM smart object (iOS only). Fetches object metadata from the Salesforce Mobile SDK cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectMetadataPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the object metadata.

Throws

• Throws an error if the object name is not provided.

Example

// iOS only method to retrieve CRM object metadata.
api.crmSmartObjectMetadata({ object: 'Account' })

crmSmartObjectValidationRules()

crmSmartObjectValidationRules(payload): Promise<any>

Retrieves validation rules for a CRM smart object (iOS only). This method fetches the validation rules configured for a specific CRM object type from the local SmartStore cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectValidationRulesPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the validation rules for the specified object.

Examples

// iOS only method to get validation rules for an Account object.
api.crmSmartObjectValidationRules({ object: 'Account' })

// Get validation rules for a Contact object.
api.crmSmartObjectValidationRules({ object: 'Contact' })

crmSmartQuery()

crmSmartQuery(payload): Promise<any[]>

Executes a SmartStore query against local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore query syntax. Validates that the query uses SmartStore syntax before execution.

Parameters

Parameter	Type	Description
payload	CRMQueryPayload	The query payload containing the SmartStore query string.

Returns

Promise<any[]>

• Promise resolving with an array of query results from SmartStore.

Throws

• Throws an error if the query is not a valid SmartStore query.

Example

// iOS only method to execute a SmartStore query.
api.crmSmartQuery({ query: 'SELECT {Account:Id}, {Account:Name} FROM {Account} ORDER BY {Account:Name} LIMIT 10' })

crmSmartUpsertObjects()

crmSmartUpsertObjects(payload): Promise<any>

Upserts CRM objects into local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to insert or update records. Each object in the payload specifies a table name, the objects to upsert, and an optional external ID path.

Important: Always provide external_id_path when performing updates to ensure records are matched correctly. Without it, the operation may create duplicate records instead of updating existing ones.

Note: When creating new records, you must provide an explicit identifier field (e.g., Id) in each record object passed from the frontend. The backend does not auto-generate IDs.

Parameters

Parameter	Type	Description
payload	UpsertCRMObjectsPayload	The upsert payload containing an array of UpsertCRMObject items.

Returns

Promise<any>

• Promise resolving with the result of the upsert operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to upsert CRM objects.

// Updating existing records - always include external_id_path
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [{ Id: '001xx000003DGbQAAW', Name: 'Acme Corp Updated' }],
      external_id_path: 'Id' // Required for updates to match existing records
    }
  ]
})

// Creating new records - explicit ID required in each record
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [
        { Id: '001xx000003NEW001', Name: 'New Company' }, // Explicit ID required
        { Id: '001xx000003NEW002', Name: 'Another Company' }
      ]
    }
  ]
})

crmUpsert()

crmUpsert(payload): Promise<any>

Upserts records in CRM (Web only). Uses Salesforce REST API to insert or update records based on external ID. If a record with matching external ID exists, it will be updated; otherwise, a new record is created.

Parameters

Parameter	Type	Description
payload	CRMUpsertPayload	The upsert payload containing sobject type, records, and external ID field.

Returns

Promise<any>

• Promise resolving with the result of the upsert operation.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to upsert CRM records.
api.crmUpsert({
  sobject: 'Order__c',
  records: [
    { External_Id__c: 'ORD-001', Account__c: '001xx000003DGbQAAW', Status__c: 'Submitted' },
    { External_Id__c: 'ORD-002', Account__c: '001xx000003DGbRABW', Status__c: 'Draft' }
  ],
  external_id_field: 'External_Id__c'
})

deleteCanvas()

deleteCanvas(payload): Promise<CanvasRetrieve>

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<CanvasRetrieve>

deleteFile()

deleteFile(payload): Promise<string>

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<string>

deleteFolder()

deleteFolder(payload): Promise<void>

Deletes a folder.

Parameters

Parameter	Type	Description
payload	{ folder_id: string; }	An object containing the ID of the folder to delete.
payload.folder_id	string	The ID of the folder to delete.

Returns

Promise<void>

A promise that resolves when the folder is deleted.

deleteLocalFile()

deleteLocalFile(payload): Promise<void>

Deletes a local file on iOS devices from Pitcher Folders.

Parameters

Parameter	Type
payload	{ url: string; }
payload.url	string

Returns

Promise<void>

Example

// iOS only method to delete a local file.
api.deleteLocalFile({ url: 'file:///var/mobile/Containers/Data/Application/x/Documents/Pitcher%20Folders/ARPhotocapture/x.png' })

downloadFile()

downloadFile(payload): Promise<null>

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<null>

fetchDocumentInfo()

fetchDocumentInfo(payload): Promise<{[key: string]: unknown; pageCount: number; }>

Parameters

Parameter	Type
payload	{ fileId: string; }
payload.fileId	string

Returns

Promise<{[key: string]: unknown; pageCount: number; }>

Deprecated

• not used anymore

getAppConfig()

getAppConfig(payload?): Promise<Record<string, any>>

Parameters

Parameter	Type
payload?	{ app_name?: string; }
payload.app_name?	string

Returns

Promise<Record<string, any>>

getCanvas()

getCanvas(payload): Promise<CanvasRetrieve>

Fetches a single canvas by ID.

Pass lazy_sections: true to request the opt-in lazy "shell": when the org/instance lazy_load_sections setting is also on, the response returns ordered section_ids instead of the heavy inline sections, and you hydrate section bodies on demand via getSectionsByIds. With the setting off (or the param omitted) the response is the legacy fully-expanded canvas.

Parameters

Parameter	Type	Description
payload	{ fields?: string; id: string; lazy_sections?: boolean; skip_error_toast?: boolean; }	-
payload.fields?	string	-
payload.id	string	-
payload.lazy_sections?	boolean	-
payload.skip_error_toast?	boolean	Suppress the host's error toast for best-effort reads (e.g. download-completion polling).

Returns

Promise<CanvasRetrieve>

getCanvases()

getCanvases(payload): Promise<PaginatedData<CanvasRetrieve>>

Fetches a list of canvases to use in your app.

Parameters

Parameter	Type
payload	GetCanvasesParams & object

Returns

Promise<PaginatedData<CanvasRetrieve>>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
api.getCanvases({
  search: 'my search query',
  ordering: '-created_at',
  filters: {
    metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
    metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
  },
 fields: 'id,name,metadata',
})

getCanvasRecommendedFiles()

getCanvasRecommendedFiles(payload): Promise<CanvasRecommendedFiles>

Parameters

Parameter	Type
payload	{ canvas_id: string; match?: ("metadata" | "tags")[]; }
payload.canvas_id	string
payload.match?	("metadata" | "tags")[]

Returns

Promise<CanvasRecommendedFiles>

getCanvasTheme()

getCanvasTheme(payload): Promise<CanvasThemeRetrieve | null>

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<CanvasThemeRetrieve | null>

getCoreFolders()

getCoreFolders(payload): Promise<CoreFolderContentsRetrieve>

Parameters

Parameter	Type
payload	{ entity: CoreFolderEntityType; instance_id: string; parent_id?: string | null; }
payload.entity	CoreFolderEntityType
payload.instance_id	string
payload.parent_id?	string | null

Returns

Promise<CoreFolderContentsRetrieve>

getEnv()

getEnv(): Promise<PitcherEnv>

Fetches the necessary info for the app to know where it is embedded.

It contains information about:

• user
• instance
• organization
• security token to query Pitcher REST API
• Salesforce connection information (if connected) including security token to query Salesforce REST API
• Auth0 token information

Returns

Promise<PitcherEnv>

Example

const env = usePitcherApi().getEnv().then((env) => {
  console.log(env.pitcher.user.name)
})

getFile()

getFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	{ file_id?: string; id?: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRetrieve>

getFileRevisionData()

getFileRevisionData(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	{ file_id: string; revision_id: string; }
payload.file_id	string
payload.revision_id	string

Returns

Promise<FileRetrieve>

getFileRevisions()

getFileRevisions(payload): Promise<FileRevision[]>

Parameters

Parameter	Type
payload	{ file_id?: string; id?: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRevision[]>

getFiles()

getFiles(payload): Promise<PaginatedFileList>

Parameters

Parameter	Type
payload	Partial<Omit<File, "type">> & object & object

Returns

Promise<PaginatedFileList>

getFolder()

getFolder(payload?): Promise<FolderRetrieve>

Retrieves a folder by its ID.

Parameters

Parameter	Type	Description
payload	{ id: string; }	An object containing the folder ID.
payload.id	string	The ID of the folder to retrieve. Defaults to 'root'.

Returns

Promise<FolderRetrieve>

A promise that resolves to the retrieved folder.

getFolders()

getFolders(payload): Promise<PaginatedFolderList>

Retrieves a list of folders.

Parameters

Parameter	Type	Description
payload	FolderListRequest	The payload containing the search, ordering, filters, fields, name, page, and page_size.

Returns

Promise<PaginatedFolderList>

A promise that resolves to the list of folders.

getInstanceMetadataTemplates()

getInstanceMetadataTemplates(payload?): Promise<PaginatedMetadataTemplateList>

Parameters

Parameter	Type
payload?	GetInstanceMetadataTemplatesPayload

Returns

Promise<PaginatedMetadataTemplateList>

getSectionsByIds()

getSectionsByIds(payload): Promise<{ sections: CanvasSection[]; }>

Batch-hydrate section bodies for a canvas fetched as a lazy shell.

Companion to getCanvas({ lazy_sections: true }): pass the canvas ID and a slice of its section_ids (≤100 per call) and receive the full section bodies, serialized identically to a normal canvas retrieve's inline sections. Only sections actually referenced by the canvas are returned.

Pass the SAME exclude_drafts / include_expired_files / include_pending_files the shell was fetched with so hydration filters identically to the shell that advertised the IDs — otherwise admin decks (fetched with exclude_drafts:false, expired/pending on) list draft/expired sections the batch would silently drop, leaving them blank. Omit them to get the rep defaults (drafts excluded, expired/pending off). include_expired_files/include_pending_files are server-side role-gated (admin/editor only), matching the inline retrieve.

Parameters

Parameter	Type
payload	{ canvas_id: string; exclude_drafts?: boolean; include_expired_files?: boolean; include_pending_files?: boolean; section_ids: string[]; }
payload.canvas_id	string
payload.exclude_drafts?	boolean
payload.include_expired_files?	boolean
payload.include_pending_files?	boolean
payload.section_ids	string[]

Returns

Promise<{ sections: CanvasSection[]; }>

Example

const { sections } = await api.getSectionsByIds({
  canvas_id: '01HH4RCBH631K4JDHWAQB0RPR6',
  section_ids: ['01SEC...', '02SEC...'],
})

getThemes()

getThemes(payload): Promise<CanvasThemeRetrieve[]>

Parameters

Parameter	Type
payload	Partial<CanvasThemeRetrieve>

Returns

Promise<CanvasThemeRetrieve[]>

getUsers()

getUsers(payload?): Promise<PaginatedData<User>>

Parameters

Parameter	Type
payload?	GetUsersParams

Returns

Promise<PaginatedData<User>>

isOffline()

isOffline(): Promise<boolean>

Returns

Promise<boolean>

moveFolderItems()

moveFolderItems(payload): Promise<FolderRetrieve>

Moves items (files or folders) to a target folder.

Parameters

Parameter	Type	Description
payload	{ items: object[]; target_folder_id: string; }	The payload containing the target folder ID and items to move.
payload.items	object[]	An array of items to move, each with an ID and type.
payload.target_folder_id	string	The ID of the target folder.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated target folder.

notify()

notify(payload): Promise<void>

Parameters

Parameter	Type
payload	NotificationPayload

Returns

Promise<void>

open()

open(payload?): Promise<string>

Open a file in the CatalogIQ instance.

Parameters

Parameter	Type
payload	OpenRequestPayload

Returns

Promise<string>

openExternalUrl()

openExternalUrl(payload): Promise<void>

Open external URL in a new tab. Works on both web and mobile.

Parameters

Parameter	Type
payload	OpenExternalUrlRequestPayload

Returns

Promise<void>

openWebViewAlwaysOnTop()

openWebViewAlwaysOnTop(payload): Promise<void>

Parameters

Parameter	Type
payload	OpenWebViewAlwaysOnTop

Returns

Promise<void>

patchCoreFolder()

patchCoreFolder(id, payload): Promise<CoreFolderContentsRetrieve>

Parameters

Parameter	Type
id	string
payload	Partial<CoreFolderRetrieve>

Returns

Promise<CoreFolderContentsRetrieve>

piaSearchAnswer()

piaSearchAnswer(payload): Promise<PiaSearchAnswerResult>

Answer a rep's natural-language question over the instance's content — the ONE high-level PIA Search call (PIT-6863). Routing follows the pia_search_config flag mode (see resolvePiaSearchMode):

• on_device on iOS with an available local model → aiComplete over the caller-assembled context_text (the Hub has the file metadata client-side). Unavailable/downloading models fall through to online.
• online (or any on-device fallback) → POST to the next-core pia-prepare/pia-search Bedrock route, which assembles its own candidate context server-side.
• off → rejects.

Parameters

Parameter	Type	Description
payload	PiaSearchAnswerPayload	The question + optional context/narrowing.

Returns

Promise<PiaSearchAnswerResult>

• Unified answer with the serving source.

Example

const result = await api.piaSearchAnswer({ query: 'What is our pricing for oncology?' })
console.log(result.answer, result.cited_file_ids, result.source)

postJsonWithTimeout()

postJsonWithTimeout<T>(url, body, accessToken, timeoutMs, label): Promise<T>

POST JSON to a next-core route with a hard deadline, returning the parsed body. The shared scaffold behind the SDK's online AI calls (piaSearchAnswer, weeklyFocusRank).

Bounds the WHOLE request including the body read: fetch() resolves on headers alone, so reading .json() INSIDE the timed window (and letting the abort cancel that read too — hence clearTimeout in finally) is what stops a response that stalls mid-body from hanging unbounded. label names the route in BOTH the non-2xx error (<label> <status>) and the timeout error, so each caller keeps its exact error strings.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
url	string
body	unknown
accessToken	string
timeoutMs	number
label	string

Returns

Promise<T>

query()

query(payload): Promise<any>

Parameters

Parameter	Type
payload	QueryPayload

Returns

Promise<any>

refreshAccessToken()

refreshAccessToken(): any

Returns

any

refreshServiceToken()

refreshServiceToken(payload?): Promise<RefreshServiceTokenResponse>

Ask for a refreshed Salesforce token. In case the token hasn't expired yet, this method will return the same token as the current one found in the (getEnv)[#getenv] result.

Parameters

Parameter	Type
payload?	RefreshServiceTokenRequest

Returns

Promise<RefreshServiceTokenResponse>

Promise resolving to an object containing the token

renderPageAsImage()

renderPageAsImage(payload): Promise<ArrayBuffer>

Renders a page from a file together with annotations.

Parameters

Parameter	Type	Description
payload	{ documentId?: string; fileId: string; pageIndex: number; params: { width: number; } | { height: number; }; }	-
payload.documentId?	string	The ID of the document to render (optional). If not provided the fileId will be used.
payload.fileId	string	The ID of the file to render. Used when the documentId is not available.
payload.pageIndex	number	The index of the page to render.
payload.params	{ width: number; } | { height: number; }	The parameters to use for rendering the page.

Returns

Promise<ArrayBuffer>

A promise that resolves with the image as an ArrayBuffer.

Example

api.renderPageAsImage({
  fileId: '123456',
  documentId: '654321',
  pageIndex: 0,
  params: { width: 1920 },
})

search()

search(payload): Promise<any>

Parameters

Parameter	Type
payload	{ includeExpired?: boolean; query: string; }
payload.includeExpired?	boolean
payload.query	string

Returns

Promise<any>

selectDeviceFile()

selectDeviceFile(): Promise<DeviceFile>

Dispatches iOS native file selector and returns the selected file.

Returns

Promise<DeviceFile>

Example

// iOS only method to select a file from the device.
api.selectDeviceFile()

share()

share(payload): Promise<ShareResponse>

Dispatch iOS sharing dialog.

Parameters

Parameter	Type
payload	SharePayload

Returns

Promise<ShareResponse>

Example

api.share({text: "example text", subject: "example subject"})

shareCanvas()

shareCanvas(payload): Promise<SharedLink>

Get (or create) the shared link for a canvas.

brand_id (PIT-7682, optional) names an entry in the instance's shared_link_brands setting and only takes effect when the link is created. Omit it and the server uses the brand the rep last used on that instance, falling back to the instance default — the behaviour quick-share, bulk-share and API-created links get. A host that does not forward it (the iOS bridge today) therefore still produces a correctly branded link, just without the rep's per-share choice.

Parameters

Parameter	Type
payload	{ brand_id?: string; id: string; }
payload.brand_id?	string
payload.id	string

Returns

Promise<SharedLink>

showPeerSession()

showPeerSession(payload): Promise<void>

Show peer session dialog with button coordinates, for local peer sharing feature.

Parameters

Parameter	Type
payload	ShowPeerSessionRequestPayload

Returns

Promise<void>

Example

api.showPeerSession({x: 100, y: 200})

showSyncbox()

showSyncbox(payload): Promise<void>

Parameters

Parameter	Type
payload	ShowSyncboxRequestPayload

Returns

Promise<void>

slideSearch()

slideSearch(payload): Promise<SlideSearchResult>

Rank the slides of one wizard template configuration for a query (PIT-9090) — the online slide_search AITask, for vanilla and headless consumers that can load this SDK. (The React completion wizard calls the route directly.)

The caller passes its own visible realm (visible_group_names + visible_slide_refs); the server narrows the configuration to it, drops whatever the caller's ACL hides, and reranks with one model call. Results are ordered best first. Rejects on a non-2xx (slide_search <status>) or after 30 s.

Parameters

Parameter	Type	Description
payload	SlideSearchPayload	The configuration, the visible realm and the query.

Returns

Promise<SlideSearchResult>

• Ranked slides, the mode used and the realm size.

Example

const { results } = await api.slideSearch({
  canvas_id: deckId,
  section_list_id: 'node_abc',
  visible_group_names: ['Efficacy', 'Safety'],
  visible_slide_refs: ['01K…', '01F…_page_3'],
  query: 'which slides cover renal dosing?',
})

sttAvailability()

sttAvailability(): Promise<SttAvailabilityResult>

Check whether dictation can be offered — a side-effect-free capability probe to gate a mic button. Does NOT prompt for the microphone or download a model. Answered by the native bridge on iOS and the Impact host on web.

Returns

Promise<SttAvailabilityResult>

{ available, engine, reason? } — available is true only when the feature is enabled AND an engine can run; engine is what would answer sttStart ("webspeech" sends audio off-device); reason is "disabled" or "unsupported" when not available.

Example

const { available, engine } = await api.sttAvailability()
if (available) showMicButton({ warnCloud: engine === 'webspeech' })

sttErrorCode()

sttErrorCode(error): SttErrorCode | undefined

Extract the SttErrorCode from a rejected sttStart / sttStop, normalizing across hosts: the iOS bridge rejection (error_code / errorCode) and Impact web's { reason } / error message string. Returns undefined if no known code is present.

Parameters

Parameter	Type
error	unknown

Returns

SttErrorCode | undefined

Example

try { await api.sttStart({ session_id }) } catch (err) {
  if (api.sttErrorCode(err) === 'STT_BUSY') showMicInUseHint()
}

sttStart()

sttStart(payload): Promise<void>

Parameters

Parameter	Type
payload	SttStartPayload

Returns

Promise<void>

sttStop()

sttStop(payload): Promise<SttStopResult>

Finalize a dictation session. Resolves with the final full transcript; rejects with STT_NOT_RECORDING if the session isn't active.

Parameters

Parameter	Type	Description
payload	SttStopPayload	-

Returns

Promise<SttStopResult>

The final { transcript }.

Example

const { transcript } = await api.sttStop({ session_id: 'notes-1' })

sttWarmup()

sttWarmup(): Promise<void>

Pre-load the on-device dictation model so a later sttStart resolves instantly (and the mic-permission prompt appears immediately instead of after a download). Web only — on iOS the native side manages its own model lifecycle, so the bridge has no stt.warmup type and calling it there rejects requestTypeDoesNotExists.

Fire-and-forget: don't block your UI on it and ignore rejections. It is idempotent (repeated / concurrent calls collapse to a single download) and a no-op when the feature is disabled or the engine has nothing to warm (Web Speech fallback). Call it right after sttAvailability reports available with engine === 'whisper'.

Returns

Promise<void>

Resolves once the model is ready (or immediately when there's nothing to warm).

Example

const { available, engine } = await api.sttAvailability()
if (available) {
  showMicButton()
  if (engine === 'whisper') api.sttWarmup().catch(() => {}) // background, non-blocking
}

submitUserFeedback()

submitUserFeedback(payload): Promise<any>

Submit user feedback

Parameters

Parameter	Type
payload	SubmitUserFeedbackPayload

Returns

Promise<any>

toast()

toast(payload): Promise<void>

Parameters

Parameter	Type
payload	{ message: string; type: string; }
payload.message	string
payload.type	string

Returns

Promise<void>

track()

track(payload): Promise<any>

Parameters

Parameter	Type
payload	{ event_name: string; payload: any; }
payload.event_name	string
payload.payload	any

Returns

Promise<any>

triggerNonFilesSync()

triggerNonFilesSync(): Promise<void>

Dispatches iOS only sync method for non-files.

Returns

Promise<void>

Example

// iOS only method to sync non-files from the server.
api.triggerNonFilesSync()

ttsErrorCode()

ttsErrorCode(error): TtsErrorCode | undefined

Extract the TtsErrorCode from a rejected ttsSpeak, normalizing across hosts: the iOS bridge APIError (code / error_code / errorCode) and a host { reason } / error message string. Returns undefined if no known code is present.

Parameters

Parameter	Type
error	unknown

Returns

TtsErrorCode | undefined

Example

try { await api.ttsSpeak({ text, language }) } catch (err) {
  if (api.ttsErrorCode(err) === 'TTS_VOICE_UNAVAILABLE') promptVoiceDownload()
}

ttsSpeak()

ttsSpeak(payload): Promise<TtsSpeakResult>

Speak text on the device speaker. Resolves when the utterance FINISHES; rejects with a TtsErrorCode.

Parameters

Parameter	Type	Description
payload	TtsSpeakPayload	-

Returns

Promise<TtsSpeakResult>

{ completed } — true if it finished naturally, false if stopped or replaced by a newer ttsSpeak.

Example

const { completed } = await api.ttsSpeak({ text: 'Meeting summary saved.', language: 'en-US' })

ttsStop()

ttsStop(): Promise<void>

Stop any in-flight speech. The in-flight ttsSpeak resolves with { completed: false }.

Returns

Promise<void>

Example

await api.ttsStop()

ttsWarmup()

ttsWarmup(): Promise<void>

Pre-load the on-device Supertonic model (web only) WITHOUT speaking, so a later ttsSpeak answers instantly instead of paying the first-use model download/init cost. Optional — call it when the app knows it will speak soon (e.g. once an AI response starts generating). A no-op on hosts with nothing to warm (iOS, or web with the on-device model disabled/ unsupported — Web Speech needs no warmup); the bridge has no tts.warmup type, so calling it there rejects with requestTypeDoesNotExists — catch and ignore, mirroring its STT counterpart sttWarmup.

Returns

Promise<void>

Example

api.ttsWarmup().catch(() => {}) // background, non-blocking

unassignCanvasTheme()

unassignCanvasTheme(payload): Promise<void>

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<void>

updateCanvas()

updateCanvas(payload): Promise<CanvasRetrieve>

Updates a canvas by ID

Parameters

Parameter	Type
payload	PatchedCanvasUpdateRequest & object

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  PitcherAPI.updateCanvas({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    fields: 'id,name',
    name: 'To 3!',
  }).then((res) => {
    console.log(res)  // logs: { id: '01HH4RCBH631K4JDHWAQB0RPR6', name: 'To 3!' }
  })
})

updateCanvasIndicators()

updateCanvasIndicators(payload): Promise<CanvasRetrieve>

Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.

Indicators can also be updated using updateCanvas API but in this case passed object fully replaces existing indicators.

Parameters

Parameter	Type
payload	{ id: string; indicators: Record<string, CanvasIndicator>; instance_id?: string; }
payload.id	string
payload.indicators	Record<string, CanvasIndicator>
payload.instance_id?	string

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  PitcherAPI.updateCanvasIndicators({
    id: '01J9XT0WVXRTETF4CQZP42CPZP',
    indicators: {
      existing: { type: 'info', label: 'new label' }, // will be overriden
      new: { type: 'info', label: 'INFO' }, // will be added
      removeExisting: null // will be set to null and ignored, it is the same as removal
   }
   }).then((res) => {
    console.log(res)  // entire canvas object, including indicators field
  })
})

updateFile()

updateFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	FileUpdateRequest & object

Returns

Promise<FileRetrieve>

updateFolder()

updateFolder(payload): Promise<FolderRetrieve>

Updates an existing folder.

Parameters

Parameter	Type	Description
payload	UpdateFolderPayload	The folder update payload, including the folder ID and update data.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated folder.

updateMyUser()

updateMyUser(payload): Promise<User>

Parameters

Parameter	Type
payload	UpdateEnvParams

Returns

Promise<User>

weeklyFocusRank()

weeklyFocusRank(payload): Promise<WeeklyFocusRankResult>

Rank the rep's next-7-days meetings by how much preparation they need — the ONE high-level Weekly Focus call (PIT-7257), the weekly_focus AITask.

The on-device path runs the prompt, window, parser and ordinal resolver from @lib/ai-tasks/weekly-focus; the online route runs next-core's parallel copy of the same logic. The two are kept in lockstep by matching test suites, not a shared import (see that module's header / ADR-002), so the two paths produce the same shape:

• iOS with an available local model → aiComplete over the caller-supplied meetings + account context. Unavailable models / unusable output fall through.
• Otherwise → POST to the next-core Bedrock route.

The model picks meetings by ORDINAL and the resolver maps them back to event_ids, dropping out-of-range ones — so a returned id can only come from the meetings passed in.

This does NOT cache, lock or prewarm: an app that generates on a schedule (as pre-call-brief does) owns those mechanics and calls this underneath.

Parameters

Parameter	Type	Description
payload	WeeklyFocusRankPayload	The meetings + optional account context.

Returns

Promise<WeeklyFocusRankResult>

• Ranking with the serving source.

Example

const focus = await api.weeklyFocusRank({ meetings, context })
console.log(focus.hero, focus.top, focus.collapsed_count)

---

Type Literal

{ on: (type, handler) => Promise<() => void>; toast: (payload) => Promise<void>; captureAppError: Promise<void>; close: Promise<void>; createCanvas: Promise<CanvasRetrieve>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getEnv: Promise<AdminEnv>; getFile: Promise<File>; getFiles: Promise<PaginatedFileList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getUsers: Promise<PaginatedData<User>>; open: Promise<void>; openCanvasOverlay: Promise<void>; openCollectionPlayerOverlay: Promise<void>; selectAgendaContent: Promise<AdminSelectAgendaResponse>; selectCanvases: Promise<AdminSelectCanvasesResponse>; selectCollectionContent: Promise<AdminSelectCollectionPlayerResponse>; selectContent: Promise<AdminSelectContentResponse>; updateCanvas: Promise<CanvasRetrieve>; }

on

on: (type, handler) => Promise<() => void>

Subscribe to a given event type by its key.

Parameters

Parameter	Type	Description
type	"admin_env_changed"	The event type/key to subscribe to.
handler	(data) => Promise<void>	The handler function to call when the event is emitted.

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

toast

toast: (payload) => Promise<void>

Show a toast message to the user. Compatible with the UI API version of this method.

Parameters

Parameter	Type
payload	AdminToastRequest

Returns

Promise<void>

Example

useAdmin().toast({ type: 'info', message: 'Hello, world!' })

captureAppError()

captureAppError(payload): Promise<void>

Send an app error to Pitcher sentry instance.

Sentry files it under one issue per app + message and tags it app_name, so send your app's name as app_name (app is also read) and a stable message, and keep ids and other varying values in other fields. Without a name the error groups under unknown with every other unnamed app's. The whole payload is attached to the event.

Parameters

Parameter	Type	Description
payload	AdminCaptureAppErrorRequest	error object to send to Pitcher sentry instance

Returns

Promise<void>

Example

try {
  throw new Error('This is an error')
} catch (error) {
  useAdmin().captureAppError({
    app_name: 'my-admin-app',
    message: 'Failed to save settings',
    stack: error instanceof Error ? error.stack : String(error),
  })
}

close()

close(): Promise<void>

Closes the already open file that was opened via api or by the user.

Returns

Promise<void>

Example

adminApi.close()

createCanvas()

createCanvas(payload): Promise<CanvasRetrieve>

Creates a new canvas.

Parameters

Parameter	Type
payload	CanvasCreateRequest

Returns

Promise<CanvasRetrieve>

Example

adminApi.createCanvas({
   name: 'my new canvas';
 })

getAppConfig()

getAppConfig(payload): Promise<Record<string, any>>

Get the metadata object of an app with a given name.

Parameters

Parameter	Type	Description
payload	{ app_name: string; }	The payload object.
payload.app_name	string	name value from app.json of the app you want to get the metadata of.

Returns

Promise<Record<string, any>>

Example

useAdmin().getAppConfig({ app_name: 'my-app' })

getCanvas()

getCanvas(payload): Promise<CanvasRetrieve>

Fetches a canvas by id with the defined fields or all of them.

Parameters

Parameter	Type
payload	{ fields?: string; id: string; }
payload.fields?	string
payload.id	string

Returns

Promise<CanvasRetrieve>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
adminApi.getCanvas({
 fields: 'id,name,metadata',
})

getCanvases()

getCanvases(payload): Promise<PaginatedData<CanvasRetrieve>>

Fetches a list of canvases to use in your app.

Parameters

Parameter	Type
payload	GetCanvasesParams & object

Returns

Promise<PaginatedData<CanvasRetrieve>>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
adminApi.getCanvases({
  search: 'my search query',
  ordering: '-created_at',
  filters: {
    metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
    metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
  },
 fields: 'id,name,metadata',
})

getEnv()

getEnv(): Promise<AdminEnv>

Fetches the necessary info for the app to know where it is embedded.

Check out usePitcherApi().getEnv() for more information.

Returns

Promise<AdminEnv>

Example

adminApi.getEnv()

getFile()

getFile(payload): Promise<File>

Fetches a file by ID.

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<File>

Example

adminApi.getFile({ id: 'my-file-id' })

getFiles()

getFiles(payload): Promise<PaginatedFileList>

Lists available files.

Parameters

Parameter	Type
payload	Record<string, any>

Returns

Promise<PaginatedFileList>

Example

adminApi.getFiles()

getInstanceMetadataTemplates()

getInstanceMetadataTemplates(payload?): Promise<PaginatedMetadataTemplateList>

Fetches a list of metadata templates to use in your app. Instance is auto-injected by admin app if in instance scope.

Parameters

Parameter	Type
payload?	GetInstanceMetadataTemplatesPayload

Returns

Promise<PaginatedMetadataTemplateList>

Example

adminApi.getInstanceMetadataTemplates()

getUsers()

getUsers(payload?): Promise<PaginatedData<User>>

Fetches a list of users from the admin API.

Parameters

Parameter	Type	Description
payload?	GetUsersParams	Optional parameters for filtering users

Returns

Promise<PaginatedData<User>>

Promise resolving to a paginated list of users

Example

const adminApi = useAdmin()
const users = await adminApi.getUsers({ page_size: 100 })

open()

open(payload): Promise<void>

Opens a file by id.

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<void>

Example

adminApi.open({ id: 'my-file-id' })

openCanvasOverlay()

openCanvasOverlay(payload): Promise<void>

Opens a modal to view a canvas by ID.

onMounted(() => {
  adminApi.openCanvasOverlay({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    edit_mode: false,
    fullscreen: true,
  })
})

You can also specify a position for the canvas overlay:

adminApi.openCanvasOverlay({
  id: '01HH4RCBH631K4JDHWAQB0RPR6',
  position: {
    top: '10px',
    left: '20px',
    right: '20px',
    bottom: '10px'
  }
})

Parameters

Parameter	Type
payload	{ component_id?: string; edit_mode?: boolean; fullscreen?: boolean; id: string; position?: { bottom?: string | number; left?: string | number; right?: string | number; top?: string | number; }; section_id?: string; }
payload.component_id?	string
payload.edit_mode?	boolean
payload.fullscreen?	boolean
payload.id	string
payload.position?	{ bottom?: string | number; left?: string | number; right?: string | number; top?: string | number; }
payload.position.bottom?	string | number
payload.position.left?	string | number
payload.position.right?	string | number
payload.position.top?	string | number
payload.section_id?	string

Returns

Promise<void>

openCollectionPlayerOverlay()

openCollectionPlayerOverlay(payload): Promise<void>

Opens a modal to display collection player content.

Parameters

Parameter	Type
payload	AdminOpenCollectionPlayerOverlayRequest

Returns

Promise<void>

Example

adminApi.openCollectionPlayerOverlay({
  name: 'My Collection',
  groups: [
    {
      id: 'file-id-1',
      name: 'Group 1',
    },
    {
      id: 'group-2',
      name: 'Group 2',
      slides: [
        { file_id: 'file-id-2', slide_index: 0 },
        { file_id: 'file-id-3', slide_index: 1 },
      ],
    },
  ],
})

selectAgendaContent()

selectAgendaContent(payload?): Promise<AdminSelectAgendaResponse>

Opens the agenda selector modal to allow the user to select agenda content and handle the outcome.

const api = useApi() // or useAdmin() if you know that you 're in Admin context

adminApi.selectAgendaContent({
 // optional payload
 initial_agenda: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	AdminSelectAgendaRequest

Returns

Promise<AdminSelectAgendaResponse>

selectCanvases()

selectCanvases(payload?): Promise<AdminSelectCanvasesResponse>

Allows the user to select (and preselect) canvases from the instance.

This method allows you to prompt the user to select canvases from the CatalogIQ instance and use that canvas selection in your application.

Parameters

Parameter	Type	Description
payload	AdminSelectCanvasesRequest	optional payload to preselect specific canvases

Returns

Promise<AdminSelectCanvasesResponse>

Promise with the user action and selected canvases

Example

const api = useApi() // or useAdmin() if you know that you 're in Admin context
api
  .selectCanvases({
    allowed_types: ['canvas','canvas-template','section','section-template'] // default ['canvas']
    selections: [
      { id: "01HCZ623YYRFJQ0F7B69VWE510" },
      { id: "02HCZ623YYRFJQ0F7B69VWE510" },
    ], // default []
  })

selectCollectionContent()

selectCollectionContent(payload?): Promise<AdminSelectCollectionPlayerResponse>

Opens the collection player selector modal to allow the user to select collection player content and handle the outcome.

const api = useApi() // or useAdmin() if you know that you 're in Admin context

adminApi.selectCollectionContent({
 // optional payload
 initial_data: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	AdminSelectCollectionPlayerRequest

Returns

Promise<AdminSelectCollectionPlayerResponse>

selectContent()

selectContent(payload): Promise<AdminSelectContentResponse>

Opens a selector that allows you to select (and preselect) from your Pitcher uploaded content.

Parameters

Parameter	Type
payload	AdminSelectContentRequest

Returns

Promise<AdminSelectContentResponse>

Example

const api = useApi() // or useAdmin() if you know that you 're in Admin app context
api
  .select_content({
    selections: [
      { fileId: "01HCZ623YYRFJQ0F7B69VWE510", type: "file" },
      {
        fileId: "01HD3XGZ5FN90QJGK7CH8TBZDF",
        type: "page",
        pageIndex: 2,
      },
    ],
  })

updateCanvas()

updateCanvas(payload): Promise<CanvasRetrieve>

Updates a canvas by ID and returns the defined fields or all of them.

Parameters

Parameter	Type
payload	PatchedCanvasUpdateRequest & object

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  adminApi.updateCanvas({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    fields: 'id,name',
    name: 'To 3!',
  }).then((res) => {
    console.log(res)  // logs: { id: '01HH4RCBH631K4JDHWAQB0RPR6', name: 'To 3!' }
  })
})

---

Type Literal

{ API: LowLevelApi; broadcast: (event) => Promise<any>; broadcastToWebviews: (event) => Promise<any>; enterFullscreen: () => Promise<any>; exitFullscreen: () => Promise<any>; getRequestTypes: () => Promise<any>; impact: { API: LowLevelApi; broadcast: (event) => Promise<any>; broadcastToWebviews: (event) => Promise<any>; enterFullscreen: () => Promise<any>; exitFullscreen: () => Promise<any>; getRequestTypes: () => Promise<any>; isFullscreen: () => Promise<any>; logout: () => Promise<any>; off: (type, callback) => void; on: (type, callback) => void; quitInstance: () => Promise<any>; subscribe: () => Promise<any>; unsubscribe: () => Promise<any>; aiComplete: Promise<AICompleteResult>; aiGetCapabilities: Promise<AIRuntimeCapabilities>; appsDbDeleteEntry: Promise<void>; appsDbGetEntries: Promise<AppsDbEntriesResult>; appsDbPsql: Promise<AppsDbEntriesResult>; appsDbUpsertEntry: Promise<AppsDbEntry>; assignCanvasTheme: Promise<{ canvas_id: string; theme_id: string; }>; close: Promise<any>; createCanvas: Promise<CanvasRetrieve>; createFile: Promise<FileRetrieve>; createFolder: Promise<FolderRetrieve>; crmCreate: Promise<any>; crmDescribe: Promise<any>; crmLayout: Promise<any>; crmQuery: Promise<any>; crmQueryAdaptive: Promise<any>; crmSmartDeleteObjects: Promise<any>; crmSmartObjectLayout: Promise<any>; crmSmartObjectMetadata: Promise<any>; crmSmartObjectValidationRules: Promise<any>; crmSmartQuery: Promise<any[]>; crmSmartUpsertObjects: Promise<any>; crmUpsert: Promise<any>; deleteCanvas: Promise<CanvasRetrieve>; deleteFile: Promise<string>; deleteFolder: Promise<void>; deleteLocalFile: Promise<void>; downloadFile: Promise<null>; fetchDocumentInfo: Promise<{[key: string]: unknown; pageCount: number; }>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getCanvasRecommendedFiles: Promise<CanvasRecommendedFiles>; getCanvasTheme: Promise<CanvasThemeRetrieve | null>; getCoreFolders: Promise<CoreFolderContentsRetrieve>; getEnv: Promise<PitcherEnv>; getFile: Promise<FileRetrieve>; getFileRevisionData: Promise<FileRetrieve>; getFileRevisions: Promise<FileRevision[]>; getFiles: Promise<PaginatedFileList>; getFolder: Promise<FolderRetrieve>; getFolders: Promise<PaginatedFolderList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getSectionsByIds: Promise<{ sections: CanvasSection[]; }>; getThemes: Promise<CanvasThemeRetrieve[]>; getUsers: Promise<PaginatedData<User>>; isOffline: Promise<boolean>; moveFolderItems: Promise<FolderRetrieve>; notify: Promise<void>; open: Promise<string>; openExternalUrl: Promise<void>; openWebViewAlwaysOnTop: Promise<void>; patchCoreFolder: Promise<CoreFolderContentsRetrieve>; piaSearchAnswer: Promise<PiaSearchAnswerResult>; postJsonWithTimeout: Promise<T>; query: Promise<any>; refreshAccessToken: any; refreshServiceToken: Promise<RefreshServiceTokenResponse>; renderPageAsImage: Promise<ArrayBuffer>; search: Promise<any>; selectDeviceFile: Promise<DeviceFile>; share: Promise<ShareResponse>; shareCanvas: Promise<SharedLink>; showPeerSession: Promise<void>; showSyncbox: Promise<void>; slideSearch: Promise<SlideSearchResult>; sttAvailability: Promise<SttAvailabilityResult>; sttErrorCode: SttErrorCode | undefined; sttStart: Promise<void>; sttStop: Promise<SttStopResult>; sttWarmup: Promise<void>; submitUserFeedback: Promise<any>; toast: Promise<void>; track: Promise<any>; triggerNonFilesSync: Promise<void>; ttsErrorCode: TtsErrorCode | undefined; ttsSpeak: Promise<TtsSpeakResult>; ttsStop: Promise<void>; ttsWarmup: Promise<void>; unassignCanvasTheme: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateCanvasIndicators: Promise<CanvasRetrieve>; updateFile: Promise<FileRetrieve>; updateFolder: Promise<FolderRetrieve>; updateMyUser: Promise<User>; weeklyFocusRank: Promise<WeeklyFocusRankResult>; }; isFullscreen: () => Promise<any>; logout: () => Promise<any>; off: (type, callback) => void; on: <T>(type, handler) => Promise<() => void>; onAppSetData: (handler) => Promise<() => void>; onAppUpdateData: (handler) => Promise<() => void>; onCanvasUpdated: (handler) => Promise<() => void>; onMeetingCanceled: (handler) => Promise<() => void>; onSectionListUpdated: (handler) => Promise<() => void>; quitInstance: () => Promise<any>; subscribe: () => Promise<any>; ui: { on: <T>(type, handler) => Promise<() => void>; onAppSetData: (handler) => Promise<() => void>; onAppUpdateData: (handler) => Promise<() => void>; onCanvasUpdated: (handler) => Promise<() => void>; onMeetingCanceled: (handler) => Promise<() => void>; onSectionListUpdated: (handler) => Promise<() => void>; uiBroadcast: { }; appFullscreenChange: Promise<void>; appLoaded: Promise<void>; appResize: Promise<void>; cancelMeeting: Promise<void>; canvasNavigateNextPage: Promise<void>; canvasNavigatePage: Promise<void>; canvasNavigatePreviousPage: Promise<void>; captureAppError: Promise<void>; closeCanvasDrawer: Promise<void>; closeCanvasSectionExecution: Promise<void>; closeGlobalPopup: Promise<void>; completePostcall: Promise<void>; disablePostcallSubmit: Promise<void>; embeddableReady: Promise<void>; enablePostcallSubmit: Promise<void>; open: Promise<void>; openCanvasOverlay: Promise<void>; openCollectionPlayerOverlay: Promise<void>; openGlobalPopup: Promise<UiOpenGlobalPopupResponse>; openSharingSettings: Promise<UiOpenSharingSettingsResponse>; preselectSfdcMeetingId: Promise<UiPreselectSfdcMeetingIdResponse>; printCanvas: Promise<UiPrintCanvasResponse>; promptPia: Promise<UiPromptPiaResponse>; resumeMeeting: Promise<void>; selectAgendaContent: Promise<UiSelectAgendaResponse>; selectCanvases: Promise<UiSelectCanvasesResponse>; selectCollectionContent: Promise<UiSelectCollectionPlayerResponse>; selectContent: Promise<UiSelectContentResponse>; setPostcallStyle: Promise<void>; stopMeeting: Promise<void>; toast: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateLocation: Promise<any>; }; uiBroadcast: { }; unsubscribe: () => Promise<any>; aiComplete: Promise<AICompleteResult>; aiGetCapabilities: Promise<AIRuntimeCapabilities>; appFullscreenChange: Promise<void>; appLoaded: Promise<void>; appResize: Promise<void>; appsDbDeleteEntry: Promise<void>; appsDbGetEntries: Promise<AppsDbEntriesResult>; appsDbPsql: Promise<AppsDbEntriesResult>; appsDbUpsertEntry: Promise<AppsDbEntry>; assignCanvasTheme: Promise<{ canvas_id: string; theme_id: string; }>; cancelMeeting: Promise<void>; canvasNavigateNextPage: Promise<void>; canvasNavigatePage: Promise<void>; canvasNavigatePreviousPage: Promise<void>; captureAppError: Promise<void>; close: Promise<any>; closeCanvasDrawer: Promise<void>; closeCanvasSectionExecution: Promise<void>; closeGlobalPopup: Promise<void>; completePostcall: Promise<void>; createCanvas: Promise<CanvasRetrieve>; createFile: Promise<FileRetrieve>; createFolder: Promise<FolderRetrieve>; crmCreate: Promise<any>; crmDescribe: Promise<any>; crmLayout: Promise<any>; crmQuery: Promise<any>; crmQueryAdaptive: Promise<any>; crmSmartDeleteObjects: Promise<any>; crmSmartObjectLayout: Promise<any>; crmSmartObjectMetadata: Promise<any>; crmSmartObjectValidationRules: Promise<any>; crmSmartQuery: Promise<any[]>; crmSmartUpsertObjects: Promise<any>; crmUpsert: Promise<any>; deleteCanvas: Promise<CanvasRetrieve>; deleteFile: Promise<string>; deleteFolder: Promise<void>; deleteLocalFile: Promise<void>; disablePostcallSubmit: Promise<void>; downloadFile: Promise<null>; embeddableReady: Promise<void>; enablePostcallSubmit: Promise<void>; fetchDocumentInfo: Promise<{[key: string]: unknown; pageCount: number; }>; getAppConfig: Promise<Record<string, any>>; getCanvas: Promise<CanvasRetrieve>; getCanvases: Promise<PaginatedData<CanvasRetrieve>>; getCanvasRecommendedFiles: Promise<CanvasRecommendedFiles>; getCanvasTheme: Promise<CanvasThemeRetrieve | null>; getCoreFolders: Promise<CoreFolderContentsRetrieve>; getEnv: Promise<PitcherEnv>; getFile: Promise<FileRetrieve>; getFileRevisionData: Promise<FileRetrieve>; getFileRevisions: Promise<FileRevision[]>; getFiles: Promise<PaginatedFileList>; getFolder: Promise<FolderRetrieve>; getFolders: Promise<PaginatedFolderList>; getInstanceMetadataTemplates: Promise<PaginatedMetadataTemplateList>; getSectionsByIds: Promise<{ sections: CanvasSection[]; }>; getThemes: Promise<CanvasThemeRetrieve[]>; getUsers: Promise<PaginatedData<User>>; isOffline: Promise<boolean>; moveFolderItems: Promise<FolderRetrieve>; notify: Promise<void>; open: Promise<void>; openCanvasOverlay: Promise<void>; openCollectionPlayerOverlay: Promise<void>; openExternalUrl: Promise<void>; openGlobalPopup: Promise<UiOpenGlobalPopupResponse>; openSharingSettings: Promise<UiOpenSharingSettingsResponse>; openWebViewAlwaysOnTop: Promise<void>; patchCoreFolder: Promise<CoreFolderContentsRetrieve>; piaSearchAnswer: Promise<PiaSearchAnswerResult>; postJsonWithTimeout: Promise<T>; preselectSfdcMeetingId: Promise<UiPreselectSfdcMeetingIdResponse>; printCanvas: Promise<UiPrintCanvasResponse>; promptPia: Promise<UiPromptPiaResponse>; query: Promise<any>; refreshAccessToken: any; refreshServiceToken: Promise<RefreshServiceTokenResponse>; renderPageAsImage: Promise<ArrayBuffer>; resumeMeeting: Promise<void>; search: Promise<any>; selectAgendaContent: Promise<UiSelectAgendaResponse>; selectCanvases: Promise<UiSelectCanvasesResponse>; selectCollectionContent: Promise<UiSelectCollectionPlayerResponse>; selectContent: Promise<UiSelectContentResponse>; selectDeviceFile: Promise<DeviceFile>; setPostcallStyle: Promise<void>; share: Promise<ShareResponse>; shareCanvas: Promise<SharedLink>; showPeerSession: Promise<void>; showSyncbox: Promise<void>; slideSearch: Promise<SlideSearchResult>; stopMeeting: Promise<void>; sttAvailability: Promise<SttAvailabilityResult>; sttErrorCode: SttErrorCode | undefined; sttStart: Promise<void>; sttStop: Promise<SttStopResult>; sttWarmup: Promise<void>; submitUserFeedback: Promise<any>; toast: Promise<void>; track: Promise<any>; triggerNonFilesSync: Promise<void>; ttsErrorCode: TtsErrorCode | undefined; ttsSpeak: Promise<TtsSpeakResult>; ttsStop: Promise<void>; ttsWarmup: Promise<void>; unassignCanvasTheme: Promise<void>; updateCanvas: Promise<CanvasRetrieve>; updateCanvasIndicators: Promise<CanvasRetrieve>; updateFile: Promise<FileRetrieve>; updateFolder: Promise<FolderRetrieve>; updateLocation: Promise<any>; updateMyUser: Promise<User>; weeklyFocusRank: Promise<WeeklyFocusRankResult>; }

API

API: LowLevelApi

broadcast

broadcast: (event) => Promise<any>

Broadcast an event to CatalogIQ.

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcast({
    type: "canvas_updated",
    body: { context: { myContextProperty: 'test' } },
  })
  .then(function (result) {
    useUi().toast({
      message: "Canvas Populated.",
      type: "info",
    })
  })

broadcastToWebviews

broadcastToWebviews: (event) => Promise<any>

Broadcast an event to webviews only (iOS only).

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcastToWebviews({
    type: "canvas_updated",
    body: { context: { myContextProperty: 'test' } },
  })
  .then(function (result) {
    useUi().toast({
      message: "Canvas Populated.",
      type: "info",
    })
  })

enterFullscreen

enterFullscreen: () => Promise<any>

Make the entire CatalogIQ fullscreen.

Returns

Promise<any>

Example

usePitcherApi().enterFullscreen()

exitFullscreen

exitFullscreen: () => Promise<any>

Exit fullscreen mode.

Returns

Promise<any>

Example

usePitcherApi().exitFullscreen()

getRequestTypes

getRequestTypes: () => Promise<any>

Get the request types.

Returns

Promise<any>

impact

impact: object

impact.API

API: LowLevelApi

impact.broadcast

broadcast: (event) => Promise<any>

Broadcast an event to CatalogIQ.

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcast({
    type: "canvas_updated",
    body: { context: { myContextProperty: 'test' } },
  })
  .then(function (result) {
    useUi().toast({
      message: "Canvas Populated.",
      type: "info",
    })
  })

impact.broadcastToWebviews

broadcastToWebviews: (event) => Promise<any>

Broadcast an event to webviews only (iOS only).

Parameters

Parameter	Type	Description
event	PitcherEvent	The event to broadcast.

Returns

Promise<any>

Example

usePitcherApi()
  .broadcastToWebviews({
    type: "canvas_updated",
    body: { context: { myContextProperty: 'test' } },
  })
  .then(function (result) {
    useUi().toast({
      message: "Canvas Populated.",
      type: "info",
    })
  })

impact.enterFullscreen

enterFullscreen: () => Promise<any>

Make the entire CatalogIQ fullscreen.

Returns

Promise<any>

Example

usePitcherApi().enterFullscreen()

impact.exitFullscreen

exitFullscreen: () => Promise<any>

Exit fullscreen mode.

Returns

Promise<any>

Example

usePitcherApi().exitFullscreen()

impact.getRequestTypes

getRequestTypes: () => Promise<any>

Get the request types.

Returns

Promise<any>

impact.isFullscreen

isFullscreen: () => Promise<any>

Return is CatalogIQ in fullscreen.

Returns

Promise<any>

Example

usePitcherApi().isFullscreen()

impact.logout

logout: () => Promise<any>

Log out the current user.

Returns

Promise<any>

Example

usePitcherApi().logout()

impact.off

off: (type, callback) => void

Unsubscribe from a given event type by its key and the attached callback reference.

Parameters

Parameter	Type	Description
type	string	The event type to unsubscribe from.
callback	(payload) => void	The callback function reference to remove.

Returns

void

Example

const callback = (event: object) => {
  // handle event
}
usePitcherApi().on('entered_fullscreen', callback)
// later
usePitcherApi().off('entered_fullscreen', callback)

impact.on

on: (type, callback) => void

Subscribe to a given event type by its key.

Parameters

Parameter	Type	Description
type	string	The event type to subscribe to.
callback	(payload) => void	The callback function to handle the event.

Returns

void

Nothing. To unsubscribe, pass the same callback reference to off().

Example

usePitcherApi().on('entered_fullscreen', (event: object) => {
  // handle event
})

impact.quitInstance

quitInstance: () => Promise<any>

Quit the current instance and go to the instance selection screen.

Returns

Promise<any>

Example

usePitcherApi().quitInstance()

impact.subscribe

subscribe: () => Promise<any>

Subscribe to updates.

Returns

Promise<any>

impact.unsubscribe

unsubscribe: () => Promise<any>

Unsubscribe from updates.

Returns

Promise<any>

impact.aiComplete()

aiComplete(payload): Promise<AICompleteResult>

Run an AI completion on the on-device model (iOS only). On web the host rejects with a clear error — use piaSearchAnswer (or the next-core AI routes) for online inference instead.

The payload is the EXACT iOS wire contract: { prompt, max_tokens?, stream? } → { text, tokens_generated, elapsed_seconds, time_to_first_token_seconds }.

Parameters

Parameter	Type	Description
payload	AICompletePayload	The completion payload.

Returns

Promise<AICompleteResult>

• Promise resolving with the completion.

Example

const completion = await api.aiComplete({ prompt: 'Summarize ...', max_tokens: 256 })
console.log(completion.text)

impact.aiGetCapabilities()

aiGetCapabilities(): Promise<AIRuntimeCapabilities>

Capabilities of the AI completion runtime on the current platform.

On iOS this asks the native on-device bridge (ai.get_capabilities); on web it resolves statically to the online (Bedrock) runtime — no postMessage round-trip.

Returns

Promise<AIRuntimeCapabilities>

• Promise resolving with the runtime capabilities.

Example

const capabilities = await api.aiGetCapabilities()
if (capabilities.available) { ... }

impact.appsDbDeleteEntry()

appsDbDeleteEntry(payload): Promise<void>

Deletes an AppsDB entry (soft delete server-side), adapting to the platform:

• Web: DELETE to the next-core AppsDB REST API.
• Native (iPad or desktop): the appsdb_delete_entry bridge request deletes on the server and removes the entry from the local offline mirror. Offline it rejects with code = offline_write_not_supported.

Parameters

Parameter	Type
payload	AppsDbDeleteEntryPayload

Returns

Promise<void>

Example

await api.appsDbDeleteEntry({ id: '01H5ZXE7YP2JR6Q1Z2G3K4H5J6' })

impact.appsDbGetEntries()

appsDbGetEntries(payload): Promise<AppsDbEntriesResult>

Lists AppsDB entries of a type, adapting to the platform:

• Web: GET to the next-core AppsDB REST API.
• Native (iPad or desktop): reads the local offline mirror via the appsdb_get_entries bridge request. Types not allowlisted in the offline_appsdb_types setting fail with code = type_not_synced and automatically fall back to the network.

Parameters

Parameter	Type
payload	AppsDbGetEntriesPayload

Returns

Promise<AppsDbEntriesResult>

Example

const { entries } = await api.appsDbGetEntries({ type: 'favorite' })

impact.appsDbPsql()

appsDbPsql(payload): Promise<AppsDbEntriesResult>

Runs a PSQL (SQL-like) query against AppsDB: POST to the next-core /appsdb/psql endpoint whenever the network is available.

On a native host the local offline mirror (appsdb_get_entries + client-side evaluation of simple field = literal AND-chains) serves the query ONLY while the device is offline, or when an online fetch fails at the connection level. Online queries are always answered by the server: Hub flows use psql results to decide between creating and updating an entry, and the mirror can lag the server by a sync cycle (multi-device) — a stale empty read would turn an update into a duplicate create. Offline that same stale read is harmless because AppsDB writes are rejected offline anyway.

Parameters

Parameter	Type
payload	AppsDbPsqlPayload

Returns

Promise<AppsDbEntriesResult>

Example

const { entries } = await api.appsDbPsql({
  query: "SELECT * FROM personalfolders WHERE user_id = 1 AND data.custom_domain = 'acme.my.pitcher.com'",
})

impact.appsDbUpsertEntry()

appsDbUpsertEntry(payload): Promise<AppsDbEntry>

Creates or updates (deep-merges) an AppsDB entry, adapting to the platform:

• Web: POST (create) or PUT (update, when id is set) to the next-core AppsDB REST API.
• Native (iPad or desktop): the appsdb_upsert_entry bridge request writes on the server and mirrors the authoritative result locally. Offline it rejects with code = offline_write_not_supported — AppsDB writes are online-only.

The data blob is sent verbatim (no key-casing transformation), and all appsDb* responses are likewise returned verbatim — even for casing: 'camel' consumers — so bridge and REST results are identical.

Parameters

Parameter	Type
payload	AppsDbUpsertEntryPayload

Returns

Promise<AppsDbEntry>

Example

const entry = await api.appsDbUpsertEntry({ type: 'favorite', user_id: 1, data: { file_id: 'abc' } })

impact.assignCanvasTheme()

assignCanvasTheme(payload): Promise<{ canvas_id: string; theme_id: string; }>

Parameters

Parameter	Type
payload	{ canvas_id: string; theme_id: string; }
payload.canvas_id	string
payload.theme_id	string

Returns

Promise<{ canvas_id: string; theme_id: string; }>

impact.close()

close(): Promise<any>

Returns

Promise<any>

impact.createCanvas()

createCanvas(payload): Promise<CanvasRetrieve>

Parameters

Parameter	Type
payload	Omit<CanvasCreateRequest, "instance_id">

Returns

Promise<CanvasRetrieve>

impact.createFile()

createFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	Omit<AllFileCreateRequest, "instance_id">

Returns

Promise<FileRetrieve>

impact.createFolder()

createFolder(payload): Promise<FolderRetrieve>

Creates a new folder.

Parameters

Parameter	Type	Description
payload	Omit<FolderCreateRequest, "instance_id">	The folder creation request payload, excluding the instance_id.

Returns

Promise<FolderRetrieve>

A promise that resolves to the created folder.

impact.crmCreate()

crmCreate(payload): Promise<any>

Creates new records in CRM (Web only). Uses Salesforce REST API to create records.

Parameters

Parameter	Type	Description
payload	CRMCreatePayload	The create payload containing sobject type and records.

Returns

Promise<any>

• Promise resolving with the result of the create operation.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to create CRM records.
api.crmCreate({
  sobject: 'Order__c',
  records: [
    { Account__c: '001xx000003DGbQAAW', Order_Date__c: '2024-01-15' },
    { Account__c: '001xx000003DGbRABW', Order_Date__c: '2024-01-16' }
  ]
})

impact.crmDescribe()

crmDescribe(payload): Promise<any>

Retrieves metadata/describe for a CRM object (Web only). Uses Salesforce REST API to fetch object metadata including fields and picklist values.

Parameters

Parameter	Type	Description
payload	CRMDescribePayload	The describe payload containing the sobject name.

Returns

Promise<any>

• Promise resolving with the object metadata including fields and picklist values.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to get CRM object metadata.
api.crmDescribe({ sobject: 'Account' })
  .then(metadata => {
    // Access fields
    console.log(metadata.fields)
    // Access picklist values for a specific field
    const industryField = metadata.fields.find(f => f.name === 'Industry')
    console.log(industryField.picklistValues)
  })

impact.crmLayout()

crmLayout(payload): Promise<any>

Retrieves layout information for a CRM object (Web only). Uses Salesforce REST API to fetch object layout including sections, fields arrangement, and form factors.

Parameters

Parameter	Type	Description
payload	CRMLayoutPayload	The layout payload containing the sobject name and optional layout parameters.

Returns

Promise<any>

• Promise resolving with the object layout information.

Throws

• Throws an error if the payload is invalid.

Examples

// Web only method to get CRM object layout.
api.crmLayout({ sobject: 'Account' })
  .then(layout => {
    // Access layout sections
    console.log(layout.editLayoutSections)
  })

// Get layout with specific form factor, mode, and record type.
api.crmLayout({
  sobject: 'Account',
  form_factor: 'Large',
  mode: 'Edit',
  record_type_id: '012xx0000004ABC'
})

impact.crmQuery()

crmQuery(payload): Promise<any>

Parameters

Parameter	Type
payload	CRMQueryPayload

Returns

Promise<any>

impact.crmQueryAdaptive()

crmQueryAdaptive(payload): Promise<any>

Executes a CRM query with automatic iOS/SmartStore adaptation.

On iOS devices with the 'sfdc_offline_enabled' LaunchDarkly flag enabled, this function automatically converts SOQL queries to SmartStore Smart SQL format and uses the local SmartStore for offline data access. On other platforms or when the flag is disabled, it uses the standard CRM query API.

Parameters

Parameter	Type	Description
payload	CRMQueryPayload	The query payload containing the SOQL query string.

Returns

Promise<any>

• Promise resolving with query results.

Example

// Works on all platforms - automatically adapts for iOS with sfdc_offline_enabled LD flag
const result = await crmQueryAdaptive({ query: 'SELECT Id, Name FROM Account WHERE Active = true' })

impact.crmSmartDeleteObjects()

crmSmartDeleteObjects(payload): Promise<any>

Deletes CRM objects from local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to delete records. Each object in the payload specifies a table name and an array of IDs to delete.

Parameters

Parameter	Type	Description
payload	CRMSmartDeleteObjectsPayload	The delete payload containing an array of CRMDeleteObject items.

Returns

Promise<any>

• Promise resolving with the result of the delete operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to delete CRM objects.
api.crmSmartDeleteObjects({
  objects: [
    {
      table_name: 'Account',
      ids: ['001xx000003DGbQAAW', '001xx000003DGbRABW']
    },
    {
      table_name: 'Contact',
      ids: ['003xx000004TmiQAAS']
    }
  ]
})

impact.crmSmartObjectLayout()

crmSmartObjectLayout(payload): Promise<any>

Retrieves layout information for a CRM smart object (iOS only). Fetches object layout metadata from the Salesforce Mobile SDK cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectLayoutPayload	The payload containing the object name and optional layout parameters.

Returns

Promise<any>

• Promise resolving with the object layout metadata.

Throws

• Throws an error if the object name is not provided.

Examples

// iOS only method to retrieve CRM object layout.
api.crmSmartObjectLayout({ object: 'Account' })

// Get layout with specific form factor and mode.
api.crmSmartObjectLayout({ object: 'Account', form_factor: 'Large', mode: 'Edit' })

impact.crmSmartObjectMetadata()

crmSmartObjectMetadata(payload): Promise<any>

Retrieves metadata for a CRM smart object (iOS only). Fetches object metadata from the Salesforce Mobile SDK cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectMetadataPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the object metadata.

Throws

• Throws an error if the object name is not provided.

Example

// iOS only method to retrieve CRM object metadata.
api.crmSmartObjectMetadata({ object: 'Account' })

impact.crmSmartObjectValidationRules()

crmSmartObjectValidationRules(payload): Promise<any>

Retrieves validation rules for a CRM smart object (iOS only). This method fetches the validation rules configured for a specific CRM object type from the local SmartStore cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectValidationRulesPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the validation rules for the specified object.

Examples

// iOS only method to get validation rules for an Account object.
api.crmSmartObjectValidationRules({ object: 'Account' })

// Get validation rules for a Contact object.
api.crmSmartObjectValidationRules({ object: 'Contact' })

impact.crmSmartQuery()

crmSmartQuery(payload): Promise<any[]>

Executes a SmartStore query against local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore query syntax. Validates that the query uses SmartStore syntax before execution.

Parameters

Parameter	Type	Description
payload	CRMQueryPayload	The query payload containing the SmartStore query string.

Returns

Promise<any[]>

• Promise resolving with an array of query results from SmartStore.

Throws

• Throws an error if the query is not a valid SmartStore query.

Example

// iOS only method to execute a SmartStore query.
api.crmSmartQuery({ query: 'SELECT {Account:Id}, {Account:Name} FROM {Account} ORDER BY {Account:Name} LIMIT 10' })

impact.crmSmartUpsertObjects()

crmSmartUpsertObjects(payload): Promise<any>

Upserts CRM objects into local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to insert or update records. Each object in the payload specifies a table name, the objects to upsert, and an optional external ID path.

Important: Always provide external_id_path when performing updates to ensure records are matched correctly. Without it, the operation may create duplicate records instead of updating existing ones.

Note: When creating new records, you must provide an explicit identifier field (e.g., Id) in each record object passed from the frontend. The backend does not auto-generate IDs.

Parameters

Parameter	Type	Description
payload	UpsertCRMObjectsPayload	The upsert payload containing an array of UpsertCRMObject items.

Returns

Promise<any>

• Promise resolving with the result of the upsert operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to upsert CRM objects.

// Updating existing records - always include external_id_path
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [{ Id: '001xx000003DGbQAAW', Name: 'Acme Corp Updated' }],
      external_id_path: 'Id' // Required for updates to match existing records
    }
  ]
})

// Creating new records - explicit ID required in each record
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [
        { Id: '001xx000003NEW001', Name: 'New Company' }, // Explicit ID required
        { Id: '001xx000003NEW002', Name: 'Another Company' }
      ]
    }
  ]
})

impact.crmUpsert()

crmUpsert(payload): Promise<any>

Upserts records in CRM (Web only). Uses Salesforce REST API to insert or update records based on external ID. If a record with matching external ID exists, it will be updated; otherwise, a new record is created.

Parameters

Parameter	Type	Description
payload	CRMUpsertPayload	The upsert payload containing sobject type, records, and external ID field.

Returns

Promise<any>

• Promise resolving with the result of the upsert operation.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to upsert CRM records.
api.crmUpsert({
  sobject: 'Order__c',
  records: [
    { External_Id__c: 'ORD-001', Account__c: '001xx000003DGbQAAW', Status__c: 'Submitted' },
    { External_Id__c: 'ORD-002', Account__c: '001xx000003DGbRABW', Status__c: 'Draft' }
  ],
  external_id_field: 'External_Id__c'
})

impact.deleteCanvas()

deleteCanvas(payload): Promise<CanvasRetrieve>

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<CanvasRetrieve>

impact.deleteFile()

deleteFile(payload): Promise<string>

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<string>

impact.deleteFolder()

deleteFolder(payload): Promise<void>

Deletes a folder.

Parameters

Parameter	Type	Description
payload	{ folder_id: string; }	An object containing the ID of the folder to delete.
payload.folder_id	string	The ID of the folder to delete.

Returns

Promise<void>

A promise that resolves when the folder is deleted.

impact.deleteLocalFile()

deleteLocalFile(payload): Promise<void>

Deletes a local file on iOS devices from Pitcher Folders.

Parameters

Parameter	Type
payload	{ url: string; }
payload.url	string

Returns

Promise<void>

Example

// iOS only method to delete a local file.
api.deleteLocalFile({ url: 'file:///var/mobile/Containers/Data/Application/x/Documents/Pitcher%20Folders/ARPhotocapture/x.png' })

impact.downloadFile()

downloadFile(payload): Promise<null>

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<null>

impact.fetchDocumentInfo()

fetchDocumentInfo(payload): Promise<{[key: string]: unknown; pageCount: number; }>

Parameters

Parameter	Type
payload	{ fileId: string; }
payload.fileId	string

Returns

Promise<{[key: string]: unknown; pageCount: number; }>

Deprecated

• not used anymore

impact.getAppConfig()

getAppConfig(payload?): Promise<Record<string, any>>

Parameters

Parameter	Type
payload?	{ app_name?: string; }
payload.app_name?	string

Returns

Promise<Record<string, any>>

impact.getCanvas()

getCanvas(payload): Promise<CanvasRetrieve>

Fetches a single canvas by ID.

Pass lazy_sections: true to request the opt-in lazy "shell": when the org/instance lazy_load_sections setting is also on, the response returns ordered section_ids instead of the heavy inline sections, and you hydrate section bodies on demand via getSectionsByIds. With the setting off (or the param omitted) the response is the legacy fully-expanded canvas.

Parameters

Parameter	Type	Description
payload	{ fields?: string; id: string; lazy_sections?: boolean; skip_error_toast?: boolean; }	-
payload.fields?	string	-
payload.id	string	-
payload.lazy_sections?	boolean	-
payload.skip_error_toast?	boolean	Suppress the host's error toast for best-effort reads (e.g. download-completion polling).

Returns

Promise<CanvasRetrieve>

impact.getCanvases()

getCanvases(payload): Promise<PaginatedData<CanvasRetrieve>>

Fetches a list of canvases to use in your app.

Parameters

Parameter	Type
payload	GetCanvasesParams & object

Returns

Promise<PaginatedData<CanvasRetrieve>>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
api.getCanvases({
  search: 'my search query',
  ordering: '-created_at',
  filters: {
    metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
    metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
  },
 fields: 'id,name,metadata',
})

impact.getCanvasRecommendedFiles()

getCanvasRecommendedFiles(payload): Promise<CanvasRecommendedFiles>

Parameters

Parameter	Type
payload	{ canvas_id: string; match?: ("metadata" | "tags")[]; }
payload.canvas_id	string
payload.match?	("metadata" | "tags")[]

Returns

Promise<CanvasRecommendedFiles>

impact.getCanvasTheme()

getCanvasTheme(payload): Promise<CanvasThemeRetrieve | null>

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<CanvasThemeRetrieve | null>

impact.getCoreFolders()

getCoreFolders(payload): Promise<CoreFolderContentsRetrieve>

Parameters

Parameter	Type
payload	{ entity: CoreFolderEntityType; instance_id: string; parent_id?: string | null; }
payload.entity	CoreFolderEntityType
payload.instance_id	string
payload.parent_id?	string | null

Returns

Promise<CoreFolderContentsRetrieve>

impact.getEnv()

getEnv(): Promise<PitcherEnv>

Fetches the necessary info for the app to know where it is embedded.

It contains information about:

• user
• instance
• organization
• security token to query Pitcher REST API
• Salesforce connection information (if connected) including security token to query Salesforce REST API
• Auth0 token information

Returns

Promise<PitcherEnv>

Example

const env = usePitcherApi().getEnv().then((env) => {
  console.log(env.pitcher.user.name)
})

impact.getFile()

getFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	{ file_id?: string; id?: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRetrieve>

impact.getFileRevisionData()

getFileRevisionData(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	{ file_id: string; revision_id: string; }
payload.file_id	string
payload.revision_id	string

Returns

Promise<FileRetrieve>

impact.getFileRevisions()

getFileRevisions(payload): Promise<FileRevision[]>

Parameters

Parameter	Type
payload	{ file_id?: string; id?: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRevision[]>

impact.getFiles()

getFiles(payload): Promise<PaginatedFileList>

Parameters

Parameter	Type
payload	Partial<Omit<File, "type">> & object & object

Returns

Promise<PaginatedFileList>

impact.getFolder()

getFolder(payload?): Promise<FolderRetrieve>

Retrieves a folder by its ID.

Parameters

Parameter	Type	Description
payload	{ id: string; }	An object containing the folder ID.
payload.id	string	The ID of the folder to retrieve. Defaults to 'root'.

Returns

Promise<FolderRetrieve>

A promise that resolves to the retrieved folder.

impact.getFolders()

getFolders(payload): Promise<PaginatedFolderList>

Retrieves a list of folders.

Parameters

Parameter	Type	Description
payload	FolderListRequest	The payload containing the search, ordering, filters, fields, name, page, and page_size.

Returns

Promise<PaginatedFolderList>

A promise that resolves to the list of folders.

impact.getInstanceMetadataTemplates()

getInstanceMetadataTemplates(payload?): Promise<PaginatedMetadataTemplateList>

Parameters

Parameter	Type
payload?	GetInstanceMetadataTemplatesPayload

Returns

Promise<PaginatedMetadataTemplateList>

impact.getSectionsByIds()

getSectionsByIds(payload): Promise<{ sections: CanvasSection[]; }>

Batch-hydrate section bodies for a canvas fetched as a lazy shell.

Companion to getCanvas({ lazy_sections: true }): pass the canvas ID and a slice of its section_ids (≤100 per call) and receive the full section bodies, serialized identically to a normal canvas retrieve's inline sections. Only sections actually referenced by the canvas are returned.

Pass the SAME exclude_drafts / include_expired_files / include_pending_files the shell was fetched with so hydration filters identically to the shell that advertised the IDs — otherwise admin decks (fetched with exclude_drafts:false, expired/pending on) list draft/expired sections the batch would silently drop, leaving them blank. Omit them to get the rep defaults (drafts excluded, expired/pending off). include_expired_files/include_pending_files are server-side role-gated (admin/editor only), matching the inline retrieve.

Parameters

Parameter	Type
payload	{ canvas_id: string; exclude_drafts?: boolean; include_expired_files?: boolean; include_pending_files?: boolean; section_ids: string[]; }
payload.canvas_id	string
payload.exclude_drafts?	boolean
payload.include_expired_files?	boolean
payload.include_pending_files?	boolean
payload.section_ids	string[]

Returns

Promise<{ sections: CanvasSection[]; }>

Example

const { sections } = await api.getSectionsByIds({
  canvas_id: '01HH4RCBH631K4JDHWAQB0RPR6',
  section_ids: ['01SEC...', '02SEC...'],
})

impact.getThemes()

getThemes(payload): Promise<CanvasThemeRetrieve[]>

Parameters

Parameter	Type
payload	Partial<CanvasThemeRetrieve>

Returns

Promise<CanvasThemeRetrieve[]>

impact.getUsers()

getUsers(payload?): Promise<PaginatedData<User>>

Parameters

Parameter	Type
payload?	GetUsersParams

Returns

Promise<PaginatedData<User>>

impact.isOffline()

isOffline(): Promise<boolean>

Returns

Promise<boolean>

impact.moveFolderItems()

moveFolderItems(payload): Promise<FolderRetrieve>

Moves items (files or folders) to a target folder.

Parameters

Parameter	Type	Description
payload	{ items: object[]; target_folder_id: string; }	The payload containing the target folder ID and items to move.
payload.items	object[]	An array of items to move, each with an ID and type.
payload.target_folder_id	string	The ID of the target folder.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated target folder.

impact.notify()

notify(payload): Promise<void>

Parameters

Parameter	Type
payload	NotificationPayload

Returns

Promise<void>

impact.open()

open(payload?): Promise<string>

Open a file in the CatalogIQ instance.

Parameters

Parameter	Type
payload	OpenRequestPayload

Returns

Promise<string>

impact.openExternalUrl()

openExternalUrl(payload): Promise<void>

Open external URL in a new tab. Works on both web and mobile.

Parameters

Parameter	Type
payload	OpenExternalUrlRequestPayload

Returns

Promise<void>

impact.openWebViewAlwaysOnTop()

openWebViewAlwaysOnTop(payload): Promise<void>

Parameters

Parameter	Type
payload	OpenWebViewAlwaysOnTop

Returns

Promise<void>

impact.patchCoreFolder()

patchCoreFolder(id, payload): Promise<CoreFolderContentsRetrieve>

Parameters

Parameter	Type
id	string
payload	Partial<CoreFolderRetrieve>

Returns

Promise<CoreFolderContentsRetrieve>

impact.piaSearchAnswer()

piaSearchAnswer(payload): Promise<PiaSearchAnswerResult>

Answer a rep's natural-language question over the instance's content — the ONE high-level PIA Search call (PIT-6863). Routing follows the pia_search_config flag mode (see resolvePiaSearchMode):

• on_device on iOS with an available local model → aiComplete over the caller-assembled context_text (the Hub has the file metadata client-side). Unavailable/downloading models fall through to online.
• online (or any on-device fallback) → POST to the next-core pia-prepare/pia-search Bedrock route, which assembles its own candidate context server-side.
• off → rejects.

Parameters

Parameter	Type	Description
payload	PiaSearchAnswerPayload	The question + optional context/narrowing.

Returns

Promise<PiaSearchAnswerResult>

• Unified answer with the serving source.

Example

const result = await api.piaSearchAnswer({ query: 'What is our pricing for oncology?' })
console.log(result.answer, result.cited_file_ids, result.source)

impact.postJsonWithTimeout()

postJsonWithTimeout<T>(url, body, accessToken, timeoutMs, label): Promise<T>

POST JSON to a next-core route with a hard deadline, returning the parsed body. The shared scaffold behind the SDK's online AI calls (piaSearchAnswer, weeklyFocusRank).

Bounds the WHOLE request including the body read: fetch() resolves on headers alone, so reading .json() INSIDE the timed window (and letting the abort cancel that read too — hence clearTimeout in finally) is what stops a response that stalls mid-body from hanging unbounded. label names the route in BOTH the non-2xx error (<label> <status>) and the timeout error, so each caller keeps its exact error strings.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
url	string
body	unknown
accessToken	string
timeoutMs	number
label	string

Returns

Promise<T>

impact.query()

query(payload): Promise<any>

Parameters

Parameter	Type
payload	QueryPayload

Returns

Promise<any>

impact.refreshAccessToken()

refreshAccessToken(): any

Returns

any

impact.refreshServiceToken()

refreshServiceToken(payload?): Promise<RefreshServiceTokenResponse>

Ask for a refreshed Salesforce token. In case the token hasn't expired yet, this method will return the same token as the current one found in the (getEnv)[#getenv] result.

Parameters

Parameter	Type
payload?	RefreshServiceTokenRequest

Returns

Promise<RefreshServiceTokenResponse>

Promise resolving to an object containing the token

impact.renderPageAsImage()

renderPageAsImage(payload): Promise<ArrayBuffer>

Renders a page from a file together with annotations.

Parameters

Parameter	Type	Description
payload	{ documentId?: string; fileId: string; pageIndex: number; params: { width: number; } | { height: number; }; }	-
payload.documentId?	string	The ID of the document to render (optional). If not provided the fileId will be used.
payload.fileId	string	The ID of the file to render. Used when the documentId is not available.
payload.pageIndex	number	The index of the page to render.
payload.params	{ width: number; } | { height: number; }	The parameters to use for rendering the page.

Returns

Promise<ArrayBuffer>

A promise that resolves with the image as an ArrayBuffer.

Example

api.renderPageAsImage({
  fileId: '123456',
  documentId: '654321',
  pageIndex: 0,
  params: { width: 1920 },
})

impact.search()

search(payload): Promise<any>

Parameters

Parameter	Type
payload	{ includeExpired?: boolean; query: string; }
payload.includeExpired?	boolean
payload.query	string

Returns

Promise<any>

impact.selectDeviceFile()

selectDeviceFile(): Promise<DeviceFile>

Dispatches iOS native file selector and returns the selected file.

Returns

Promise<DeviceFile>

Example

// iOS only method to select a file from the device.
api.selectDeviceFile()

impact.share()

share(payload): Promise<ShareResponse>

Dispatch iOS sharing dialog.

Parameters

Parameter	Type
payload	SharePayload

Returns

Promise<ShareResponse>

Example

api.share({text: "example text", subject: "example subject"})

impact.shareCanvas()

shareCanvas(payload): Promise<SharedLink>

Get (or create) the shared link for a canvas.

brand_id (PIT-7682, optional) names an entry in the instance's shared_link_brands setting and only takes effect when the link is created. Omit it and the server uses the brand the rep last used on that instance, falling back to the instance default — the behaviour quick-share, bulk-share and API-created links get. A host that does not forward it (the iOS bridge today) therefore still produces a correctly branded link, just without the rep's per-share choice.

Parameters

Parameter	Type
payload	{ brand_id?: string; id: string; }
payload.brand_id?	string
payload.id	string

Returns

Promise<SharedLink>

impact.showPeerSession()

showPeerSession(payload): Promise<void>

Show peer session dialog with button coordinates, for local peer sharing feature.

Parameters

Parameter	Type
payload	ShowPeerSessionRequestPayload

Returns

Promise<void>

Example

api.showPeerSession({x: 100, y: 200})

impact.showSyncbox()

showSyncbox(payload): Promise<void>

Parameters

Parameter	Type
payload	ShowSyncboxRequestPayload

Returns

Promise<void>

impact.slideSearch()

slideSearch(payload): Promise<SlideSearchResult>

Rank the slides of one wizard template configuration for a query (PIT-9090) — the online slide_search AITask, for vanilla and headless consumers that can load this SDK. (The React completion wizard calls the route directly.)

The caller passes its own visible realm (visible_group_names + visible_slide_refs); the server narrows the configuration to it, drops whatever the caller's ACL hides, and reranks with one model call. Results are ordered best first. Rejects on a non-2xx (slide_search <status>) or after 30 s.

Parameters

Parameter	Type	Description
payload	SlideSearchPayload	The configuration, the visible realm and the query.

Returns

Promise<SlideSearchResult>

• Ranked slides, the mode used and the realm size.

Example

const { results } = await api.slideSearch({
  canvas_id: deckId,
  section_list_id: 'node_abc',
  visible_group_names: ['Efficacy', 'Safety'],
  visible_slide_refs: ['01K…', '01F…_page_3'],
  query: 'which slides cover renal dosing?',
})

impact.sttAvailability()

sttAvailability(): Promise<SttAvailabilityResult>

Check whether dictation can be offered — a side-effect-free capability probe to gate a mic button. Does NOT prompt for the microphone or download a model. Answered by the native bridge on iOS and the Impact host on web.

Returns

Promise<SttAvailabilityResult>

{ available, engine, reason? } — available is true only when the feature is enabled AND an engine can run; engine is what would answer sttStart ("webspeech" sends audio off-device); reason is "disabled" or "unsupported" when not available.

Example

const { available, engine } = await api.sttAvailability()
if (available) showMicButton({ warnCloud: engine === 'webspeech' })

impact.sttErrorCode()

sttErrorCode(error): SttErrorCode | undefined

Extract the SttErrorCode from a rejected sttStart / sttStop, normalizing across hosts: the iOS bridge rejection (error_code / errorCode) and Impact web's { reason } / error message string. Returns undefined if no known code is present.

Parameters

Parameter	Type
error	unknown

Returns

SttErrorCode | undefined

Example

try { await api.sttStart({ session_id }) } catch (err) {
  if (api.sttErrorCode(err) === 'STT_BUSY') showMicInUseHint()
}

impact.sttStart()

sttStart(payload): Promise<void>

Parameters

Parameter	Type
payload	SttStartPayload

Returns

Promise<void>

impact.sttStop()

sttStop(payload): Promise<SttStopResult>

Finalize a dictation session. Resolves with the final full transcript; rejects with STT_NOT_RECORDING if the session isn't active.

Parameters

Parameter	Type	Description
payload	SttStopPayload	-

Returns

Promise<SttStopResult>

The final { transcript }.

Example

const { transcript } = await api.sttStop({ session_id: 'notes-1' })

impact.sttWarmup()

sttWarmup(): Promise<void>

Pre-load the on-device dictation model so a later sttStart resolves instantly (and the mic-permission prompt appears immediately instead of after a download). Web only — on iOS the native side manages its own model lifecycle, so the bridge has no stt.warmup type and calling it there rejects requestTypeDoesNotExists.

Fire-and-forget: don't block your UI on it and ignore rejections. It is idempotent (repeated / concurrent calls collapse to a single download) and a no-op when the feature is disabled or the engine has nothing to warm (Web Speech fallback). Call it right after sttAvailability reports available with engine === 'whisper'.

Returns

Promise<void>

Resolves once the model is ready (or immediately when there's nothing to warm).

Example

const { available, engine } = await api.sttAvailability()
if (available) {
  showMicButton()
  if (engine === 'whisper') api.sttWarmup().catch(() => {}) // background, non-blocking
}

impact.submitUserFeedback()

submitUserFeedback(payload): Promise<any>

Submit user feedback

Parameters

Parameter	Type
payload	SubmitUserFeedbackPayload

Returns

Promise<any>

impact.toast()

toast(payload): Promise<void>

Parameters

Parameter	Type
payload	{ message: string; type: string; }
payload.message	string
payload.type	string

Returns

Promise<void>

impact.track()

track(payload): Promise<any>

Parameters

Parameter	Type
payload	{ event_name: string; payload: any; }
payload.event_name	string
payload.payload	any

Returns

Promise<any>

impact.triggerNonFilesSync()

triggerNonFilesSync(): Promise<void>

Dispatches iOS only sync method for non-files.

Returns

Promise<void>

Example

// iOS only method to sync non-files from the server.
api.triggerNonFilesSync()

impact.ttsErrorCode()

ttsErrorCode(error): TtsErrorCode | undefined

Extract the TtsErrorCode from a rejected ttsSpeak, normalizing across hosts: the iOS bridge APIError (code / error_code / errorCode) and a host { reason } / error message string. Returns undefined if no known code is present.

Parameters

Parameter	Type
error	unknown

Returns

TtsErrorCode | undefined

Example

try { await api.ttsSpeak({ text, language }) } catch (err) {
  if (api.ttsErrorCode(err) === 'TTS_VOICE_UNAVAILABLE') promptVoiceDownload()
}

impact.ttsSpeak()

ttsSpeak(payload): Promise<TtsSpeakResult>

Speak text on the device speaker. Resolves when the utterance FINISHES; rejects with a TtsErrorCode.

Parameters

Parameter	Type	Description
payload	TtsSpeakPayload	-

Returns

Promise<TtsSpeakResult>

{ completed } — true if it finished naturally, false if stopped or replaced by a newer ttsSpeak.

Example

const { completed } = await api.ttsSpeak({ text: 'Meeting summary saved.', language: 'en-US' })

impact.ttsStop()

ttsStop(): Promise<void>

Stop any in-flight speech. The in-flight ttsSpeak resolves with { completed: false }.

Returns

Promise<void>

Example

await api.ttsStop()

impact.ttsWarmup()

ttsWarmup(): Promise<void>

Pre-load the on-device Supertonic model (web only) WITHOUT speaking, so a later ttsSpeak answers instantly instead of paying the first-use model download/init cost. Optional — call it when the app knows it will speak soon (e.g. once an AI response starts generating). A no-op on hosts with nothing to warm (iOS, or web with the on-device model disabled/ unsupported — Web Speech needs no warmup); the bridge has no tts.warmup type, so calling it there rejects with requestTypeDoesNotExists — catch and ignore, mirroring its STT counterpart sttWarmup.

Returns

Promise<void>

Example

api.ttsWarmup().catch(() => {}) // background, non-blocking

impact.unassignCanvasTheme()

unassignCanvasTheme(payload): Promise<void>

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<void>

impact.updateCanvas()

updateCanvas(payload): Promise<CanvasRetrieve>

Updates a canvas by ID

Parameters

Parameter	Type
payload	PatchedCanvasUpdateRequest & object

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  PitcherAPI.updateCanvas({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    fields: 'id,name',
    name: 'To 3!',
  }).then((res) => {
    console.log(res)  // logs: { id: '01HH4RCBH631K4JDHWAQB0RPR6', name: 'To 3!' }
  })
})

impact.updateCanvasIndicators()

updateCanvasIndicators(payload): Promise<CanvasRetrieve>

Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.

Indicators can also be updated using updateCanvas API but in this case passed object fully replaces existing indicators.

Parameters

Parameter	Type
payload	{ id: string; indicators: Record<string, CanvasIndicator>; instance_id?: string; }
payload.id	string
payload.indicators	Record<string, CanvasIndicator>
payload.instance_id?	string

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  PitcherAPI.updateCanvasIndicators({
    id: '01J9XT0WVXRTETF4CQZP42CPZP',
    indicators: {
      existing: { type: 'info', label: 'new label' }, // will be overriden
      new: { type: 'info', label: 'INFO' }, // will be added
      removeExisting: null // will be set to null and ignored, it is the same as removal
   }
   }).then((res) => {
    console.log(res)  // entire canvas object, including indicators field
  })
})

impact.updateFile()

updateFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	FileUpdateRequest & object

Returns

Promise<FileRetrieve>

impact.updateFolder()

updateFolder(payload): Promise<FolderRetrieve>

Updates an existing folder.

Parameters

Parameter	Type	Description
payload	UpdateFolderPayload	The folder update payload, including the folder ID and update data.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated folder.

impact.updateMyUser()

updateMyUser(payload): Promise<User>

Parameters

Parameter	Type
payload	UpdateEnvParams

Returns

Promise<User>

impact.weeklyFocusRank()

weeklyFocusRank(payload): Promise<WeeklyFocusRankResult>

Rank the rep's next-7-days meetings by how much preparation they need — the ONE high-level Weekly Focus call (PIT-7257), the weekly_focus AITask.

The on-device path runs the prompt, window, parser and ordinal resolver from @lib/ai-tasks/weekly-focus; the online route runs next-core's parallel copy of the same logic. The two are kept in lockstep by matching test suites, not a shared import (see that module's header / ADR-002), so the two paths produce the same shape:

• iOS with an available local model → aiComplete over the caller-supplied meetings + account context. Unavailable models / unusable output fall through.
• Otherwise → POST to the next-core Bedrock route.

The model picks meetings by ORDINAL and the resolver maps them back to event_ids, dropping out-of-range ones — so a returned id can only come from the meetings passed in.

This does NOT cache, lock or prewarm: an app that generates on a schedule (as pre-call-brief does) owns those mechanics and calls this underneath.

Parameters

Parameter	Type	Description
payload	WeeklyFocusRankPayload	The meetings + optional account context.

Returns

Promise<WeeklyFocusRankResult>

• Ranking with the serving source.

Example

const focus = await api.weeklyFocusRank({ meetings, context })
console.log(focus.hero, focus.top, focus.collapsed_count)

isFullscreen

isFullscreen: () => Promise<any>

Return is CatalogIQ in fullscreen.

Returns

Promise<any>

Example

usePitcherApi().isFullscreen()

logout

logout: () => Promise<any>

Log out the current user.

Returns

Promise<any>

Example

usePitcherApi().logout()

off

off: (type, callback) => void

Unsubscribe from a given event type by its key and the attached callback reference.

Parameters

Parameter	Type	Description
type	string	The event type to unsubscribe from.
callback	(payload) => void	The callback function reference to remove.

Returns

void

Example

const callback = (event: object) => {
  // handle event
}
usePitcherApi().on('entered_fullscreen', callback)
// later
usePitcherApi().off('entered_fullscreen', callback)

on

on: <T>(type, handler) => Promise<() => void>

Subscribe to a given event type by its key.

Type Parameters

Type Parameter
T extends keyof UiMessagePayloads

Parameters

Parameter	Type	Description
type	T	The event type/key to subscribe to.
handler	(data) => Promise<void>	The handler function to call when the event is emitted.

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribeFromSectionListUpdate = useUi().on('ui_section_list_updated', (event: object) => {
  // handle event
})

// later
unsubscribeFromSectionListUpdate.then(unsubscribe => unsubscribe())

onAppSetData

onAppSetData: (handler) => Promise<() => void>

Subscribe to the app set data event. It is triggered when the app data is set. This event is triggered when the app is loaded and in certain other cases after loading.

This is the main event for the canvas app to receive data from the CatalogIQ instance and know about its environment.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

let user = null
let isEditMode = null
let activeCanvas = null
let isPrintMode = false
const unsubscribePromise = useUi().onAppSetData((data) => {
  user = data?.user
  isEditMode = data?.is_edit_mode
  activeCanvas = data?.canvas
  isPrintMode = data?.display_mode === 'print' || data?.client === 'dsr'
  // ...mode logic...
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

onAppUpdateData

onAppUpdateData: (handler) => Promise<() => void>

Subscribe to the app update data event. It is triggered when the user changes from edit mode to view mode or vice versa and when the call is started or ended.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

let inCall = false
let isEditMode = false
const unsubscribePromise = useUi().onAppUpdateData((data) => {
  isEditMode = data?.is_edit_mode
  inCall = data?.in_call
  // ...mode logic...
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

onCanvasUpdated

onCanvasUpdated: (handler) => Promise<() => void>

Subscribe to the canvas updated event. It is triggered when the current canvas of the app is updated.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribePromise = useUi().onCanvasUpdated((event: { canvas }) => {
  // handle event
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

onMeetingCanceled

onMeetingCanceled: (handler) => Promise<() => void>

Subscribe to the meeting canceled event.

Parameters

Parameter	Type	Description
handler	(data) => Promise<void>	-

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribeFromMeetingCanceled = useUi().onMeetingCanceled((event: {
  accountId?: string;
  eventId?: string;
}) => {
  // handle event
})

// later
unsubscribeFromMeetingCanceled.then(cancel => cancel())

onSectionListUpdated

onSectionListUpdated: (handler) => Promise<() => void>

Subscribe to the section list updated event. It is triggered when the list of sections (products) in the current canvas is updated.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribePromise = useUi().onSectionListUpdated((event: { canvas }) => {
  // handle event
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

quitInstance

quitInstance: () => Promise<any>

Quit the current instance and go to the instance selection screen.

Returns

Promise<any>

Example

usePitcherApi().quitInstance()

subscribe

subscribe: () => Promise<any>

Subscribe to updates.

Returns

Promise<any>

ui

ui: object

ui.on

on: <T>(type, handler) => Promise<() => void>

Subscribe to a given event type by its key.

Type Parameters

Type Parameter
T extends keyof UiMessagePayloads

Parameters

Parameter	Type	Description
type	T	The event type/key to subscribe to.
handler	(data) => Promise<void>	The handler function to call when the event is emitted.

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribeFromSectionListUpdate = useUi().on('ui_section_list_updated', (event: object) => {
  // handle event
})

// later
unsubscribeFromSectionListUpdate.then(unsubscribe => unsubscribe())

ui.onAppSetData

onAppSetData: (handler) => Promise<() => void>

Subscribe to the app set data event. It is triggered when the app data is set. This event is triggered when the app is loaded and in certain other cases after loading.

This is the main event for the canvas app to receive data from the CatalogIQ instance and know about its environment.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

let user = null
let isEditMode = null
let activeCanvas = null
let isPrintMode = false
const unsubscribePromise = useUi().onAppSetData((data) => {
  user = data?.user
  isEditMode = data?.is_edit_mode
  activeCanvas = data?.canvas
  isPrintMode = data?.display_mode === 'print' || data?.client === 'dsr'
  // ...mode logic...
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

ui.onAppUpdateData

onAppUpdateData: (handler) => Promise<() => void>

Subscribe to the app update data event. It is triggered when the user changes from edit mode to view mode or vice versa and when the call is started or ended.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

let inCall = false
let isEditMode = false
const unsubscribePromise = useUi().onAppUpdateData((data) => {
  isEditMode = data?.is_edit_mode
  inCall = data?.in_call
  // ...mode logic...
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

ui.onCanvasUpdated

onCanvasUpdated: (handler) => Promise<() => void>

Subscribe to the canvas updated event. It is triggered when the current canvas of the app is updated.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribePromise = useUi().onCanvasUpdated((event: { canvas }) => {
  // handle event
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

ui.onMeetingCanceled

onMeetingCanceled: (handler) => Promise<() => void>

Subscribe to the meeting canceled event.

Parameters

Parameter	Type	Description
handler	(data) => Promise<void>	-

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribeFromMeetingCanceled = useUi().onMeetingCanceled((event: {
  accountId?: string;
  eventId?: string;
}) => {
  // handle event
})

// later
unsubscribeFromMeetingCanceled.then(cancel => cancel())

ui.onSectionListUpdated

onSectionListUpdated: (handler) => Promise<() => void>

Subscribe to the section list updated event. It is triggered when the list of sections (products) in the current canvas is updated.

Parameters

Parameter	Type
handler	(data) => Promise<void>

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

Example

const unsubscribePromise = useUi().onSectionListUpdated((event: { canvas }) => {
  // handle event
})

// later
unsubscribePromise.then(unsubscribe => unsubscribe())

ui.uiBroadcast

uiBroadcast: object

ui.appFullscreenChange()

appFullscreenChange(payload): Promise<void>

Tell the CatalogIQ UI that the app is showing something fullscreen, or has stopped. While the app reports is_fullscreen: true, the UI lays the app's page over its own top bar and sidebar, so content the app draws over its whole window covers the whole screen. Report is_fullscreen: false as soon as the app leaves fullscreen: the UI shows no exit of its own while covered.

For now the UI honours it only from the Canvas Renderer app (canvas-renderer) opened as a page of the UI's sidebar (ui_app module), which sends it while a collection player in its canvas is fullscreen, so that no app that misses its false can leave the rep stuck until Pitcher is relaunched. From any other app, and anywhere else such as an app embedded in a canvas, the message is ignored, as it is by a UI that predates it. It does not use the browser's Fullscreen API.

Parameters

Parameter	Type	Description
payload	UiAppFullscreenChangeRequest	object saying whether the app is now fullscreen

Returns

Promise<void>

Example

useUi().appFullscreenChange({ is_fullscreen: true })
// later, when the app leaves fullscreen
useUi().appFullscreenChange({ is_fullscreen: false })

ui.appLoaded()

appLoaded(): Promise<void>

Notify the CatalogIQ instance that the app is loaded and ready to get the data. Triggering this method will trigger the on_app_set_data event.

Returns

Promise<void>

Examples

useUi().appLoaded()

ui.appResize()

appResize(payload): Promise<void>

Resize the app iframe to a given height.

Note that initial iframe height comes from the app.json manifest file. It can also be adjusted by the user when adding app component to the canvas. In case when the app must be temporarily resized to show larger ui elements it can read the user-set height from the on_app_set_data event.

Parameters

Parameter	Type	Description
payload	UiAppResizeRequest	object containing requested height of the iframe as the number of pixels

Returns

Promise<void>

ui.cancelMeeting()

cancelMeeting(): Promise<void>

Cancels current meeting and the event remains unrealized (like it never happened).

Returns

Promise<void>

Example

useUi().cancelMeeting()

ui.canvasNavigateNextPage()

canvasNavigateNextPage(): Promise<void>

Navigate to the next page in the current canvas. Noop if the current page is the last one.

Returns

Promise<void>

Example

useUi().canvasNavigateNextPage()

ui.canvasNavigatePage()

canvasNavigatePage(payload): Promise<void>

Navigate to a specific canvas place in the current canvas. Despite the event and parameter name, it takes the component id that we want to put in view.

Parameters

Parameter	Type
payload	UiCanvasNavigatePageRequest

Returns

Promise<void>

Example

const uiApi = useUi() // our useApi()

let activeCanvas = null
const unsubscribe = uiApi.on_app_set_data((data) => {
  activeCanvas = data?.canvas
})

document.getElementById('my-button').addEventListener('click', () => {
  const target = activeCanvas?.content?.data?.find((i: any) => i.data.app_name === 'my-target-app-id') || null
  if (target) {
    uiApi.canvasNavigatePage({ page: target.id })
  }
})

ui.canvasNavigatePreviousPage()

canvasNavigatePreviousPage(): Promise<void>

Navigate to the previous page in the current canvas. Noop if the current page is the first one.

Returns

Promise<void>

Example

useUi().canvasNavigatePreviousPage()

ui.captureAppError()

captureAppError(payload): Promise<void>

Send an app error to Pitcher sentry instance.

Sentry files it under one issue per app + message and tags it app_name, so send your app's name as app_name (app is also read) and a stable message, and keep ids and other varying values in other fields. Without a name the error groups under unknown with every other unnamed app's. The whole payload is attached to the event.

Parameters

Parameter	Type	Description
payload	UiCaptureAppErrorRequest	error object to send to Pitcher sentry instance

Returns

Promise<void>

Example

try {
  throw new Error('This is an error')
} catch (error) {
  useUi().captureAppError({
    app_name: 'my-app',
    message: 'Failed to load accounts',
    stack: error instanceof Error ? error.stack : String(error),
  })
}

ui.closeCanvasDrawer()

closeCanvasDrawer(): Promise<void>

Close the Canvas Drawer modal. Only takes effect for apps running in canvas_drawer embed location

Note that this method simply closes the drawer and will result in the app calling it being unmounted from the DOM and destroyed. Make sure your app has finished updating data before you call this method.

Returns

Promise<void>

Example

useUi().closeCanvasDrawer()

ui.closeCanvasSectionExecution()

closeCanvasSectionExecution(): Promise<void>

Close the Canvas Section Execution modal. Only takes effect for canvas_section_execution app modules

Note that this method simply closes the modal and will result in the app calling it being unmounted from the DOM and destroyed. Make sure your app has finished updating data before you call this method.

Returns

Promise<void>

Example

useUi().closeCanvasSectionExecution()

ui.closeGlobalPopup()

closeGlobalPopup(): Promise<void>

Closes the currently open global popup app.

Returns

Promise<void>

Example

const api = useApi()
api.closeGlobalPopup()

ui.completePostcall()

completePostcall(payload): Promise<void>

Completes the postcall stage (with successful submission or not)

Parameters

Parameter	Type
payload	UiCompletePostcallRequest

Returns

Promise<void>

Example

useUi().completePostcall({ was_successfully_submitted: true })

ui.disablePostcallSubmit()

disablePostcallSubmit(): Promise<void>

Mark the postcall form as not possible to submit by the user. Useful while processing the form data.

Returns

Promise<void>

Deprecated

Example

useUi().disablePostcallSubmit()

ui.embeddableReady()

embeddableReady(): Promise<void>

This event is used for appJson.module.canvas.start_in_loading_mode: true apps. A loading curtain is displayed until you call this event.

Returns

Promise<void>

Example

useUi().embeddableReady()

ui.enablePostcallSubmit()

enablePostcallSubmit(): Promise<void>

Mark the postcall form as possible to submit by the user.

Returns

Promise<void>

Deprecated

Example

useUi().enablePostcallSubmit()

ui.open()

open(payload): Promise<void>

Open a file in the CatalogIQ instance.

Parameters

Parameter	Type
payload	UiOpenRequest

Returns

Promise<void>

ui.openCanvasOverlay()

openCanvasOverlay(payload): Promise<void>

Opens a modal to view a canvas by ID.

onMounted(() => {
  uiApi.openCanvasOverlay({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    edit_mode: false,
    fullscreen: true,
  })
})

You can also specify a position for the canvas overlay:

uiApi.openCanvasOverlay({
  id: '01HH4RCBH631K4JDHWAQB0RPR6',
  position: {
    top: '10px',
    left: '20px',
    right: '20px',
    bottom: '10px'
  }
})

If your app just created this canvas and is opening it only so the rep can run its completion wizard, set discard_on_wizard_cancel so that cancelling the wizard deletes the empty shell instead of leaving it in the rep's pitchdecks:

const canvas = await api.createCanvas(...)
uiApi.openCanvasOverlay({ id: canvas.id, edit_mode: true, discard_on_wizard_cancel: true })

Pass it ONLY for a canvas created moments ago — never when re-opening one the rep already has.

If your app navigates the shell instead of opening an overlay (update_location to /canvases/saved-canvases/<id>/build/<mode>), the equivalent is the discard_on_wizard_cancel query param on that route: query: { discard_on_wizard_cancel: '1' }. Accepted opt-in values are '1', 'true', '' and a bare key; ANY other value is ignored and nothing is discarded, so a wrong guess no-ops rather than deleting a canvas.

Parameters

Parameter	Type	Description
payload	{ component_id?: string; discard_on_wizard_cancel?: boolean; edit_mode?: boolean; fullscreen?: boolean; id: string; position?: { bottom?: string | number; left?: string | number; right?: string | number; top?: string | number; }; section_id?: string; }	-
payload.component_id?	string	-
payload.discard_on_wizard_cancel?	boolean	PIT-8622 — delete this canvas if the rep cancels its completion wizard. Opt-in, for apps that POST the canvas themselves before handing it to the shell.
payload.edit_mode?	boolean	-
payload.fullscreen?	boolean	-
payload.id	string	-
payload.position?	{ bottom?: string | number; left?: string | number; right?: string | number; top?: string | number; }	-
payload.position.bottom?	string | number	-
payload.position.left?	string | number	-
payload.position.right?	string | number	-
payload.position.top?	string | number	-
payload.section_id?	string	-

Returns

Promise<void>

ui.openCollectionPlayerOverlay()

openCollectionPlayerOverlay(payload): Promise<void>

Opens the collection player overlay to view a collection of files/slides.

This method opens the native Pitcher collection player interface with the specified files and slides. You can show entire files or specific pages from files.

Parameters

Parameter	Type	Description
payload	UiOpenCollectionPlayerOverlayRequest	Object containing groups array and collection name

Returns

Promise<void>

Example

// Open collection with full files
useUi().openCollectionPlayerOverlay({
  groups: [
    { id: 'file-123-abc', name: 'Product Overview' },
    { id: 'file-456-def', name: 'Pricing Slides' }
  ],
  name: 'Sales Deck'
})

// Open collection with specific slides/pages
useUi().openCollectionPlayerOverlay({
  groups: [
    {
      id: 'file-123-abc',
      name: 'Product Overview',
      slides: [
        { file_id: 'file-123-abc', slide_index: 0 },
        { file_id: 'file-123-abc', slide_index: 2 }
      ]
    }
  ],
  name: 'Custom Sales Presentation'
})

ui.openGlobalPopup()

openGlobalPopup(appName, extraContext?): Promise<UiOpenGlobalPopupResponse>

Opens a global popup app by name.

Parameters

Parameter	Type	Description
appName	string	The name of the app to open (must have app_type: 'ui-global-popup')
extraContext?	Record<string, any>	Extra context to pass to the app

Returns

Promise<UiOpenGlobalPopupResponse>

Promise with the result of the operation

Example

const api = useApi()
api.openGlobalPopup('my-popup-app')
api.openGlobalPopup('my-popup-app', { customData: 'value' })

ui.openSharingSettings()

openSharingSettings(payload): Promise<UiOpenSharingSettingsResponse>

Parameters

Parameter	Type
payload	UiOpenSharingSettingsRequest

Returns

Promise<UiOpenSharingSettingsResponse>

ui.preselectSfdcMeetingId()

preselectSfdcMeetingId(payload): Promise<UiPreselectSfdcMeetingIdResponse>

Preselect a meeting in the top meeting bar by Salesforce Meeting ID. From there, the user can easily start the meeting with a single click.

Parameters

Parameter	Type
payload	UiPreselectSfdcMeetingIdRequest

Returns

Promise<UiPreselectSfdcMeetingIdResponse>

Example

const objectFetchedFromSalesforce = {
  // fetch dynamically from Salesforce or provide in another way
  EventId: '00U1r00000D1J1zEAF',
}
ui.preselectSfdcMeetingId({ eventId: objectFetchedFromSalesforce.EventId }).then((response) => {
  // e.g. display advanced meeting details inside your app
  console.log(response.event)
})

ui.printCanvas()

printCanvas(payload): Promise<UiPrintCanvasResponse>

Trigger async print/download of a canvas with optional notification URL. Calls the downloader-test endpoint to convert the canvas to PDF.

Parameters

Parameter	Type	Description
payload	UiPrintCanvasRequest	Canvas ID and optional notify URL for async notifications

Returns

Promise<UiPrintCanvasResponse>

Promise with job ID and success status

Example

useUi().printCanvas({
  id: '01HH4RCBH631K4JDHWAQB0RPR6',
  notify_url: 'https://my-webhook.example.com/canvas-ready'
})

ui.promptPia()

promptPia(payload): Promise<UiPromptPiaResponse>

Sends a query to the Pitcher Intelligent Assistant (PIA) and handles the streamed response.

Parameters

Parameter	Type
payload	UiPromptPiaRequest

Returns

Promise<UiPromptPiaResponse>

Example

// Subscribe to PIA's streamed responses
const cleanup = await useUi().on(
  UI_MESSAGE_TYPES.UI_PROMPT_PIA_RESPONSE_STREAMED,
  async ({ chunk, partial_response, id }) => {
    console.log(`PIA response chunk for stream ${id}: ${chunk}`);
    console.log(`PIA response so far for stream ${id}: ${partial_response}`);
  }
);
// Prompt PIA with a question and ensure cleanup is called afterwards
useUi().promptPia({ prompt: "What's my most presented file?", id: 'my-prompt-id-to-discern-with-stream-event' })
  .finally(cleanup);

ui.resumeMeeting()

resumeMeeting(): Promise<void>

Resumes the meeting and attempts to go at the last presented route / component.

Returns

Promise<void>

Example

useUi().resumeMeeting()

ui.selectAgendaContent()

selectAgendaContent(payload?): Promise<UiSelectAgendaResponse>

Opens the agenda selector modal to allow the user to select agenda content and handle the outcome.

const api = useApi() // or useUi() if you know that you 're in UI context

uiApi.selectAgendaContent({
 // optional payload
 initial_agenda: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	UiSelectAgendaRequest

Returns

Promise<UiSelectAgendaResponse>

ui.selectCanvases()

selectCanvases(payload?): Promise<UiSelectCanvasesResponse>

Allows the user to select (and preselect) canvases from the instance.

This method allows you to prompt the user to select canvases from the CatalogIQ instance and use that canvas selection in your application.

Parameters

Parameter	Type	Description
payload	UiSelectCanvasesRequest	optional payload to preselect specific canvases

Returns

Promise<UiSelectCanvasesResponse>

Promise with the user action and selected canvases

Example

const api = useApi() // or useUi() if you know that you 're in UI context
api
  .selectCanvases({
    allowed_types: ['canvas','canvas-template','section','section-template'] // default ['canvas']
    selections: [
      { id: "01HCZ623YYRFJQ0F7B69VWE510" },
      { id: "02HCZ623YYRFJQ0F7B69VWE510" },
    ], // default []
  })

ui.selectCollectionContent()

selectCollectionContent(payload?): Promise<UiSelectCollectionPlayerResponse>

Opens the collection player selector modal to allow the user to select collection player content and handle the outcome.

const api = useApi() // or useUi() if you know that you 're in UI context

uiApi.selectCollectionContent({
 // optional payload
 initial_data: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	UiSelectCollectionPlayerRequest

Returns

Promise<UiSelectCollectionPlayerResponse>

ui.selectContent()

selectContent(payload?): Promise<UiSelectContentResponse>

Allows the user to select (and preselect) content from the instance.

Opens the content selector dialog to allow the user to select content and handle the outcome. This method allows you to prompt the user to select content from the CatalogIQ instance and use that content in your application.

Parameters

Parameter	Type	Description
payload	UiSelectContentRequest	optional payload to preselect specific content

Returns

Promise<UiSelectContentResponse>

Promise with the user action and selected content

Example

const api = useApi() // or useUi() if you know that you 're in UI context
api
  .selectContent({
    selections: [
      { fileId: "01HCZ623YYRFJQ0F7B69VWE510", type: "file" },
      {
        fileId: "01HD3XGZ5FN90QJGK7CH8TBZDF",
        type: "page",
        pageIndex: 2,
      },
    ],
  })

ui.setPostcallStyle()

setPostcallStyle(payload): Promise<void>

Change the height of the postcall form.

Parameters

Parameter	Type
payload	UiSetPostcallStyleRequest

Returns

Promise<void>

Example

useUi().setPostcallStyle({ height: 100 })

ui.stopMeeting()

stopMeeting(): Promise<void>

Ends current meeting and shows postcall form.

Returns

Promise<void>

Example

useUi().stopMeeting()

ui.toast()

toast(payload): Promise<void>

Show a toast message to the user.

Parameters

Parameter	Type
payload	UiToastRequest

Returns

Promise<void>

Example

useUi().toast({ type: 'info', message: 'Hello, world!' })

ui.updateCanvas()

updateCanvas(payload): Promise<CanvasRetrieve>

Modify the currently loaded canvas. On the web it sends an update_canvas request to the server.

Parameters

Parameter	Type	Description
payload	UiUpdateCanvasRequest	parts of the canvas object to update with fields to return

Returns

Promise<CanvasRetrieve>

ui.updateLocation()

updateLocation(payload): Promise<any>

Navigate to another page in the CatalogIQ instance.

Parameters

Parameter	Type
payload	UpdateLocationPitcherEvent

Returns

Promise<any>

Example

const canvasId = '1234567890abcdef12345678' // obtain target canvasId
useUi().updateLocation({
  action: 'restore',
  routes: {
    'slotty-ui': {
      path: '/canvases/saved-canvases/' + canvasId + '/build/present',
      query: {},
    },
  },
})

uiBroadcast

uiBroadcast: object

unsubscribe

unsubscribe: () => Promise<any>

Unsubscribe from updates.

Returns

Promise<any>

aiComplete()

aiComplete(payload): Promise<AICompleteResult>

Run an AI completion on the on-device model (iOS only). On web the host rejects with a clear error — use piaSearchAnswer (or the next-core AI routes) for online inference instead.

The payload is the EXACT iOS wire contract: { prompt, max_tokens?, stream? } → { text, tokens_generated, elapsed_seconds, time_to_first_token_seconds }.

Parameters

Parameter	Type	Description
payload	AICompletePayload	The completion payload.

Returns

Promise<AICompleteResult>

• Promise resolving with the completion.

Example

const completion = await api.aiComplete({ prompt: 'Summarize ...', max_tokens: 256 })
console.log(completion.text)

aiGetCapabilities()

aiGetCapabilities(): Promise<AIRuntimeCapabilities>

Capabilities of the AI completion runtime on the current platform.

On iOS this asks the native on-device bridge (ai.get_capabilities); on web it resolves statically to the online (Bedrock) runtime — no postMessage round-trip.

Returns

Promise<AIRuntimeCapabilities>

• Promise resolving with the runtime capabilities.

Example

const capabilities = await api.aiGetCapabilities()
if (capabilities.available) { ... }

appFullscreenChange()

appFullscreenChange(payload): Promise<void>

Tell the CatalogIQ UI that the app is showing something fullscreen, or has stopped. While the app reports is_fullscreen: true, the UI lays the app's page over its own top bar and sidebar, so content the app draws over its whole window covers the whole screen. Report is_fullscreen: false as soon as the app leaves fullscreen: the UI shows no exit of its own while covered.

For now the UI honours it only from the Canvas Renderer app (canvas-renderer) opened as a page of the UI's sidebar (ui_app module), which sends it while a collection player in its canvas is fullscreen, so that no app that misses its false can leave the rep stuck until Pitcher is relaunched. From any other app, and anywhere else such as an app embedded in a canvas, the message is ignored, as it is by a UI that predates it. It does not use the browser's Fullscreen API.

Parameters

Parameter	Type	Description
payload	UiAppFullscreenChangeRequest	object saying whether the app is now fullscreen

Returns

Promise<void>

Example

useUi().appFullscreenChange({ is_fullscreen: true })
// later, when the app leaves fullscreen
useUi().appFullscreenChange({ is_fullscreen: false })

appLoaded()

appLoaded(): Promise<void>

Notify the CatalogIQ instance that the app is loaded and ready to get the data. Triggering this method will trigger the on_app_set_data event.

Returns

Promise<void>

Examples

useUi().appLoaded()

appResize()

appResize(payload): Promise<void>

Resize the app iframe to a given height.

Note that initial iframe height comes from the app.json manifest file. It can also be adjusted by the user when adding app component to the canvas. In case when the app must be temporarily resized to show larger ui elements it can read the user-set height from the on_app_set_data event.

Parameters

Parameter	Type	Description
payload	UiAppResizeRequest	object containing requested height of the iframe as the number of pixels

Returns

Promise<void>

appsDbDeleteEntry()

appsDbDeleteEntry(payload): Promise<void>

Deletes an AppsDB entry (soft delete server-side), adapting to the platform:

• Web: DELETE to the next-core AppsDB REST API.
• Native (iPad or desktop): the appsdb_delete_entry bridge request deletes on the server and removes the entry from the local offline mirror. Offline it rejects with code = offline_write_not_supported.

Parameters

Parameter	Type
payload	AppsDbDeleteEntryPayload

Returns

Promise<void>

Example

await api.appsDbDeleteEntry({ id: '01H5ZXE7YP2JR6Q1Z2G3K4H5J6' })

appsDbGetEntries()

appsDbGetEntries(payload): Promise<AppsDbEntriesResult>

Lists AppsDB entries of a type, adapting to the platform:

• Web: GET to the next-core AppsDB REST API.
• Native (iPad or desktop): reads the local offline mirror via the appsdb_get_entries bridge request. Types not allowlisted in the offline_appsdb_types setting fail with code = type_not_synced and automatically fall back to the network.

Parameters

Parameter	Type
payload	AppsDbGetEntriesPayload

Returns

Promise<AppsDbEntriesResult>

Example

const { entries } = await api.appsDbGetEntries({ type: 'favorite' })

appsDbPsql()

appsDbPsql(payload): Promise<AppsDbEntriesResult>

Runs a PSQL (SQL-like) query against AppsDB: POST to the next-core /appsdb/psql endpoint whenever the network is available.

On a native host the local offline mirror (appsdb_get_entries + client-side evaluation of simple field = literal AND-chains) serves the query ONLY while the device is offline, or when an online fetch fails at the connection level. Online queries are always answered by the server: Hub flows use psql results to decide between creating and updating an entry, and the mirror can lag the server by a sync cycle (multi-device) — a stale empty read would turn an update into a duplicate create. Offline that same stale read is harmless because AppsDB writes are rejected offline anyway.

Parameters

Parameter	Type
payload	AppsDbPsqlPayload

Returns

Promise<AppsDbEntriesResult>

Example

const { entries } = await api.appsDbPsql({
  query: "SELECT * FROM personalfolders WHERE user_id = 1 AND data.custom_domain = 'acme.my.pitcher.com'",
})

appsDbUpsertEntry()

appsDbUpsertEntry(payload): Promise<AppsDbEntry>

Creates or updates (deep-merges) an AppsDB entry, adapting to the platform:

• Web: POST (create) or PUT (update, when id is set) to the next-core AppsDB REST API.
• Native (iPad or desktop): the appsdb_upsert_entry bridge request writes on the server and mirrors the authoritative result locally. Offline it rejects with code = offline_write_not_supported — AppsDB writes are online-only.

The data blob is sent verbatim (no key-casing transformation), and all appsDb* responses are likewise returned verbatim — even for casing: 'camel' consumers — so bridge and REST results are identical.

Parameters

Parameter	Type
payload	AppsDbUpsertEntryPayload

Returns

Promise<AppsDbEntry>

Example

const entry = await api.appsDbUpsertEntry({ type: 'favorite', user_id: 1, data: { file_id: 'abc' } })

assignCanvasTheme()

assignCanvasTheme(payload): Promise<{ canvas_id: string; theme_id: string; }>

Parameters

Parameter	Type
payload	{ canvas_id: string; theme_id: string; }
payload.canvas_id	string
payload.theme_id	string

Returns

Promise<{ canvas_id: string; theme_id: string; }>

cancelMeeting()

cancelMeeting(): Promise<void>

Cancels current meeting and the event remains unrealized (like it never happened).

Returns

Promise<void>

Example

useUi().cancelMeeting()

canvasNavigateNextPage()

canvasNavigateNextPage(): Promise<void>

Navigate to the next page in the current canvas. Noop if the current page is the last one.

Returns

Promise<void>

Example

useUi().canvasNavigateNextPage()

canvasNavigatePage()

canvasNavigatePage(payload): Promise<void>

Navigate to a specific canvas place in the current canvas. Despite the event and parameter name, it takes the component id that we want to put in view.

Parameters

Parameter	Type
payload	UiCanvasNavigatePageRequest

Returns

Promise<void>

Example

const uiApi = useUi() // our useApi()

let activeCanvas = null
const unsubscribe = uiApi.on_app_set_data((data) => {
  activeCanvas = data?.canvas
})

document.getElementById('my-button').addEventListener('click', () => {
  const target = activeCanvas?.content?.data?.find((i: any) => i.data.app_name === 'my-target-app-id') || null
  if (target) {
    uiApi.canvasNavigatePage({ page: target.id })
  }
})

canvasNavigatePreviousPage()

canvasNavigatePreviousPage(): Promise<void>

Navigate to the previous page in the current canvas. Noop if the current page is the first one.

Returns

Promise<void>

Example

useUi().canvasNavigatePreviousPage()

captureAppError()

captureAppError(payload): Promise<void>

Send an app error to Pitcher sentry instance.

Sentry files it under one issue per app + message and tags it app_name, so send your app's name as app_name (app is also read) and a stable message, and keep ids and other varying values in other fields. Without a name the error groups under unknown with every other unnamed app's. The whole payload is attached to the event.

Parameters

Parameter	Type	Description
payload	UiCaptureAppErrorRequest	error object to send to Pitcher sentry instance

Returns

Promise<void>

Example

try {
  throw new Error('This is an error')
} catch (error) {
  useUi().captureAppError({
    app_name: 'my-app',
    message: 'Failed to load accounts',
    stack: error instanceof Error ? error.stack : String(error),
  })
}

close()

close(): Promise<any>

Returns

Promise<any>

closeCanvasDrawer()

closeCanvasDrawer(): Promise<void>

Close the Canvas Drawer modal. Only takes effect for apps running in canvas_drawer embed location

Note that this method simply closes the drawer and will result in the app calling it being unmounted from the DOM and destroyed. Make sure your app has finished updating data before you call this method.

Returns

Promise<void>

Example

useUi().closeCanvasDrawer()

closeCanvasSectionExecution()

closeCanvasSectionExecution(): Promise<void>

Close the Canvas Section Execution modal. Only takes effect for canvas_section_execution app modules

Note that this method simply closes the modal and will result in the app calling it being unmounted from the DOM and destroyed. Make sure your app has finished updating data before you call this method.

Returns

Promise<void>

Example

useUi().closeCanvasSectionExecution()

closeGlobalPopup()

closeGlobalPopup(): Promise<void>

Closes the currently open global popup app.

Returns

Promise<void>

Example

const api = useApi()
api.closeGlobalPopup()

completePostcall()

completePostcall(payload): Promise<void>

Completes the postcall stage (with successful submission or not)

Parameters

Parameter	Type
payload	UiCompletePostcallRequest

Returns

Promise<void>

Example

useUi().completePostcall({ was_successfully_submitted: true })

createCanvas()

createCanvas(payload): Promise<CanvasRetrieve>

Parameters

Parameter	Type
payload	Omit<CanvasCreateRequest, "instance_id">

Returns

Promise<CanvasRetrieve>

createFile()

createFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	Omit<AllFileCreateRequest, "instance_id">

Returns

Promise<FileRetrieve>

createFolder()

createFolder(payload): Promise<FolderRetrieve>

Creates a new folder.

Parameters

Parameter	Type	Description
payload	Omit<FolderCreateRequest, "instance_id">	The folder creation request payload, excluding the instance_id.

Returns

Promise<FolderRetrieve>

A promise that resolves to the created folder.

crmCreate()

crmCreate(payload): Promise<any>

Creates new records in CRM (Web only). Uses Salesforce REST API to create records.

Parameters

Parameter	Type	Description
payload	CRMCreatePayload	The create payload containing sobject type and records.

Returns

Promise<any>

• Promise resolving with the result of the create operation.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to create CRM records.
api.crmCreate({
  sobject: 'Order__c',
  records: [
    { Account__c: '001xx000003DGbQAAW', Order_Date__c: '2024-01-15' },
    { Account__c: '001xx000003DGbRABW', Order_Date__c: '2024-01-16' }
  ]
})

crmDescribe()

crmDescribe(payload): Promise<any>

Retrieves metadata/describe for a CRM object (Web only). Uses Salesforce REST API to fetch object metadata including fields and picklist values.

Parameters

Parameter	Type	Description
payload	CRMDescribePayload	The describe payload containing the sobject name.

Returns

Promise<any>

• Promise resolving with the object metadata including fields and picklist values.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to get CRM object metadata.
api.crmDescribe({ sobject: 'Account' })
  .then(metadata => {
    // Access fields
    console.log(metadata.fields)
    // Access picklist values for a specific field
    const industryField = metadata.fields.find(f => f.name === 'Industry')
    console.log(industryField.picklistValues)
  })

crmLayout()

crmLayout(payload): Promise<any>

Retrieves layout information for a CRM object (Web only). Uses Salesforce REST API to fetch object layout including sections, fields arrangement, and form factors.

Parameters

Parameter	Type	Description
payload	CRMLayoutPayload	The layout payload containing the sobject name and optional layout parameters.

Returns

Promise<any>

• Promise resolving with the object layout information.

Throws

• Throws an error if the payload is invalid.

Examples

// Web only method to get CRM object layout.
api.crmLayout({ sobject: 'Account' })
  .then(layout => {
    // Access layout sections
    console.log(layout.editLayoutSections)
  })

// Get layout with specific form factor, mode, and record type.
api.crmLayout({
  sobject: 'Account',
  form_factor: 'Large',
  mode: 'Edit',
  record_type_id: '012xx0000004ABC'
})

crmQuery()

crmQuery(payload): Promise<any>

Parameters

Parameter	Type
payload	CRMQueryPayload

Returns

Promise<any>

crmQueryAdaptive()

crmQueryAdaptive(payload): Promise<any>

Executes a CRM query with automatic iOS/SmartStore adaptation.

On iOS devices with the 'sfdc_offline_enabled' LaunchDarkly flag enabled, this function automatically converts SOQL queries to SmartStore Smart SQL format and uses the local SmartStore for offline data access. On other platforms or when the flag is disabled, it uses the standard CRM query API.

Parameters

Parameter	Type	Description
payload	CRMQueryPayload	The query payload containing the SOQL query string.

Returns

Promise<any>

• Promise resolving with query results.

Example

// Works on all platforms - automatically adapts for iOS with sfdc_offline_enabled LD flag
const result = await crmQueryAdaptive({ query: 'SELECT Id, Name FROM Account WHERE Active = true' })

crmSmartDeleteObjects()

crmSmartDeleteObjects(payload): Promise<any>

Deletes CRM objects from local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to delete records. Each object in the payload specifies a table name and an array of IDs to delete.

Parameters

Parameter	Type	Description
payload	CRMSmartDeleteObjectsPayload	The delete payload containing an array of CRMDeleteObject items.

Returns

Promise<any>

• Promise resolving with the result of the delete operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to delete CRM objects.
api.crmSmartDeleteObjects({
  objects: [
    {
      table_name: 'Account',
      ids: ['001xx000003DGbQAAW', '001xx000003DGbRABW']
    },
    {
      table_name: 'Contact',
      ids: ['003xx000004TmiQAAS']
    }
  ]
})

crmSmartObjectLayout()

crmSmartObjectLayout(payload): Promise<any>

Retrieves layout information for a CRM smart object (iOS only). Fetches object layout metadata from the Salesforce Mobile SDK cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectLayoutPayload	The payload containing the object name and optional layout parameters.

Returns

Promise<any>

• Promise resolving with the object layout metadata.

Throws

• Throws an error if the object name is not provided.

Examples

// iOS only method to retrieve CRM object layout.
api.crmSmartObjectLayout({ object: 'Account' })

// Get layout with specific form factor and mode.
api.crmSmartObjectLayout({ object: 'Account', form_factor: 'Large', mode: 'Edit' })

crmSmartObjectMetadata()

crmSmartObjectMetadata(payload): Promise<any>

Retrieves metadata for a CRM smart object (iOS only). Fetches object metadata from the Salesforce Mobile SDK cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectMetadataPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the object metadata.

Throws

• Throws an error if the object name is not provided.

Example

// iOS only method to retrieve CRM object metadata.
api.crmSmartObjectMetadata({ object: 'Account' })

crmSmartObjectValidationRules()

crmSmartObjectValidationRules(payload): Promise<any>

Retrieves validation rules for a CRM smart object (iOS only). This method fetches the validation rules configured for a specific CRM object type from the local SmartStore cache.

Parameters

Parameter	Type	Description
payload	CRMSmartObjectValidationRulesPayload	The payload containing the object name.

Returns

Promise<any>

• Promise resolving with the validation rules for the specified object.

Examples

// iOS only method to get validation rules for an Account object.
api.crmSmartObjectValidationRules({ object: 'Account' })

// Get validation rules for a Contact object.
api.crmSmartObjectValidationRules({ object: 'Contact' })

crmSmartQuery()

crmSmartQuery(payload): Promise<any[]>

Executes a SmartStore query against local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore query syntax. Validates that the query uses SmartStore syntax before execution.

Parameters

Parameter	Type	Description
payload	CRMQueryPayload	The query payload containing the SmartStore query string.

Returns

Promise<any[]>

• Promise resolving with an array of query results from SmartStore.

Throws

• Throws an error if the query is not a valid SmartStore query.

Example

// iOS only method to execute a SmartStore query.
api.crmSmartQuery({ query: 'SELECT {Account:Id}, {Account:Name} FROM {Account} ORDER BY {Account:Name} LIMIT 10' })

crmSmartUpsertObjects()

crmSmartUpsertObjects(payload): Promise<any>

Upserts CRM objects into local CRM data (iOS only). Uses Salesforce Mobile SDK SmartStore to insert or update records. Each object in the payload specifies a table name, the objects to upsert, and an optional external ID path.

Important: Always provide external_id_path when performing updates to ensure records are matched correctly. Without it, the operation may create duplicate records instead of updating existing ones.

Note: When creating new records, you must provide an explicit identifier field (e.g., Id) in each record object passed from the frontend. The backend does not auto-generate IDs.

Parameters

Parameter	Type	Description
payload	UpsertCRMObjectsPayload	The upsert payload containing an array of UpsertCRMObject items.

Returns

Promise<any>

• Promise resolving with the result of the upsert operation.

Throws

• Throws an error if the payload is invalid.

Example

// iOS only method to upsert CRM objects.

// Updating existing records - always include external_id_path
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [{ Id: '001xx000003DGbQAAW', Name: 'Acme Corp Updated' }],
      external_id_path: 'Id' // Required for updates to match existing records
    }
  ]
})

// Creating new records - explicit ID required in each record
api.crmSmartUpsertObjects({
  objects: [
    {
      table_name: 'Account',
      objects: [
        { Id: '001xx000003NEW001', Name: 'New Company' }, // Explicit ID required
        { Id: '001xx000003NEW002', Name: 'Another Company' }
      ]
    }
  ]
})

crmUpsert()

crmUpsert(payload): Promise<any>

Upserts records in CRM (Web only). Uses Salesforce REST API to insert or update records based on external ID. If a record with matching external ID exists, it will be updated; otherwise, a new record is created.

Parameters

Parameter	Type	Description
payload	CRMUpsertPayload	The upsert payload containing sobject type, records, and external ID field.

Returns

Promise<any>

• Promise resolving with the result of the upsert operation.

Throws

• Throws an error if the payload is invalid.

Example

// Web only method to upsert CRM records.
api.crmUpsert({
  sobject: 'Order__c',
  records: [
    { External_Id__c: 'ORD-001', Account__c: '001xx000003DGbQAAW', Status__c: 'Submitted' },
    { External_Id__c: 'ORD-002', Account__c: '001xx000003DGbRABW', Status__c: 'Draft' }
  ],
  external_id_field: 'External_Id__c'
})

deleteCanvas()

deleteCanvas(payload): Promise<CanvasRetrieve>

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<CanvasRetrieve>

deleteFile()

deleteFile(payload): Promise<string>

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<string>

deleteFolder()

deleteFolder(payload): Promise<void>

Deletes a folder.

Parameters

Parameter	Type	Description
payload	{ folder_id: string; }	An object containing the ID of the folder to delete.
payload.folder_id	string	The ID of the folder to delete.

Returns

Promise<void>

A promise that resolves when the folder is deleted.

deleteLocalFile()

deleteLocalFile(payload): Promise<void>

Deletes a local file on iOS devices from Pitcher Folders.

Parameters

Parameter	Type
payload	{ url: string; }
payload.url	string

Returns

Promise<void>

Example

// iOS only method to delete a local file.
api.deleteLocalFile({ url: 'file:///var/mobile/Containers/Data/Application/x/Documents/Pitcher%20Folders/ARPhotocapture/x.png' })

disablePostcallSubmit()

disablePostcallSubmit(): Promise<void>

Mark the postcall form as not possible to submit by the user. Useful while processing the form data.

Returns

Promise<void>

Deprecated

Example

useUi().disablePostcallSubmit()

downloadFile()

downloadFile(payload): Promise<null>

Parameters

Parameter	Type
payload	{ file_id: string; }
payload.file_id	string

Returns

Promise<null>

embeddableReady()

embeddableReady(): Promise<void>

This event is used for appJson.module.canvas.start_in_loading_mode: true apps. A loading curtain is displayed until you call this event.

Returns

Promise<void>

Example

useUi().embeddableReady()

enablePostcallSubmit()

enablePostcallSubmit(): Promise<void>

Mark the postcall form as possible to submit by the user.

Returns

Promise<void>

Deprecated

Example

useUi().enablePostcallSubmit()

fetchDocumentInfo()

fetchDocumentInfo(payload): Promise<{[key: string]: unknown; pageCount: number; }>

Parameters

Parameter	Type
payload	{ fileId: string; }
payload.fileId	string

Returns

Promise<{[key: string]: unknown; pageCount: number; }>

Deprecated

• not used anymore

getAppConfig()

getAppConfig(payload?): Promise<Record<string, any>>

Parameters

Parameter	Type
payload?	{ app_name?: string; }
payload.app_name?	string

Returns

Promise<Record<string, any>>

getCanvas()

getCanvas(payload): Promise<CanvasRetrieve>

Fetches a single canvas by ID.

Pass lazy_sections: true to request the opt-in lazy "shell": when the org/instance lazy_load_sections setting is also on, the response returns ordered section_ids instead of the heavy inline sections, and you hydrate section bodies on demand via getSectionsByIds. With the setting off (or the param omitted) the response is the legacy fully-expanded canvas.

Parameters

Parameter	Type	Description
payload	{ fields?: string; id: string; lazy_sections?: boolean; skip_error_toast?: boolean; }	-
payload.fields?	string	-
payload.id	string	-
payload.lazy_sections?	boolean	-
payload.skip_error_toast?	boolean	Suppress the host's error toast for best-effort reads (e.g. download-completion polling).

Returns

Promise<CanvasRetrieve>

getCanvases()

getCanvases(payload): Promise<PaginatedData<CanvasRetrieve>>

Fetches a list of canvases to use in your app.

Parameters

Parameter	Type
payload	GetCanvasesParams & object

Returns

Promise<PaginatedData<CanvasRetrieve>>

Example

// The `filters` object is a reserved payload key to transfer the metadata dict over the wire.
api.getCanvases({
  search: 'my search query',
  ordering: '-created_at',
  filters: {
    metadata__mydaterangefiltername__range: ['2023-12-10', '2023-12-22'],
    metadata__mymultiselectfiltername: ['optionAValue', 'optionCValue'],
  },
 fields: 'id,name,metadata',
})

getCanvasRecommendedFiles()

getCanvasRecommendedFiles(payload): Promise<CanvasRecommendedFiles>

Parameters

Parameter	Type
payload	{ canvas_id: string; match?: ("metadata" | "tags")[]; }
payload.canvas_id	string
payload.match?	("metadata" | "tags")[]

Returns

Promise<CanvasRecommendedFiles>

getCanvasTheme()

getCanvasTheme(payload): Promise<CanvasThemeRetrieve | null>

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<CanvasThemeRetrieve | null>

getCoreFolders()

getCoreFolders(payload): Promise<CoreFolderContentsRetrieve>

Parameters

Parameter	Type
payload	{ entity: CoreFolderEntityType; instance_id: string; parent_id?: string | null; }
payload.entity	CoreFolderEntityType
payload.instance_id	string
payload.parent_id?	string | null

Returns

Promise<CoreFolderContentsRetrieve>

getEnv()

getEnv(): Promise<PitcherEnv>

Fetches the necessary info for the app to know where it is embedded.

It contains information about:

• user
• instance
• organization
• security token to query Pitcher REST API
• Salesforce connection information (if connected) including security token to query Salesforce REST API
• Auth0 token information

Returns

Promise<PitcherEnv>

Example

const env = usePitcherApi().getEnv().then((env) => {
  console.log(env.pitcher.user.name)
})

getFile()

getFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	{ file_id?: string; id?: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRetrieve>

getFileRevisionData()

getFileRevisionData(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	{ file_id: string; revision_id: string; }
payload.file_id	string
payload.revision_id	string

Returns

Promise<FileRetrieve>

getFileRevisions()

getFileRevisions(payload): Promise<FileRevision[]>

Parameters

Parameter	Type
payload	{ file_id?: string; id?: string; }
payload.file_id?	string
payload.id?	string

Returns

Promise<FileRevision[]>

getFiles()

getFiles(payload): Promise<PaginatedFileList>

Parameters

Parameter	Type
payload	Partial<Omit<File, "type">> & object & object

Returns

Promise<PaginatedFileList>

getFolder()

getFolder(payload?): Promise<FolderRetrieve>

Retrieves a folder by its ID.

Parameters

Parameter	Type	Description
payload	{ id: string; }	An object containing the folder ID.
payload.id	string	The ID of the folder to retrieve. Defaults to 'root'.

Returns

Promise<FolderRetrieve>

A promise that resolves to the retrieved folder.

getFolders()

getFolders(payload): Promise<PaginatedFolderList>

Retrieves a list of folders.

Parameters

Parameter	Type	Description
payload	FolderListRequest	The payload containing the search, ordering, filters, fields, name, page, and page_size.

Returns

Promise<PaginatedFolderList>

A promise that resolves to the list of folders.

getInstanceMetadataTemplates()

getInstanceMetadataTemplates(payload?): Promise<PaginatedMetadataTemplateList>

Parameters

Parameter	Type
payload?	GetInstanceMetadataTemplatesPayload

Returns

Promise<PaginatedMetadataTemplateList>

getSectionsByIds()

getSectionsByIds(payload): Promise<{ sections: CanvasSection[]; }>

Batch-hydrate section bodies for a canvas fetched as a lazy shell.

Companion to getCanvas({ lazy_sections: true }): pass the canvas ID and a slice of its section_ids (≤100 per call) and receive the full section bodies, serialized identically to a normal canvas retrieve's inline sections. Only sections actually referenced by the canvas are returned.

Pass the SAME exclude_drafts / include_expired_files / include_pending_files the shell was fetched with so hydration filters identically to the shell that advertised the IDs — otherwise admin decks (fetched with exclude_drafts:false, expired/pending on) list draft/expired sections the batch would silently drop, leaving them blank. Omit them to get the rep defaults (drafts excluded, expired/pending off). include_expired_files/include_pending_files are server-side role-gated (admin/editor only), matching the inline retrieve.

Parameters

Parameter	Type
payload	{ canvas_id: string; exclude_drafts?: boolean; include_expired_files?: boolean; include_pending_files?: boolean; section_ids: string[]; }
payload.canvas_id	string
payload.exclude_drafts?	boolean
payload.include_expired_files?	boolean
payload.include_pending_files?	boolean
payload.section_ids	string[]

Returns

Promise<{ sections: CanvasSection[]; }>

Example

const { sections } = await api.getSectionsByIds({
  canvas_id: '01HH4RCBH631K4JDHWAQB0RPR6',
  section_ids: ['01SEC...', '02SEC...'],
})

getThemes()

getThemes(payload): Promise<CanvasThemeRetrieve[]>

Parameters

Parameter	Type
payload	Partial<CanvasThemeRetrieve>

Returns

Promise<CanvasThemeRetrieve[]>

getUsers()

getUsers(payload?): Promise<PaginatedData<User>>

Parameters

Parameter	Type
payload?	GetUsersParams

Returns

Promise<PaginatedData<User>>

isOffline()

isOffline(): Promise<boolean>

Returns

Promise<boolean>

moveFolderItems()

moveFolderItems(payload): Promise<FolderRetrieve>

Moves items (files or folders) to a target folder.

Parameters

Parameter	Type	Description
payload	{ items: object[]; target_folder_id: string; }	The payload containing the target folder ID and items to move.
payload.items	object[]	An array of items to move, each with an ID and type.
payload.target_folder_id	string	The ID of the target folder.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated target folder.

notify()

notify(payload): Promise<void>

Parameters

Parameter	Type
payload	NotificationPayload

Returns

Promise<void>

open()

open(payload): Promise<void>

Open a file in the CatalogIQ instance.

Parameters

Parameter	Type
payload	UiOpenRequest

Returns

Promise<void>

openCanvasOverlay()

openCanvasOverlay(payload): Promise<void>

Opens a modal to view a canvas by ID.

onMounted(() => {
  uiApi.openCanvasOverlay({
    id: '01HH4RCBH631K4JDHWAQB0RPR6',
    edit_mode: false,
    fullscreen: true,
  })
})

You can also specify a position for the canvas overlay:

uiApi.openCanvasOverlay({
  id: '01HH4RCBH631K4JDHWAQB0RPR6',
  position: {
    top: '10px',
    left: '20px',
    right: '20px',
    bottom: '10px'
  }
})

If your app just created this canvas and is opening it only so the rep can run its completion wizard, set discard_on_wizard_cancel so that cancelling the wizard deletes the empty shell instead of leaving it in the rep's pitchdecks:

const canvas = await api.createCanvas(...)
uiApi.openCanvasOverlay({ id: canvas.id, edit_mode: true, discard_on_wizard_cancel: true })

Pass it ONLY for a canvas created moments ago — never when re-opening one the rep already has.

If your app navigates the shell instead of opening an overlay (update_location to /canvases/saved-canvases/<id>/build/<mode>), the equivalent is the discard_on_wizard_cancel query param on that route: query: { discard_on_wizard_cancel: '1' }. Accepted opt-in values are '1', 'true', '' and a bare key; ANY other value is ignored and nothing is discarded, so a wrong guess no-ops rather than deleting a canvas.

Parameters

Parameter	Type	Description
payload	{ component_id?: string; discard_on_wizard_cancel?: boolean; edit_mode?: boolean; fullscreen?: boolean; id: string; position?: { bottom?: string | number; left?: string | number; right?: string | number; top?: string | number; }; section_id?: string; }	-
payload.component_id?	string	-
payload.discard_on_wizard_cancel?	boolean	PIT-8622 — delete this canvas if the rep cancels its completion wizard. Opt-in, for apps that POST the canvas themselves before handing it to the shell.
payload.edit_mode?	boolean	-
payload.fullscreen?	boolean	-
payload.id	string	-
payload.position?	{ bottom?: string | number; left?: string | number; right?: string | number; top?: string | number; }	-
payload.position.bottom?	string | number	-
payload.position.left?	string | number	-
payload.position.right?	string | number	-
payload.position.top?	string | number	-
payload.section_id?	string	-

Returns

Promise<void>

openCollectionPlayerOverlay()

openCollectionPlayerOverlay(payload): Promise<void>

Opens the collection player overlay to view a collection of files/slides.

This method opens the native Pitcher collection player interface with the specified files and slides. You can show entire files or specific pages from files.

Parameters

Parameter	Type	Description
payload	UiOpenCollectionPlayerOverlayRequest	Object containing groups array and collection name

Returns

Promise<void>

Example

// Open collection with full files
useUi().openCollectionPlayerOverlay({
  groups: [
    { id: 'file-123-abc', name: 'Product Overview' },
    { id: 'file-456-def', name: 'Pricing Slides' }
  ],
  name: 'Sales Deck'
})

// Open collection with specific slides/pages
useUi().openCollectionPlayerOverlay({
  groups: [
    {
      id: 'file-123-abc',
      name: 'Product Overview',
      slides: [
        { file_id: 'file-123-abc', slide_index: 0 },
        { file_id: 'file-123-abc', slide_index: 2 }
      ]
    }
  ],
  name: 'Custom Sales Presentation'
})

openExternalUrl()

openExternalUrl(payload): Promise<void>

Open external URL in a new tab. Works on both web and mobile.

Parameters

Parameter	Type
payload	OpenExternalUrlRequestPayload

Returns

Promise<void>

openGlobalPopup()

openGlobalPopup(appName, extraContext?): Promise<UiOpenGlobalPopupResponse>

Opens a global popup app by name.

Parameters

Parameter	Type	Description
appName	string	The name of the app to open (must have app_type: 'ui-global-popup')
extraContext?	Record<string, any>	Extra context to pass to the app

Returns

Promise<UiOpenGlobalPopupResponse>

Promise with the result of the operation

Example

const api = useApi()
api.openGlobalPopup('my-popup-app')
api.openGlobalPopup('my-popup-app', { customData: 'value' })

openSharingSettings()

openSharingSettings(payload): Promise<UiOpenSharingSettingsResponse>

Parameters

Parameter	Type
payload	UiOpenSharingSettingsRequest

Returns

Promise<UiOpenSharingSettingsResponse>

openWebViewAlwaysOnTop()

openWebViewAlwaysOnTop(payload): Promise<void>

Parameters

Parameter	Type
payload	OpenWebViewAlwaysOnTop

Returns

Promise<void>

patchCoreFolder()

patchCoreFolder(id, payload): Promise<CoreFolderContentsRetrieve>

Parameters

Parameter	Type
id	string
payload	Partial<CoreFolderRetrieve>

Returns

Promise<CoreFolderContentsRetrieve>

piaSearchAnswer()

piaSearchAnswer(payload): Promise<PiaSearchAnswerResult>

Answer a rep's natural-language question over the instance's content — the ONE high-level PIA Search call (PIT-6863). Routing follows the pia_search_config flag mode (see resolvePiaSearchMode):

• on_device on iOS with an available local model → aiComplete over the caller-assembled context_text (the Hub has the file metadata client-side). Unavailable/downloading models fall through to online.
• online (or any on-device fallback) → POST to the next-core pia-prepare/pia-search Bedrock route, which assembles its own candidate context server-side.
• off → rejects.

Parameters

Parameter	Type	Description
payload	PiaSearchAnswerPayload	The question + optional context/narrowing.

Returns

Promise<PiaSearchAnswerResult>

• Unified answer with the serving source.

Example

const result = await api.piaSearchAnswer({ query: 'What is our pricing for oncology?' })
console.log(result.answer, result.cited_file_ids, result.source)

postJsonWithTimeout()

postJsonWithTimeout<T>(url, body, accessToken, timeoutMs, label): Promise<T>

POST JSON to a next-core route with a hard deadline, returning the parsed body. The shared scaffold behind the SDK's online AI calls (piaSearchAnswer, weeklyFocusRank).

Bounds the WHOLE request including the body read: fetch() resolves on headers alone, so reading .json() INSIDE the timed window (and letting the abort cancel that read too — hence clearTimeout in finally) is what stops a response that stalls mid-body from hanging unbounded. label names the route in BOTH the non-2xx error (<label> <status>) and the timeout error, so each caller keeps its exact error strings.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
url	string
body	unknown
accessToken	string
timeoutMs	number
label	string

Returns

Promise<T>

preselectSfdcMeetingId()

preselectSfdcMeetingId(payload): Promise<UiPreselectSfdcMeetingIdResponse>

Preselect a meeting in the top meeting bar by Salesforce Meeting ID. From there, the user can easily start the meeting with a single click.

Parameters

Parameter	Type
payload	UiPreselectSfdcMeetingIdRequest

Returns

Promise<UiPreselectSfdcMeetingIdResponse>

Example

const objectFetchedFromSalesforce = {
  // fetch dynamically from Salesforce or provide in another way
  EventId: '00U1r00000D1J1zEAF',
}
ui.preselectSfdcMeetingId({ eventId: objectFetchedFromSalesforce.EventId }).then((response) => {
  // e.g. display advanced meeting details inside your app
  console.log(response.event)
})

printCanvas()

printCanvas(payload): Promise<UiPrintCanvasResponse>

Trigger async print/download of a canvas with optional notification URL. Calls the downloader-test endpoint to convert the canvas to PDF.

Parameters

Parameter	Type	Description
payload	UiPrintCanvasRequest	Canvas ID and optional notify URL for async notifications

Returns

Promise<UiPrintCanvasResponse>

Promise with job ID and success status

Example

useUi().printCanvas({
  id: '01HH4RCBH631K4JDHWAQB0RPR6',
  notify_url: 'https://my-webhook.example.com/canvas-ready'
})

promptPia()

promptPia(payload): Promise<UiPromptPiaResponse>

Sends a query to the Pitcher Intelligent Assistant (PIA) and handles the streamed response.

Parameters

Parameter	Type
payload	UiPromptPiaRequest

Returns

Promise<UiPromptPiaResponse>

Example

// Subscribe to PIA's streamed responses
const cleanup = await useUi().on(
  UI_MESSAGE_TYPES.UI_PROMPT_PIA_RESPONSE_STREAMED,
  async ({ chunk, partial_response, id }) => {
    console.log(`PIA response chunk for stream ${id}: ${chunk}`);
    console.log(`PIA response so far for stream ${id}: ${partial_response}`);
  }
);
// Prompt PIA with a question and ensure cleanup is called afterwards
useUi().promptPia({ prompt: "What's my most presented file?", id: 'my-prompt-id-to-discern-with-stream-event' })
  .finally(cleanup);

query()

query(payload): Promise<any>

Parameters

Parameter	Type
payload	QueryPayload

Returns

Promise<any>

refreshAccessToken()

refreshAccessToken(): any

Returns

any

refreshServiceToken()

refreshServiceToken(payload?): Promise<RefreshServiceTokenResponse>

Ask for a refreshed Salesforce token. In case the token hasn't expired yet, this method will return the same token as the current one found in the (getEnv)[#getenv] result.

Parameters

Parameter	Type
payload?	RefreshServiceTokenRequest

Returns

Promise<RefreshServiceTokenResponse>

Promise resolving to an object containing the token

renderPageAsImage()

renderPageAsImage(payload): Promise<ArrayBuffer>

Renders a page from a file together with annotations.

Parameters

Parameter	Type	Description
payload	{ documentId?: string; fileId: string; pageIndex: number; params: { width: number; } | { height: number; }; }	-
payload.documentId?	string	The ID of the document to render (optional). If not provided the fileId will be used.
payload.fileId	string	The ID of the file to render. Used when the documentId is not available.
payload.pageIndex	number	The index of the page to render.
payload.params	{ width: number; } | { height: number; }	The parameters to use for rendering the page.

Returns

Promise<ArrayBuffer>

A promise that resolves with the image as an ArrayBuffer.

Example

api.renderPageAsImage({
  fileId: '123456',
  documentId: '654321',
  pageIndex: 0,
  params: { width: 1920 },
})

resumeMeeting()

resumeMeeting(): Promise<void>

Resumes the meeting and attempts to go at the last presented route / component.

Returns

Promise<void>

Example

useUi().resumeMeeting()

search()

search(payload): Promise<any>

Parameters

Parameter	Type
payload	{ includeExpired?: boolean; query: string; }
payload.includeExpired?	boolean
payload.query	string

Returns

Promise<any>

selectAgendaContent()

selectAgendaContent(payload?): Promise<UiSelectAgendaResponse>

Opens the agenda selector modal to allow the user to select agenda content and handle the outcome.

const api = useApi() // or useUi() if you know that you 're in UI context

uiApi.selectAgendaContent({
 // optional payload
 initial_agenda: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	UiSelectAgendaRequest

Returns

Promise<UiSelectAgendaResponse>

selectCanvases()

selectCanvases(payload?): Promise<UiSelectCanvasesResponse>

Allows the user to select (and preselect) canvases from the instance.

This method allows you to prompt the user to select canvases from the CatalogIQ instance and use that canvas selection in your application.

Parameters

Parameter	Type	Description
payload	UiSelectCanvasesRequest	optional payload to preselect specific canvases

Returns

Promise<UiSelectCanvasesResponse>

Promise with the user action and selected canvases

Example

const api = useApi() // or useUi() if you know that you 're in UI context
api
  .selectCanvases({
    allowed_types: ['canvas','canvas-template','section','section-template'] // default ['canvas']
    selections: [
      { id: "01HCZ623YYRFJQ0F7B69VWE510" },
      { id: "02HCZ623YYRFJQ0F7B69VWE510" },
    ], // default []
  })

selectCollectionContent()

selectCollectionContent(payload?): Promise<UiSelectCollectionPlayerResponse>

Opens the collection player selector modal to allow the user to select collection player content and handle the outcome.

const api = useApi() // or useUi() if you know that you 're in UI context

uiApi.selectCollectionContent({
 // optional payload
 initial_data: {
  name: 'test',
  groups: []
 }
})

Parameters

Parameter	Type
payload	UiSelectCollectionPlayerRequest

Returns

Promise<UiSelectCollectionPlayerResponse>

selectContent()

selectContent(payload?): Promise<UiSelectContentResponse>

Allows the user to select (and preselect) content from the instance.

Opens the content selector dialog to allow the user to select content and handle the outcome. This method allows you to prompt the user to select content from the CatalogIQ instance and use that content in your application.

Parameters

Parameter	Type	Description
payload	UiSelectContentRequest	optional payload to preselect specific content

Returns

Promise<UiSelectContentResponse>

Promise with the user action and selected content

Example

const api = useApi() // or useUi() if you know that you 're in UI context
api
  .selectContent({
    selections: [
      { fileId: "01HCZ623YYRFJQ0F7B69VWE510", type: "file" },
      {
        fileId: "01HD3XGZ5FN90QJGK7CH8TBZDF",
        type: "page",
        pageIndex: 2,
      },
    ],
  })

selectDeviceFile()

selectDeviceFile(): Promise<DeviceFile>

Dispatches iOS native file selector and returns the selected file.

Returns

Promise<DeviceFile>

Example

// iOS only method to select a file from the device.
api.selectDeviceFile()

setPostcallStyle()

setPostcallStyle(payload): Promise<void>

Change the height of the postcall form.

Parameters

Parameter	Type
payload	UiSetPostcallStyleRequest

Returns

Promise<void>

Example

useUi().setPostcallStyle({ height: 100 })

share()

share(payload): Promise<ShareResponse>

Dispatch iOS sharing dialog.

Parameters

Parameter	Type
payload	SharePayload

Returns

Promise<ShareResponse>

Example

api.share({text: "example text", subject: "example subject"})

shareCanvas()

shareCanvas(payload): Promise<SharedLink>

Get (or create) the shared link for a canvas.

brand_id (PIT-7682, optional) names an entry in the instance's shared_link_brands setting and only takes effect when the link is created. Omit it and the server uses the brand the rep last used on that instance, falling back to the instance default — the behaviour quick-share, bulk-share and API-created links get. A host that does not forward it (the iOS bridge today) therefore still produces a correctly branded link, just without the rep's per-share choice.

Parameters

Parameter	Type
payload	{ brand_id?: string; id: string; }
payload.brand_id?	string
payload.id	string

Returns

Promise<SharedLink>

showPeerSession()

showPeerSession(payload): Promise<void>

Show peer session dialog with button coordinates, for local peer sharing feature.

Parameters

Parameter	Type
payload	ShowPeerSessionRequestPayload

Returns

Promise<void>

Example

api.showPeerSession({x: 100, y: 200})

showSyncbox()

showSyncbox(payload): Promise<void>

Parameters

Parameter	Type
payload	ShowSyncboxRequestPayload

Returns

Promise<void>

slideSearch()

slideSearch(payload): Promise<SlideSearchResult>

Rank the slides of one wizard template configuration for a query (PIT-9090) — the online slide_search AITask, for vanilla and headless consumers that can load this SDK. (The React completion wizard calls the route directly.)

The caller passes its own visible realm (visible_group_names + visible_slide_refs); the server narrows the configuration to it, drops whatever the caller's ACL hides, and reranks with one model call. Results are ordered best first. Rejects on a non-2xx (slide_search <status>) or after 30 s.

Parameters

Parameter	Type	Description
payload	SlideSearchPayload	The configuration, the visible realm and the query.

Returns

Promise<SlideSearchResult>

• Ranked slides, the mode used and the realm size.

Example

const { results } = await api.slideSearch({
  canvas_id: deckId,
  section_list_id: 'node_abc',
  visible_group_names: ['Efficacy', 'Safety'],
  visible_slide_refs: ['01K…', '01F…_page_3'],
  query: 'which slides cover renal dosing?',
})

stopMeeting()

stopMeeting(): Promise<void>

Ends current meeting and shows postcall form.

Returns

Promise<void>

Example

useUi().stopMeeting()

sttAvailability()

sttAvailability(): Promise<SttAvailabilityResult>

Check whether dictation can be offered — a side-effect-free capability probe to gate a mic button. Does NOT prompt for the microphone or download a model. Answered by the native bridge on iOS and the Impact host on web.

Returns

Promise<SttAvailabilityResult>

{ available, engine, reason? } — available is true only when the feature is enabled AND an engine can run; engine is what would answer sttStart ("webspeech" sends audio off-device); reason is "disabled" or "unsupported" when not available.

Example

const { available, engine } = await api.sttAvailability()
if (available) showMicButton({ warnCloud: engine === 'webspeech' })

sttErrorCode()

sttErrorCode(error): SttErrorCode | undefined

Extract the SttErrorCode from a rejected sttStart / sttStop, normalizing across hosts: the iOS bridge rejection (error_code / errorCode) and Impact web's { reason } / error message string. Returns undefined if no known code is present.

Parameters

Parameter	Type
error	unknown

Returns

SttErrorCode | undefined

Example

try { await api.sttStart({ session_id }) } catch (err) {
  if (api.sttErrorCode(err) === 'STT_BUSY') showMicInUseHint()
}

sttStart()

sttStart(payload): Promise<void>

Parameters

Parameter	Type
payload	SttStartPayload

Returns

Promise<void>

sttStop()

sttStop(payload): Promise<SttStopResult>

Finalize a dictation session. Resolves with the final full transcript; rejects with STT_NOT_RECORDING if the session isn't active.

Parameters

Parameter	Type	Description
payload	SttStopPayload	-

Returns

Promise<SttStopResult>

The final { transcript }.

Example

const { transcript } = await api.sttStop({ session_id: 'notes-1' })

sttWarmup()

sttWarmup(): Promise<void>

Pre-load the on-device dictation model so a later sttStart resolves instantly (and the mic-permission prompt appears immediately instead of after a download). Web only — on iOS the native side manages its own model lifecycle, so the bridge has no stt.warmup type and calling it there rejects requestTypeDoesNotExists.

Fire-and-forget: don't block your UI on it and ignore rejections. It is idempotent (repeated / concurrent calls collapse to a single download) and a no-op when the feature is disabled or the engine has nothing to warm (Web Speech fallback). Call it right after sttAvailability reports available with engine === 'whisper'.

Returns

Promise<void>

Resolves once the model is ready (or immediately when there's nothing to warm).

Example

const { available, engine } = await api.sttAvailability()
if (available) {
  showMicButton()
  if (engine === 'whisper') api.sttWarmup().catch(() => {}) // background, non-blocking
}

submitUserFeedback()

submitUserFeedback(payload): Promise<any>

Submit user feedback

Parameters

Parameter	Type
payload	SubmitUserFeedbackPayload

Returns

Promise<any>

toast()

toast(payload): Promise<void>

Show a toast message to the user.

Parameters

Parameter	Type
payload	UiToastRequest

Returns

Promise<void>

Example

useUi().toast({ type: 'info', message: 'Hello, world!' })

track()

track(payload): Promise<any>

Parameters

Parameter	Type
payload	{ event_name: string; payload: any; }
payload.event_name	string
payload.payload	any

Returns

Promise<any>

triggerNonFilesSync()

triggerNonFilesSync(): Promise<void>

Dispatches iOS only sync method for non-files.

Returns

Promise<void>

Example

// iOS only method to sync non-files from the server.
api.triggerNonFilesSync()

ttsErrorCode()

ttsErrorCode(error): TtsErrorCode | undefined

Extract the TtsErrorCode from a rejected ttsSpeak, normalizing across hosts: the iOS bridge APIError (code / error_code / errorCode) and a host { reason } / error message string. Returns undefined if no known code is present.

Parameters

Parameter	Type
error	unknown

Returns

TtsErrorCode | undefined

Example

try { await api.ttsSpeak({ text, language }) } catch (err) {
  if (api.ttsErrorCode(err) === 'TTS_VOICE_UNAVAILABLE') promptVoiceDownload()
}

ttsSpeak()

ttsSpeak(payload): Promise<TtsSpeakResult>

Speak text on the device speaker. Resolves when the utterance FINISHES; rejects with a TtsErrorCode.

Parameters

Parameter	Type	Description
payload	TtsSpeakPayload	-

Returns

Promise<TtsSpeakResult>

{ completed } — true if it finished naturally, false if stopped or replaced by a newer ttsSpeak.

Example

const { completed } = await api.ttsSpeak({ text: 'Meeting summary saved.', language: 'en-US' })

ttsStop()

ttsStop(): Promise<void>

Stop any in-flight speech. The in-flight ttsSpeak resolves with { completed: false }.

Returns

Promise<void>

Example

await api.ttsStop()

ttsWarmup()

ttsWarmup(): Promise<void>

Pre-load the on-device Supertonic model (web only) WITHOUT speaking, so a later ttsSpeak answers instantly instead of paying the first-use model download/init cost. Optional — call it when the app knows it will speak soon (e.g. once an AI response starts generating). A no-op on hosts with nothing to warm (iOS, or web with the on-device model disabled/ unsupported — Web Speech needs no warmup); the bridge has no tts.warmup type, so calling it there rejects with requestTypeDoesNotExists — catch and ignore, mirroring its STT counterpart sttWarmup.

Returns

Promise<void>

Example

api.ttsWarmup().catch(() => {}) // background, non-blocking

unassignCanvasTheme()

unassignCanvasTheme(payload): Promise<void>

Parameters

Parameter	Type
payload	{ canvas_id: string; }
payload.canvas_id	string

Returns

Promise<void>

updateCanvas()

updateCanvas(payload): Promise<CanvasRetrieve>

Modify the currently loaded canvas. On the web it sends an update_canvas request to the server.

Parameters

Parameter	Type	Description
payload	UiUpdateCanvasRequest	parts of the canvas object to update with fields to return

Returns

Promise<CanvasRetrieve>

updateCanvasIndicators()

updateCanvasIndicators(payload): Promise<CanvasRetrieve>

Updates canvas indicators by canvas ID. It merges the passed object into existing canvas indicators adding new keys if they were empty and overriding pre-existing keys.

Indicators can also be updated using updateCanvas API but in this case passed object fully replaces existing indicators.

Parameters

Parameter	Type
payload	{ id: string; indicators: Record<string, CanvasIndicator>; instance_id?: string; }
payload.id	string
payload.indicators	Record<string, CanvasIndicator>
payload.instance_id?	string

Returns

Promise<CanvasRetrieve>

Example

// The fields param is appended to the URL as a query param.
onMounted(() => {
  PitcherAPI.updateCanvasIndicators({
    id: '01J9XT0WVXRTETF4CQZP42CPZP',
    indicators: {
      existing: { type: 'info', label: 'new label' }, // will be overriden
      new: { type: 'info', label: 'INFO' }, // will be added
      removeExisting: null // will be set to null and ignored, it is the same as removal
   }
   }).then((res) => {
    console.log(res)  // entire canvas object, including indicators field
  })
})

updateFile()

updateFile(payload): Promise<FileRetrieve>

Parameters

Parameter	Type
payload	FileUpdateRequest & object

Returns

Promise<FileRetrieve>

updateFolder()

updateFolder(payload): Promise<FolderRetrieve>

Updates an existing folder.

Parameters

Parameter	Type	Description
payload	UpdateFolderPayload	The folder update payload, including the folder ID and update data.

Returns

Promise<FolderRetrieve>

A promise that resolves to the updated folder.

updateLocation()

updateLocation(payload): Promise<any>

Navigate to another page in the CatalogIQ instance.

Parameters

Parameter	Type
payload	UpdateLocationPitcherEvent

Returns

Promise<any>

Example

const canvasId = '1234567890abcdef12345678' // obtain target canvasId
useUi().updateLocation({
  action: 'restore',
  routes: {
    'slotty-ui': {
      path: '/canvases/saved-canvases/' + canvasId + '/build/present',
      query: {},
    },
  },
})

updateMyUser()

updateMyUser(payload): Promise<User>

Parameters

Parameter	Type
payload	UpdateEnvParams

Returns

Promise<User>

weeklyFocusRank()

weeklyFocusRank(payload): Promise<WeeklyFocusRankResult>

Rank the rep's next-7-days meetings by how much preparation they need — the ONE high-level Weekly Focus call (PIT-7257), the weekly_focus AITask.

The on-device path runs the prompt, window, parser and ordinal resolver from @lib/ai-tasks/weekly-focus; the online route runs next-core's parallel copy of the same logic. The two are kept in lockstep by matching test suites, not a shared import (see that module's header / ADR-002), so the two paths produce the same shape:

• iOS with an available local model → aiComplete over the caller-supplied meetings + account context. Unavailable models / unusable output fall through.
• Otherwise → POST to the next-core Bedrock route.

The model picks meetings by ORDINAL and the resolver maps them back to event_ids, dropping out-of-range ones — so a returned id can only come from the meetings passed in.

This does NOT cache, lock or prewarm: an app that generates on a schedule (as pre-call-brief does) owns those mechanics and calls this underneath.

Parameters

Parameter	Type	Description
payload	WeeklyFocusRankPayload	The meetings + optional account context.

Returns

Promise<WeeklyFocusRankResult>

• Ranking with the serving source.

Example

const focus = await api.weeklyFocusRank({ meetings, context })
console.log(focus.hero, focus.top, focus.collapsed_count)

---

Type Literal

{ broadcast: (event) => Promise<any>; on: (type, handler) => Promise<() => void>; close: Promise<void>; embeddableReady: Promise<void>; getAppConfig: Promise<Record<string, any>>; getEnv: Promise<DsrEnv>; getFile: Promise<File>; }

broadcast

broadcast: (event) => Promise<any>

Parameters

Parameter	Type
event	PitcherEvent

Returns

Promise<any>

on

on: (type, handler) => Promise<() => void>

Subscribe to a given event type by its key.

Parameters

Parameter	Type	Description
type	"dsr_env_changed"	The event type/key to subscribe to.
handler	(data) => Promise<void>	The handler function to call when the event is emitted.

Returns

Promise<() => void>

A Promise resolving to a cleanup function to unsubscribe from the event.

close()

close(): Promise<void>

Closes the already open file that was opened via api or by the user.

Returns

Promise<void>

Example

dsrApi.close()

embeddableReady()

embeddableReady(): Promise<void>

Signal to DSR that the app is ready to be shown.

Returns

Promise<void>

Example

useDsr().embeddableReady()

getAppConfig()

getAppConfig(payload?): Promise<Record<string, any>>

Retrieves the configuration for the calling app. App name can be optionally provided, otherwise it will be derived from the caller's URL.

Parameters

Parameter	Type
payload?	{ app_name?: string; }
payload.app_name?	string

Returns

Promise<Record<string, any>>

Example

dsrApi.getAppConfig() // for self config
// or with explicit app name
dsrApi.getAppConfig({ app_name: 'my-app' })

getEnv()

getEnv(): Promise<DsrEnv>

Fetches the necessary info for the app to know where it is embedded.

Check out usePitcherApi().getEnv() for more information.

Returns

Promise<DsrEnv>

Example

useDsr().getEnv()

getFile()

getFile(payload): Promise<File>

Fetches a file by ID.

Parameters

Parameter	Type
payload	{ id: string; }
payload.id	string

Returns

Promise<File>

Example

dsrApi.getFile({ id: 'my-file-id' })