Statisfy SDK API Reference

POST /auth/otp
Content-Type: application/json

{ "email": "customer@acme.com", "entity_type": "portal", "entity_id": "<portal-uuid>" }

POST /auth/verify
Content-Type: application/json

{ "email": "customer@acme.com", "token": "123456", "entity_type": "portal", "entity_id": "<portal-uuid>" }

{
  "token": "eyJhbGc…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "…",
  "customer_id": "1102",
  "portal": { "portal_id": "<uuid>", "commit_sha": "<sha>", "url": "https://…" }
}

POST /auth/token
Content-Type: application/json

{ "refresh_token": "…" }

{
  "accounts": [
    { "customer_id": "1102", "name": "Acme Corp", "domain": "acme.com", "is_primary": true },
    { "customer_id": "2201", "name": "Acme EMEA", "domain": null, "is_primary": false }
  ],
  "active_customer_id": "1102"
}

POST /auth/verify
Content-Type: application/json

{
  "entity_type": "portal",
  "entity_id": "<portal-uuid>",
  "actor_token": "<signed grant from Portal Studio>"
}

POST /auth/impersonation/stop
Content-Type: application/json

{ "refresh_token": "…" }

GET /sdk/v1/account?fields=name,renewal_date,success_goal__c
Authorization: Bearer <session-token>

{
  "data": {
    "id": "<account-id>",
    "properties": { "name": "Acme", "renewal_date": "2026-12-31", "success_goal__c": "Expand to EMEA" },
    "display": {},
    "schema": [
      { "key": "name", "label": "Name", "type": "text", "field_type": "text", "editable": false },
      { "key": "renewal_date", "label": "Renewal Date", "type": "date", "field_type": "date", "editable": true },
      { "key": "success_goal__c", "label": "Success Goal", "type": "text", "field_type": "textarea", "editable": true }
    ]
  },
  "meta": { "entity": "account", "view": "live" }
}

PATCH /sdk/v1/me
Authorization: Bearer <session-token>
Content-Type: application/json

{ "properties": { "title": "VP Customer Success" } }

type GetToken = () => Promise<string | null>
interface StatisfyConfig { baseUrl: string; getToken: GetToken; publishableKey?: string } // baseUrl is filled in by the provider
interface StatisfyProviderProps { children: ReactNode; getToken: GetToken; publishableKey?: string; /** @deprecated */ baseUrl?: string }
interface DigitalWorkerChatProps { workerId?: string; configId?: string; workerName?: string; greeting?: string; /* …see Chat page */ }
type OnboardingModuleProps = Omit<DigitalWorkerChatProps, 'initialThreadId' | 'autoLoadConversation' | 'history' | 'newChat' | 'scope'>
interface DigitalWorkerClientConfig { workerId: string; getToken: GetToken; publishableKey?: string; baseUrl?: string } // omit baseUrl to use the default gateway
class DigitalWorkerError extends Error { code?: string; status?: number }

// Hook: read the provider's config (throws a DigitalWorkerError outside the provider).
function useStatisfyConfig(): StatisfyConfig

interface FormField { key: string; label: string; type: string; options?: unknown[]; placeholder?: string; mandatory?: boolean }
interface FormSpec { prompt: string; fields: FormField[] }
type FormRenderer = (spec: FormSpec, ctx: FormRendererContext) => ReactNode
interface FormRendererContext { onSubmit: (values: Record<string, unknown>) => void; disabled: boolean }
interface ChatMessage { id: string; role: 'user' | 'assistant' | 'system'; content: string; /* …toolCalls, formSpec, senderKind, senderName, … */ }
interface ToolCall { toolName: string; status: 'running' | 'completed' | 'error'; error?: string }
interface Attachment { id: string; filename: string; mime_type: string; size_bytes: number }
interface NextAction { type: 'form' | 'approval' | 'complete' | 'handoff'; form_spec?: FormSpec | null; approval_payload?: HumanApprovalPayload | null; message?: string | null }
interface ToolCallEntry { tool_name: string; args: Record<string, unknown>; tool_schema: { fields: FormField[] }; item_id?: string | null; status?: string }
interface HumanApprovalPayload { tools: ToolCallEntry[]; display_type: string }
interface ToolSubmission { tool_name: string; args: Record<string, unknown>; item_id?: string | null }

