Portal SDK: Project API

The Portal SDK lets an embedded portal show a customer their onboarding project — its fields, milestones, tasks, and comments — and let them make the changes you allow. It has two layers:

React SDK

@statisfy/digital-workers-react — drop-in components (<ProjectModule/>, <Comments/>) and headless hooks (useProject, useComments).

REST API

The /sdk/v1 endpoints the React SDK calls. Use them directly if you’re not on React.

Everything is scoped to the customer in the session token — the portal never sends a customer id, and a project or task that isn’t the session’s is reported as 404 (existence is never leaked).

Authentication

Every call needs a portal session token (a short-lived JWT) as a bearer, plus your publishable key:

Authorization: Bearer <portal-session-token>
X-Statisfy-Publishable-Key: <publishable_key>

Mint the session token by exchanging the signed-in user’s identity at your gateway’s token endpoint; the React SDK does this for you via <StatisfyProvider>. See Publishable keys to create a key.

Visibility is enforced server-side. A real (non-preview) external viewer only receives fields, tasks, and comments that have been shared with the customer — see External sharing. An internal preview session sees everything.

What the customer can see and edit

Fields marked Internal are removed from the response entirely.
Tasks hidden from the portal are dropped from the task list.
Comments that weren’t shared with the customer are filtered out; comments the customer posts are always shared.
Writes are gated by meta.can_edit and each field’s editable flag.

REST API

Base path: /sdk/v1. All responses are JSON. Error responses:

Status	Shape
`400` `401` `403` `404`	`{ "detail": { "code": "...", "message": "..." } }`
`422` (validation error)	`{ "detail": [{ "loc": ["body", "field_name"], "msg": "...", "type": "..." }] }` — `detail` is an array of validation-error objects.

Resolve the onboarding project

GET /sdk/v1/config/portal

Returns the customer’s onboarding project id under onboarding_project__c_, which you then read with GET /projects/{id}.

{ "data": { "onboarding_project__c_": "1102" }, "meta": { "module": "portal" } }

Read a project

GET /sdk/v1/projects/{project_id}

Returns the project’s values, human-readable display strings, field schema, server-ordered tasks, and a progress meter.

{
  "data": {
    "id": "1102",
    "properties": { "title": "New Onboarding", "status": "42", "due_date": "2026-07-04" },
    "display": { "status": "In Progress" },
    "schema": [ { "key": "status", "label": "Status", "type": "select", "editable": false, "options": [] } ],
    "progress": { "percent": 40, "completed": 2, "total": 5 },
    "tasks": [ { "id": "t1", "parent_id": null, "is_milestone": true, "status": "9", "step_status": "current", "properties": {}, "display": {} } ],
    "tasks_schema": [ { "key": "status", "label": "Status", "type": "select", "editable": true, "options": [] } ]
  },
  "meta": { "can_edit": true }
}

Render display[key] ?? properties[key]; send only canonical properties back on writes. tasks is a flat, depth-first list — build the milestone → subtask tree client-side from parent_id, and never re-sort it.

Update a project or task

PATCH /sdk/v1/projects/{project_id}
PATCH /sdk/v1/projects/{project_id}/tasks/{task_id}

Body is the changed canonical values only:

{ "properties": { "status": "10" } }

Both return the refreshed project payload. A non-editable field or invalid option is rejected with a 400 (not_editable / invalid_option / invalid_type).

Comments

GET  /sdk/v1/projects/{project_id}/comments
POST /sdk/v1/projects/{project_id}/comments
GET  /sdk/v1/projects/{project_id}/tasks/{task_id}/comments
POST /sdk/v1/projects/{project_id}/tasks/{task_id}/comments
PATCH /sdk/v1/projects/{project_id}/comments/{comment_id}

GET returns customer-visible comments oldest-first:

