HTTP protocol
Map fill and editor routes to browser clients and the in-process API.
Route constants and payload schemas live in @dimah-survey/core.
| Audience | Default base path | Operations |
|---|---|---|
| Fill | /api/survey | Published read and respondent response lifecycle |
| Editor | /api/admin/survey | Authoring, settings, publish, and response analysis |
The suffixes below are appended to those bases. Browser clients take flat
objects; fill.api and editor.api take { query } or { body }. An
operation from the wrong audience is not mounted and returns NOT_FOUND.
List endpoints default to 50 rows and cap at 100.
Fill routes
| Method | Path | Browser client | In-process API |
|---|---|---|---|
GET | /survey/published | getPublishedSurvey(id) | getPublishedSurvey({ query }) |
POST | /response/start | startResponse({ surveyId, respondentId? }) | startResponse({ body }) |
GET | /response | getResponse(id) | getResponse({ query }) |
GET | /responses | listResponses(query) | listResponses({ query }) |
POST | /response/partial | savePartial(input) | savePartial({ body }) |
POST | /response/submit | submitResponse(input) | submitResponse({ body }) |
POST | /response/abandon | abandonResponse(input) | abandonResponse({ body }) |
POST | /response/reopen | reopenResponse(input) | reopenResponse({ body }) |
On survey reads, id accepts a survey id or slug. startResponse.surveyId
accepts either as well. Every response mutation uses the response row id.
getPublishedSurvey returns publishedJson and settings. It omits
draftJson. It is available to both fill principals and does not stamp a
respondent.
The guard stamps respondentId for identified callers. A matching value in the
body is tolerated, but the browser cannot claim another owner. Anonymous
callers cannot list responses; identified callers cannot request
include: "full".
Editor routes
| Method | Path | Browser client | In-process API |
|---|---|---|---|
GET | /survey | getSurvey(id) | getSurvey({ query }) |
POST | /survey | saveSurvey(input) | saveSurvey({ body }) |
GET | /surveys | listSurveys(query) | listSurveys({ query }) |
POST | /survey/publish | publishSurvey(input) | publishSurvey({ body }) |
POST | /survey/archive | archiveSurvey(input) | archiveSurvey({ body }) |
POST | /survey/settings | saveSurveySettings(input) | saveSurveySettings({ body }) |
POST | /survey/resume | resumeSurvey(input) | resumeSurvey({ body }) |
GET | /response | getResponse(id) | getResponse({ query }) |
GET | /responses | listResponses(query) | listResponses({ query }) |
saveSurvey creates the survey when the id is new. slug defaults to id.
Pass expectedUpdatedAt when updating. A create that includes the token fails
with STALE_UPDATE.
listSurveys returns { surveys, limit, offset, nextOffset }.
listResponses returns { responses, limit, offset, nextOffset, total }.
List queries
listResponses accepts:
import type { ListResponsesQuery } from "@dimah-survey/core";Prop
Type
"summary" omits definition and data. "full" is the editor analytics
read. Rows sort by updatedAt descending.
listSurveys accepts:
import type { ListSurveysQuery } from "@dimah-survey/core";Prop
Type
Compare-and-swap inputs
expectedUpdatedAt is optional on draft, publish, archive, settings, resume,
partial save, submit, abandon, and reopen. When it is set, the stored
updatedAt must match or the write fails with STALE_UPDATE. The React
bindings always send the token from their last successful read or write.
The exported Zod schemas are the authoritative payload definitions. See Errors for the stable failure codes.