Statisfy SDK API Reference

This page is the low-level reference behind the SDK components and clients. Most apps never call these endpoints directly — the SDK does — but you’ll need them when minting tokens or debugging.

Base URL & headers

All requests go to your Statisfy gateway (e.g. https://api.statisfy.com). Every SDK data request carries:

Header	Value	Notes
`Authorization`	`Bearer <session-token>`	The HS256 session token — signed by your own backend (vendored) or returned by `POST /auth/verify` (portal).
`X-Statisfy-Publishable-Key`	`pk_live_…` / `pk_test_…`	Identifies your tenant. Required by the chat routes; project routes read the tenant from the token.

Authentication

There are two ways a bearer token comes into existence. The SDK accepts either — it just returns whatever getToken gives it.

Path	Who mints the token	Carries `customer_id`?
Vendored (SDK in your own app)	Your backend signs an HS256 JWT with your JWT secret. No Statisfy endpoint involved. Required claims: `iat`, `exp`, `email`. See Publishable Keys & Secrets.	No — chat only
Portal (Statisfy-hosted)	The customer signs in with a one-time code emailed by Statisfy; `POST /auth/verify` returns the session token.	Yes — chat + projects

A Statisfy-hosted portal has no backend of its own, so its customers sign in passwordless: Statisfy emails a one-time code, the portal exchanges that code for a session token, and a rotating refresh token keeps the customer signed in afterwards. All three routes take a JSON body only — no Authorization header and no publishable key — and live on the same base URL as the rest of the API.

You rarely call these yourself. <PortalAuthGate> from @statisfy/portal-react runs the whole flow — it renders the sign-in form, stores the refresh token, silently re-mints the access token before it expires, and supplies StatisfyProvider internally. Every portal template ships with it already wired up.

entity_type must be "portal" and entity_id is the portal’s id; together they are how the service resolves your tenant. Any other entity_type is rejected with unsupported_entity — there is no “latest published portal” fallback.

`POST /auth/otp` — email a one-time code

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

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

Response 200 — an empty object, {}. The response is deliberately empty and identical for every address: it never reveals whether the email belongs to one of your customers. A code is created and sent only when the email matches a person on one of your accounts. A malformed or unknown entity_id is the one exception — that’s a misconfigured portal, not an enumeration signal, so it returns 404. The code is a 6-digit number and expires after the window set in the portal’s Auth tab (1–60 minutes, default 10) — see Customizing the Login Email.

`POST /auth/verify` — exchange the code for a session

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

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

Response 200

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

token is an HS256 JWT signed with your tenant’s shared secret, carrying tenant_id, customer_id, portal_id, email, iss (statisfy-sdk), iat, and exp. The gateway scopes every subsequent request to that customer_id. refresh_token is opaque — store it, don’t parse it.

`POST /auth/token` — refresh the session

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

{ "refresh_token": "…" }

No entity_type / entity_id is needed — the refresh token carries its own context. The response is the same shape as /auth/verify, including a new refresh_token.

Refresh tokens rotate on every use. Replace the stored token each time, and never present one that has already been exchanged — reuse revokes the whole token family and signs the customer out. A refresh token is valid for at most 30 days.

Contacts on several accounts — switching account

A session token is scoped to exactly one account (its customer_id claim), so a contact associated with more than one account switches by re-minting, not by passing an account id per request:

Call	Effect
`GET /sdk/v1/me/accounts`	The accounts this viewer may act as: `{ accounts: [{ customer_id, name, domain, is_primary }], active_customer_id }`. Derived from the signed session only — nothing is client-supplied, so the list can’t be steered.
`POST /auth/token` with `{ refresh_token, customer_id }`	Re-mints the session scoped to that account.
`POST /auth/verify` with an optional `customer_id`	Resumes sign-in on the account the contact last used.

customer_id is validated against that contact’s own accounts on every call, so it can only ever narrow to something they already had; an account they’ve since been removed from quietly resolves back to their primary, and the response’s customer_id reports the account actually bound. The SDK wraps this: listAccounts() and switchAccount(customerId) on the portal auth client, with getActiveCustomerId() for the current one. accounts is a single entry for most viewers — render a switcher only when it holds two or more. Error codes

Status	`code`	Meaning
400	`unsupported_entity`	`entity_type` is anything other than `"portal"`.
401	`auth_token_invalid`	The sign-in code is wrong, already used, or expired.
401	`refresh_token_invalid`	The refresh token is invalid, expired, or was already rotated.
403	`not_a_customer`	The email isn’t a customer of this tenant.
403	`customer_unresolved`	The matched person has no customer id.
404	`portal_not_found`	The `entity_id` is unknown, or the portal isn’t published.
500	`sdk_secret_unconfigured`	The tenant’s signing secret isn’t configured.

Project endpoints (`/sdk/v1`)

Authenticated by the session token’s own tenant_id + customer_id claims (token-only — the publishable key is not required here). All errors return { "detail": { "code": "...", "message": "..." } }.

These routes scope every query by the signed customer_id, so they require a portal-session token. A token minted by your own backend without that claim is rejected with 401 not_a_portal_session, even though it is validly signed and works for chat.

Method	Path	Body	Response
`GET`	`/sdk/v1/me/accounts`	—	`{ accounts: SdkAccount[], active_customer_id }`
`GET`	`/sdk/v1/config/{module}`	—	`{ data: {...}, meta: { module } }`
`GET`	`/sdk/v1/projects/{id}`	—	`{ data: ProjectData, meta: { can_edit } }`
`PATCH`	`/sdk/v1/projects/{id}`	`{ properties: {...} }`	`{ data: ProjectData, meta }`
`PATCH`	`/sdk/v1/projects/{id}/tasks/{taskId}`	`{ properties: {...} }`	`{ data: ProjectData, meta }`
`GET`	`/sdk/v1/projects/{id}/comments`	—	`{ data: ProjectComment[] }`
`POST`	`/sdk/v1/projects/{id}/comments`	`{ value }`	`ProjectComment`
`GET`	`/sdk/v1/projects/{id}/tasks/{taskId}/comments`	—	`{ data: ProjectComment[] }`
`POST`	`/sdk/v1/projects/{id}/tasks/{taskId}/comments`	`{ value }`	`ProjectComment`
`PATCH`	`/sdk/v1/projects/{id}/comments/{commentId}`	`{ value }`	`ProjectComment`

Comments posted through the SDK are always customer-visible (external), and an external session only ever sees external comments. Editing is author-only and text-only; it does not yet have an SDK client method. For module=portal, the config response exposes the account’s onboarding project under the onboarding_project__c_ key — the Onboarding Project lookup field on the Account, resolved for the account the token is scoped to. null means that account’s field is unset. See Portal SDK: Project API. Error codes

Status	`code`	Meaning
401	`user_token_invalid`	Token signature invalid / claims missing.
401	`user_token_expired`	Token `exp` is in the past — re-mint.
401	`not_a_portal_session`	Token has no `customer_id` (not a portal session).
404	`module_not_found`	Unknown config module.
404	`project_not_found`	Project not found for this customer.
404	`task_not_found`	Task not found on this project.
400	`not_editable`	A supplied field isn’t editable / doesn’t exist.
400	`invalid_option`	Value isn’t an allowed option for a `select` field.
400	`invalid_type`	Value doesn’t match the field’s type.

Chat endpoints (`/sdk/dw/v1`)

Authenticated by the publishable key (resolves the tenant) plus the session/worker token.

Method	Path	Body / Query	Response
`POST`	`/sdk/dw/v1/workers/{workerId}/messages`	`{ content, thread_id?, structured_input?, form_prompt? }`	`{ reply, thread_id, conversation_id, agent_message_id, pending_approval?, next_action? }`
`POST`	`/sdk/dw/v1/workers/{workerId}/messages/stream`	same as above	Server-Sent Events (see below)
`GET`	`/sdk/dw/v1/workers/{workerId}/conversation`	`?thread_id=<id>&source=in_app_sdk`	`{ thread_id, conversation_id, messages[], next_action? }`
`GET`	`/sdk/dw/v1/workers/{workerId}/conversations`	`?source=in_app_sdk&limit=<n>`	`{ conversations[], total }`

The chat endpoints live under the /sdk namespace (/sdk/dw/v1/...). The old /dw/v1/workers/... paths were a deprecated alias and have been removed — they now 404. The official SDK calls the /sdk paths; upgrade if you are pinned to an older build that still calls /dw/v1.

Streaming frames

/messages/stream emits these SSE frame types:

Frame	Payload	Meaning
`text_delta`	`{ content }`	Incremental reply text.
`tool_call_started`	`{ tool_name, tool_input? }`	A tool was invoked (e.g. `present_form`).
`tool_call_completed`	`{ tool_name }`	Tool succeeded.
`tool_call_error`	`{ tool_name, tool_error? }`	Tool failed.
`done`	`{ thread_id, conversation_id, agent_message_id, next_action? }`	Turn finished.
`error`	`{ message, code? }`	Streaming error.

The headless client (createDigitalWorkerClient) maps these frames to the streamMessage handler callbacks — see Digital Worker Chat.

TypeScript types

The package is fully typed. Public exports: Provider & chat

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

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

workerId is optional in the type because a portal component in config mode takes its worker from portal.runtime.json instead. Supply workerId for non-portal hosts and configId inside a portal — when both are set, configId wins and workerId is ignored with a dev-mode warning.

Forms & messages

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 }

