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.app). Every SDK data request carries:

Header	Value	Notes
`Authorization`	`Bearer <session-token>`	The HS256 session token from `/sdk/auth`.
`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

`POST /sdk/auth` — mint a session token

Exchanges a signed-in user’s identity for a short-lived Statisfy session token. Request

POST /sdk/auth
Authorization: Bearer <tenant Clerk/IdP JWT>
X-Statisfy-Publishable-Key: pk_live_…
Content-Type: application/json

{ "portal_id": "<uuid>" }

Response 200

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

The minted 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. Error codes

Status	`code`	Meaning
401	`auth_token_invalid`	The user JWT is missing, expired, or invalid.
401	`auth_token_missing_email`	The user JWT has no email claim.
401	`publishable_key_missing`	The `X-Statisfy-Publishable-Key` header wasn’t sent.
401	`publishable_key_invalid`	Unknown or revoked publishable key.
403	`not_a_customer`	The user’s email isn’t a customer of this tenant.
403	`customer_unresolved`	The matched person has no customer id.
404	`portal_not_found`	The `portal_id` is unknown or not 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": "..." } }.

Method	Path	Body	Response
`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 }`

For module=portal, the config response exposes the account’s onboarding project under the onboarding_project__c_ key. 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 moved under the /sdk namespace (from /dw/v1/... to /sdk/dw/v1/...). The old /dw/v1/workers/... paths still work as a deprecated alias, but new integrations should use /sdk/dw/v1. The official SDK already calls the new paths — upgrade to pick them up automatically.

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; workerName?: string; greeting?: string; /* …see Chat page */ }
interface OnboardingModuleProps { /* DigitalWorkerChatProps minus initialThreadId & autoLoadConversation */ }
interface DigitalWorkerClientConfig { baseUrl: string; workerId: string; getToken: GetToken; publishableKey?: string }
class DigitalWorkerError extends Error { code?: string; status?: number }

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 }

Project

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

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 via /sdk/auth before expiry inside your getToken callback.
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

Portals

Tasks

Reports

Workflows

Dashboard

Workbench

Digital Workers

Stella AI

Campaigns

Knowledge Base

Approvals

Statisfy SDK API Reference

Base URL & headers

Authentication

`POST /sdk/auth` — mint a session token

Project endpoints (`/sdk/v1`)

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

Streaming frames

TypeScript types

Security notes

​Base URL & headers

​Authentication

​POST /sdk/auth — mint a session token

​Project endpoints (/sdk/v1)

​Chat endpoints (/sdk/dw/v1)

​Streaming frames

​TypeScript types

​Security notes

Base URL & headers

Authentication

`POST /sdk/auth` — mint a session token

Project endpoints (`/sdk/v1`)

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

Streaming frames

TypeScript types

Security notes