Search documentation

Search for docs or ask AI

Core SDK API Reference

Complete API reference for the @pillar-ai/sdk package. Use this for vanilla JavaScript applications or direct SDK access.

Pillar.init()

Initialize the SDK. Returns a promise that resolves when ready.

Signature

typescript
Pillar.init(config: InitConfig): Promise<PillarInstance>

Parameters

PropertyTypeRequiredDescription
productKeystringYesYour product key from app.trypillar.com
publicKeystringYesYour public API key
panelPanelConfigNoPanel configuration
themeThemeConfigNoTheme configuration
textSelectionTextSelectionConfigNoText selection configuration
customCSSstringNoCustom CSS to inject

Example

examples/reference/core/pillar-init.js
import { Pillar } from '@pillar-ai/sdk';


const pillar = await Pillar.init({
  productKey: 'your-product-key',
  publicKey: 'pk_live_xxx',
  panel: { position: 'right', mode: 'push' },
  theme: { mode: 'auto', colors: { primary: '#2563eb' } },
});

Panel Methods

Pillar.open()

Open the help panel.

typescript
Pillar.open(options?: OpenOptions): void
OptionTypeDescription
articlestringOpen to a specific article by slug
searchstringOpen with a search query
focusInputbooleanFocus the chat input
examples/reference/core/pillar-open.js
Pillar.open();                          // Open to home
Pillar.open({ article: 'getting-started' }); // Open article
Pillar.open({ search: 'billing' });     // Open with search

Pillar.close()

Close the help panel.

typescript
Pillar.close(): void

Pillar.toggle()

Toggle the panel open/closed.

typescript
Pillar.toggle(): void

Context Methods

Pillar.setContext()

Set user context for smarter AI responses and action filtering.

typescript
Pillar.setContext(context: ContextData): void
PropertyTypeDescription
currentPagestringCurrent URL path
currentFeaturestringHuman-readable feature name
userRolestringUser's role for action filtering
userStatestringUser's current state
errorState{ code: string, message: string }Current error
customRecord<string, unknown>Any additional data
examples/reference/core/pillar-set-context.js
Pillar.setContext({
  currentPage: '/settings/billing',
  currentFeature: 'Billing Settings',
  userRole: 'admin',
  custom: { plan: 'pro' },
});

Task Handling

Pillar.onTask()

Register a handler for when the AI suggests an action.

typescript
Pillar.onTask(actionName: string, handler: TaskHandler): () => void

Returns an unsubscribe function.

examples/reference/core/pillar-on-task.js
const unsubscribe = Pillar.onTask('navigate', (data) => {
  window.location.href = data.path;
  return { success: true };
});


// Later: unsubscribe();

TaskHandler Return Value

examples/reference/core/task-result.ts
interface TaskResult {
  success: boolean;
  message?: string;
}

Theme Methods

Pillar.setTheme()

Update the theme at runtime.

typescript
Pillar.setTheme(update: ThemeUpdate): void
examples/reference/core/pillar-set-theme.js
// Change mode
Pillar.setTheme({ mode: 'dark' });


// Update colors
Pillar.setTheme({ colors: { primary: '#10b981' } });


// Update dark mode colors
Pillar.setTheme({ darkColors: { primary: '#34d399' } });

Plan Methods

Pillar.startPlan()

Start an awaiting plan.

typescript
Pillar.startPlan(): Promise<void>

Pillar.completeAction()

Signal that an action has completed. For wizard actions (modals, multi-step flows), call this when the user finishes. If there's an active plan waiting on this action, it automatically advances to the next step.

typescript
Pillar.completeAction(
  actionName: string,
  success?: boolean,
  data?: Record<string, unknown>
): Promise<void>
examples/reference/core/pillar-complete-action.js
// When user completes a wizard triggered by an action
Pillar.completeAction('add_source', true, { sourceId: '123' });

Pillar.skipPlanStep()

Skip a plan step.

typescript
Pillar.skipPlanStep(stepId: string): Promise<void>

Pillar.cancelPlan()

Cancel the current plan.

typescript
Pillar.cancelPlan(): Promise<void>

Event Methods

Pillar.on()

Subscribe to SDK events.

typescript
Pillar.on(event: string, callback: Function): () => void

Returns an unsubscribe function.

examples/reference/core/pillar-on.js
const unsubscribe = Pillar.on('panel:open', () => {
  console.log('Panel opened');
});


// Later: unsubscribe();

See Events Reference for all available events.

Card Registration

Pillar.registerCard()

Register a custom card renderer for vanilla JS.

typescript
Pillar.registerCard(
  cardType: string,
  renderer: CardRenderer
): void
examples/reference/core/card-renderer.ts
type CardRenderer = (
  container: HTMLElement,
  data: Record<string, unknown>,
  callbacks: { onConfirm: Function, onCancel: Function }
) => () => void; // Returns cleanup function
examples/reference/core/pillar-register-card.js
Pillar.registerCard('invite_members', (container, data, callbacks) => {
  container.innerHTML = `
    <div>
      <p>Invite ${data.emails.length} members</p>
      <button id="cancel">Cancel</button>
      <button id="confirm">Confirm</button>
    </div>
  `;


  container.querySelector('#confirm').onclick = () => callbacks.onConfirm(data);
  container.querySelector('#cancel').onclick = callbacks.onCancel;


  return () => { container.innerHTML = ''; };
});

Lifecycle

Pillar.destroy()

Destroy the SDK instance and clean up.

typescript
Pillar.destroy(): void

Use on logout or when the SDK is no longer needed:

examples/reference/core/pillar-destroy.js
function handleLogout() {
  Pillar.destroy();
  // Continue with logout...
}

Properties

Pillar.activePlan

The currently active plan, if any.

typescript
Pillar.activePlan: ExecutionPlan | null

Pillar.isReady

Whether the SDK is initialized and ready.

typescript
Pillar.isReady: boolean

Pillar.isPanelOpen

Whether the panel is currently open.

typescript
Pillar.isPanelOpen: boolean