Protocol
REST routes, client methods, form.api calls, and request payloads.
Route paths, payloads, and response shapes live in @dimah-form/core. Default base path: /api/form.
Form Management Endpoints
| Method | Path | Client Method | form.api Method | Description |
|---|---|---|---|---|
GET | /form | getForm({ formId }) | getForm({ query }) | Retrieve form definition snapshot by ID or slug. |
POST | /form | saveForm(form) | saveForm({ body }) | Upsert dynamic form definition in database. |
POST | /form/delete | deleteForm({ formId }) | deleteForm({ body }) | Delete form (rejected if responses exist). |
GET | /forms | listForms({ status?, limit?, offset? }) | listForms({ query }) | List forms (default limit: 50, max: 100). |
Response Lifecycle Endpoints
| Method | Path | Client Method | form.api Method | Description |
|---|---|---|---|---|
POST | /response/start | startResponse({ formId, respondentId?, resume? }) | startResponse({ body }) | Start fill session and freeze definition snapshot. |
GET | /response | getResponse({ responseId }) | getResponse({ query }) | Retrieve a full response record by ID. |
GET | /responses | listResponses({ formId?, respondentId?, status?, limit?, offset? }) | listResponses({ query }) | List response summaries (or full rows with include=full). |
POST | /response/draft | saveDraft({ responseId, answers, updatedAt? }) | saveDraft({ body }) | Save partial answers patch on active draft. |
POST | /response/submit | submitResponse({ responseId, answers?, updatedAt? }) | submitResponse({ body }) | Validate answers vs snapshot and finalize submission. |
POST | /response/abandon | abandonResponse({ responseId, updatedAt? }) | abandonResponse({ body }) | Lock draft response as abandoned. |
POST | /response/reopen | reopenResponse({ responseId, updatedAt? }) | reopenResponse({ body }) | Unlock submitted/abandoned response back to draft. |
POST | /response/delete | deleteResponse({ responseId }) | deleteResponse({ body }) | Delete a response record. |
Endpoint Details & Payloads
1. POST /response/start
Starts a new fill session for a questionnaire.
- Request Body:
{ "formId": "feedback", "respondentId": "user-123", "resume": true } - Response Body (
200 OK):{ "id": "resp_01h8x...", "formId": "feedback", "status": "draft", "definition": { "id": "feedback", "slug": "feedback", "title": "Product Feedback", "fields": [...] }, "answers": {}, "respondentId": "user-123", "submittedAt": null, "createdAt": "2026-09-19T10:00:00.000Z", "updatedAt": "2026-09-19T10:00:00.000Z" }
2. POST /response/draft
Saves a partial patch of answers. Setting a key to null deletes that answer.
- Request Body:
{ "responseId": "resp_01h8x...", "answers": { "fullName": "Jane Doe", "rating": "great" }, "updatedAt": "2026-09-19T10:00:00.000Z" } - Response Body (
200 OK): UpdatedResponseRecord.
3. POST /response/submit
Validates all visible required answers against the snapshot schema and locks the response to "submitted".
- Request Body:
{ "responseId": "resp_01h8x...", "answers": { "fullName": "Jane Doe", "rating": "poor", "improvements": "Please improve loading speed." }, "updatedAt": "2026-09-19T10:05:00.000Z" } - Response Body (
200 OK): UpdatedResponseRecordwithstatus: "submitted".