Protocol
HTTP routes, client methods, and form.api calls.
Paths and payloads live in @dimah-form/core. Default prefix: /api/form.
Client methods are on createFormClient(). Server methods are form.api.* and take { query } or { body }, plus optional headers for guard.
List endpoints default to 50 rows and cap at 100.
Forms
| Method | Path | Client | form.api |
|---|---|---|---|
GET | /form | getForm({ formId }) | getForm({ query }) |
POST | /form | saveForm(form) | saveForm({ body }) |
POST | /form/delete | deleteForm({ formId }) | deleteForm({ body }) |
GET | /forms | listForms({ status?, limit?, offset? }) | listForms({ query }) |
formId is an id or a slug.
saveForm and deleteForm reject code-authored forms (CODE_AUTHORED_FORM).
deleteForm also rejects a form that still has responses (FORM_HAS_RESPONSES).
listForms returns { forms, limit, offset, nextOffset }.
When updating a database-authored form, include its last updatedAt; a
concurrent write fails with STALE_UPDATE.
Responses
| Method | Path | Client | form.api |
|---|---|---|---|
POST | /response/start | startResponse({ formId, respondentId?, resume? }) | startResponse({ body }) |
GET | /response | getResponse({ responseId }) | getResponse({ query }) |
GET | /responses | listResponses({ formId?, respondentId?, status?, submittedFrom?, submittedTo?, updatedAfter?, include?, limit?, offset? }) | listResponses({ query }) |
POST | /response/draft | saveDraft({ responseId, answers, updatedAt? }) | saveDraft({ body }) |
POST | /response/submit | submitResponse({ responseId, answers?, updatedAt? }) | submitResponse({ body }) |
POST | /response/abandon | abandonResponse({ responseId, updatedAt? }) | abandonResponse({ body }) |
POST | /response/reopen | reopenResponse({ responseId, updatedAt? }) | reopenResponse({ body }) |
POST | /response/delete | deleteResponse({ responseId }) | deleteResponse({ body }) |
listResponses returns summaries unless include is "full". total is the matching count, not the page size.
submittedFrom / submittedTo are inclusive and skip rows with no submittedAt. updatedAfter is an exclusive lower bound on updatedAt.
import type { ResponseListFilter } from "@dimah-form/server";Prop
Type
Payloads
startResponse freezes the definition and seeds defaultValue. resume: true needs respondentId and returns the latest draft when one exists.
saveDraft.answers is a patch; null deletes that key.
submitResponse.answers, when present, replaces the complete answer map. Omit
it to submit the stored draft. Send updatedAt from the last read — a mismatch
is 409 STALE_UPDATE.
submitResponse evaluates showWhen, drops hidden answers, then checks every visible field. Success sets status: "submitted" and submittedAt.
The success body is a ResponseRecord, except
list routes, which return a page.
Plugin routes
Plugin routes use the same basePath. Their method name is also the default
guard.operation.
| Package | Method and path | Client and form.api method |
|---|---|---|
| Scoring | GET /scoring/response | getResponseScores |
| Dataset | GET /dataset/responses | getDatasetPage |
| Dataset | GET /dataset/codebook/history | getDatasetCodebook |
| Dataset | GET /dataset/codebook | getLiveCodebook |
| Insights | GET /insights/summary | getFormInsights |
| Insights | GET /insights/crosstab | getFormCrosstab |
Install the matching *ClientPlugin() to expose these methods in the browser.
Authorize Dataset and Insights as administrative reads; Scoring reads a stored
response and should follow the same ownership policy as getResponse.