interface PortalAccount { customer_id: string; name: string | null; domain: string | null; is_primary: boolean }
type PortalAccountScope = 'my_book' | 'my_team' | 'all'
interface PortalAccountList { accounts: PortalAccount[]; active_customer_id: string; scope: PortalAccountScope | null; has_more: boolean; available_scopes: PortalAccountScope[]; active_account: PortalAccount | null }
interface PortalAccountQuery { scope?: PortalAccountScope; search?: string; limit?: number; offset?: number }
interface PortalAccountSwitcherProps { client: PortalAuthClient; onSwitched?: (customerId: string) => void; className?: string; 'aria-label'?: string }
interface UsePortalAccountsResult {
  accounts: PortalAccount[]; activeCustomerId: string | null; activeAccount: PortalAccount | null; loading: boolean; switching: boolean
  error: Error | null; errorSource: 'list' | 'switch' | null; switchAccount: (customerId: string) => Promise<void>
  scope: PortalAccountScope | null; availableScopes: PortalAccountScope[]; search: string; hasMore: boolean; loadingMore: boolean
  setScope: (scope: PortalAccountScope) => void; setSearch: (search: string) => void; loadMore: () => void
}

// On PortalAuthClient (createPortalAuthClient):
//   listAccounts(query?: PortalAccountQuery): Promise<PortalAccountList> — requires a live session; throws on failure
//   switchAccount(customerId: string): Promise<void>  — re-mints the session; throws if the exchange fails
//   getActiveCustomerId(): string | null              — the account the cached token is scoped to
//   getEmail(): string | null                         — the signed-in viewer's email (display only, unverified claim)
//   subscribe(listener: () => void): () => void       — observe account/token/email changes; returns an unsubscribe

interface PortalFieldRef { $field: string }
type PortalConfigValue = string | PortalFieldRef
interface ResolvedPortalFields { field_values: Record<string, string | null>; locked_values: Record<string, string | null> }
interface UseResolvedFieldsResult { fields: Record<string, string | null>; locked: Record<string, string | null>; resolve: (value: PortalConfigValue | null | undefined) => string | null; loading: boolean; error: Error | null; refetch: () => void }

interface OnboardingProjectProps { configId: string; className?: string }
interface ProjectModuleProps { configId?: string; projectId?: string; className?: string }

type ProjectFieldType = 'text' | 'date' | 'number' | 'boolean' | 'select' | (string & {})
type ProjectStepStatus = 'done' | 'current' | 'upcoming' | (string & {})
interface ProjectSelectOption { value: string; label: string; color?: string }
interface ProjectFieldSchema { key: string; label: string; type: ProjectFieldType; editable: boolean; options?: ProjectSelectOption[] }
interface ProjectTask { id: string; parent_id: string | null; is_milestone: boolean; status: string | null; step_status: ProjectStepStatus; properties: Record<string, unknown>; display: Record<string, string> }
interface ProjectProgress { percent: number | null; completed: number; total: number }   // exported as ProjectProgressData
interface ProjectData { id: string; properties: Record<string, unknown>; display: Record<string, string>; schema: ProjectFieldSchema[]; progress: ProjectProgress | null; tasks: ProjectTask[]; tasks_schema: ProjectFieldSchema[] }
interface ProjectResponse { data: ProjectData; meta: { can_edit?: boolean } & Record<string, unknown> }
interface ProjectConfigResponse { data: Record<string, unknown>; meta: Record<string, unknown> }
interface ProjectComment { id: number; value: string; author_id: string; author_name: string; created_at: string | null; updated_at: string | null; visibility: string; can_edit: boolean }
interface ProjectCommentListResponse { data: ProjectComment[] }