Function: createScopedPitcherApi()

createScopedPitcherApi(options?): object

A DEDICATED api instance for a call site that needs different options, without touching the shared singleton every other consumer holds.

Inherits whatever the host configured (so the Sentry errorLogger and casing survive) and applies options on top.

Each instance registers its own window 'message' listener and its own subscribe, so create ONE per call site at module scope — never inside a component setup(), which would leak a listener per mount. Responses are matched by callback id and unknown ids are ignored, so instances coexist.

Parameters

Parameter	Type
options?	ApiOptions

Returns

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)