Portal runtime config — see Portal Runtime Config

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 }

Project

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[] }

OnboardingProject’s configId is required — there’s no embed-mode fallback, so a portal must set it for the component to ever resolve. ProjectModule’s configId and projectId are both optional: supply projectId outside a portal and configId inside one — when both are set, configId wins and projectId is ignored with a dev-mode warning. A ProjectModule pinned via configId resolves only for the account that owns the pinned project; every other signed-in account sees the empty state.

The hook result types — UseProjectResult and UseCommentsResult — are documented field-by-field on the Project Module page.

Security notes

The publishable key is safe in client-side code; it only identifies the tenant and can’t authenticate on its own.
The session token is short-lived (default 1 hour) and scoped to a single customer. Re-mint it before expiry inside your getToken callback — from your own backend in the vendored path, or via POST /auth/token in a portal. <PortalAuthGate> already does this for you.
Cross-origin requests are scoped per publishable key — the gateway only accepts SDK requests from origins configured for your key.
The gateway derives customer_id from the signed token, never from client-supplied input, so a customer can only ever read or write their own project and conversations.

Getting Started

Accounts

People & Contacts

Opportunities

Activities

Views

Filters & Custom Fields

Projects

Tasks

Reports

Workflows

Dashboard

Workbench

Stella AI

Campaigns

Knowledge Base

Approvals

Portals

Statisfy SDK

Digital Workers

Statisfy SDK API Reference

Base URL & headers

Authentication

`POST /auth/otp` — email a one-time code

`POST /auth/verify` — exchange the code for a session

`POST /auth/token` — refresh the session

Contacts on several accounts — switching account

Project endpoints (`/sdk/v1`)

Chat endpoints (`/sdk/dw/v1`)

Streaming frames

TypeScript types

Security notes

​Base URL & headers

​Authentication

​Portal sign-in

​POST /auth/otp — email a one-time code

​POST /auth/verify — exchange the code for a session

​POST /auth/token — refresh the session

​Contacts on several accounts — switching account

​Project endpoints (/sdk/v1)

​Chat endpoints (/sdk/dw/v1)

​Streaming frames

​TypeScript types

​Security notes

Base URL & headers

Authentication

Portal sign-in

`POST /auth/otp` — email a one-time code

`POST /auth/verify` — exchange the code for a session

`POST /auth/token` — refresh the session

Contacts on several accounts — switching account

Project endpoints (`/sdk/v1`)

Chat endpoints (`/sdk/dw/v1`)

Streaming frames

TypeScript types

Security notes