{ "data": [ { "id": 7, "value": "Welcome aboard!", "author_id": "p_1", "author_name": "Alex", "created_at": "2026-07-04T10:00:00Z", "updated_at": null, "visibility": "external", "can_edit": false } ] }

POST takes { "value": "..." } and returns the created comment. Portal-posted comments are always shared with the customer. PATCH (author only) edits the text.

Field	Meaning
`visibility`	`external` (shared with the customer) — internal comments are never returned here.
`can_edit`	`true` when the session’s person authored it.

React SDK

Install and wrap your app in <StatisfyProvider> (see Portals overview); it supplies the base URL, token minting, and publishable key to every hook and component.

`<ProjectModule/>`

The pre-assembled project view: header, progress, milestone journey, editable task list, project comments, and a task-detail drawer (with per-task comments).

import { ProjectModule } from '@statisfy/digital-workers-react'

// Resolve the onboarding project from the session automatically:
<ProjectModule />

// …or render a specific project:
<ProjectModule projectId="1102" />

`<Comments/>`

A standalone comment thread + composer — project-level, or task-level with a taskId. Used inside <ProjectModule/>, but also available on its own for custom layouts.

import { Comments } from '@statisfy/digital-workers-react'

<Comments projectId="1102" />                 {/* project thread */}
<Comments projectId="1102" taskId="t1" />      {/* task thread */}

`useProject(projectId?)`

Headless data hook for custom layouts. Owns the config → project resolve, the milestone/subtask tree, and optimistic task/project writes with rollback.

import { useProject } from '@statisfy/digital-workers-react'

const { project, milestones, tasksByParent, canEdit, loading, error, updateTask } = useProject()
await updateTask('t1', { status: '10' })

`useComments(projectId, taskId?)`

Headless comments hook. Loads customer-visible comments and posts new ones (optimistically appended).

import { useComments } from '@statisfy/digital-workers-react'

const { comments, loading, posting, addComment } = useComments('1102', 't1')
await addComment('Thanks — looks good!')

`createProjectClient(config)`

The React-unaware transport, if you want to call the API without hooks. Attaches the bearer token and publishable key on every request.

import { createProjectClient } from '@statisfy/digital-workers-react'

const client = createProjectClient({ baseUrl, getToken, publishableKey })
const { data } = await client.getProject('1102')
await client.addTaskComment('1102', 't1', 'Done!')

Method	Endpoint
`getConfig(module)`	`GET /config/{module}`
`getProject(id)`	`GET /projects/{id}`
`patchProject(id, properties)`	`PATCH /projects/{id}`
`patchTask(id, taskId, properties)`	`PATCH /projects/{id}/tasks/{taskId}`
`getProjectComments(id)` / `addProjectComment(id, value)`	`GET` / `POST /projects/{id}/comments`
`getTaskComments(id, taskId)` / `addTaskComment(id, taskId, value)`	`GET` / `POST /projects/{id}/tasks/{taskId}/comments`
`editComment(projectId, commentId, value)`	`PATCH /projects/{id}/comments/{commentId}`

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

Portal SDK: Project API

React SDK

REST API

Authentication

What the customer can see and edit

REST API

Resolve the onboarding project

Read a project

Update a project or task

Comments

React SDK

`<ProjectModule/>`

`<Comments/>`

`useProject(projectId?)`

`useComments(projectId, taskId?)`

`createProjectClient(config)`

React SDK

REST API

​Authentication

​What the customer can see and edit

​REST API

​Resolve the onboarding project

​Read a project

​Update a project or task

​Comments

​React SDK

​<ProjectModule/>

​<Comments/>

​useProject(projectId?)

​useComments(projectId, taskId?)

​createProjectClient(config)

Authentication

What the customer can see and edit

REST API

Resolve the onboarding project

Read a project

Update a project or task

Comments

React SDK

`<ProjectModule/>`

`<Comments/>`

`useProject(projectId?)`

`useComments(projectId, taskId?)`

`createProjectClient(config)`