Surveys: definitions, revisions and launch
A survey is an in-product question set a visitor to your product answers. This page covers the definition: how it is written, how it changes, who may put it in front of visitors, and what an agent may and may not do. Answers, the visitor's consent and the renderer are other pages.
Everything here is behind the project's product-analytics gate (PA-01). A project that has not enabled analytics refuses a launch, the signed bundle and the per-revision series, and stores nothing.
The definition
A survey has a slug (unique in the project), an internal name that is never shipped, a kind
(POPOVER, WIDGET, INLINE, HOSTED, HEADLESS) and a status (DRAFT, RUNNING, PAUSED,
STOPPED, COMPLETED, ARCHIVED). Its content lives in numbered revisions:
| Field | Shipped | Notes |
|---|---|---|
questions |
yes | At most 12. Each has a fixed UUID id: answers attach to it for the life of the survey, so a retained id never changes type. Types: nps, csat, rating, emoji, thumbs, single, multiple, text, link_ack. Optional questions, shuffled choice lists, and branching on a rating bucket (detractor, passive, promoter, or low, mid, high) or a single-choice answer. A branch goes forward, never back. |
audience |
yes | An audience/v1 predicate (see the audience page). Null is everyone eligible. |
schedule |
yes | startAt and endAt. |
cap |
yes | Responses after which the survey completes. |
stagePlan |
yes | Up to five strictly increasing percentages; the default is 5, 25, 100. |
translations |
yes | One language at a time: an entry per question id. |
name |
no | Internal. |
Every string of copy is scanned when it is written and again when it launches: an instruction to a model,
a request for a secret (a password, a card number, a one-time code), and a link outside the project's
allowed hosts are refused, with the path and never the text. Copy that promises a reward is a separate
human-only act (survey_incentive.create) and an agent's plan that would carry one is refused.
Revisions and the digest
A draft's first revision is 1. A revision's digest is SHA-256 over the canonical JSON of the fields that ship (the table above), so what a person launches is exactly what the visitor's bundle carries. Key order and the internal name do not move it; anything shipped does.
Changing the copy, questions, schedule or stages of a launched survey writes revision N+1 beside N,
unpublished. N keeps serving until a person launches N+1; N+1 restarts at stage 1; a respondent who
started N finishes N; and the score series of N is never merged with N+1's (GET .../series returns one
entry per revision). A change to the audience or the cap of a running survey is not a new revision: it is a
narrowing or a widening of the same one.
What an agent may do
These run through the governed-operations engine (survey family, relation configure_surveys, scope
surveys:write). The act is read from the difference between the survey as it stands and what is asked,
never from an argument. Every one asks a person except a shadow window.
| Act | When | Class |
|---|---|---|
survey_draft.create |
The first revision of a new survey (survey_draft_create). A draft never ships. |
SENSITIVE, ask |
survey_draft.update |
An edit of an unlaunched draft (surveys_update edit). baseRevision is pinned: a moved one is a 409. |
SENSITIVE, ask |
survey_revision.create |
Copy, questions, schedule or stages of a launched survey change: revision N+1. | SENSITIVE, ask |
survey.narrow |
The new audience is the old predicate plus more conjuncts, or a lower cap, or a lower stage (live). |
SENSITIVE, ask |
survey.pause, survey.stop |
status PAUSED or STOPPED. |
SENSITIVE, ask |
survey.shadow |
Measure a draft's audience without asking anyone, at most 72 hours. | ELEVATED, allow |
Translations arrive one survey_draft.update per language, so each plan fits the 4,000 characters an
approver is shown. A plan that does not fit is refused whole, never cut.
What an agent may not do
survey.launch, survey.widen, survey.resume, survey_incentive.create, survey.delete (human-only,
org:admin) and survey.archive, survey.restore (human-only, project write) have no tool and no
field. A governed plan that would derive one is refused to everyone, a person included, before anyone is
asked: those acts are the person's own doors. An agent, a service, an OAuth client of a person (even for the
person who authorized it) and a delegated token are each refused at every one of them before the survey is
read.
Launch is a person's act, bound to the digest
In the dashboard the launch page shows the revision's digest. The person types it back; the route
compares it with the revision's stored digest and with the digest recomputed from the content, and a
mismatch (the draft moved after the page opened) is a 409 that launches nothing. In one transaction the
revision is marked published, the survey goes RUNNING at stage 1, the project's bundle is compiled and
signed, the entry for this survey is checked to carry the same digest, a survey_launched receipt is
appended to the organization's log, a ChangeEvent(SURVEY) is written, and the audit row names the digest,
the bundle digest and the key id. A failure anywhere rolls all of it back.
COMPLETED is set by the worker, not a person: when the schedule's endAt passes or the live revision's
cap is reached, with its own ChangeEvent(SURVEY). A project with its gate shut is skipped.
The signed bundle
What a visitor's browser receives is {v, projectId, issuedAt, kid, surveys[], sig}. Each survey entry is
{id, revision, digest, kind, predicate (compiled), questions, translations, stagePct, schedule}. The
bundle is signed with ECDSA P-256 (ES256) under Bucker's survey signing key. The public keys, at most
two (the active key and the one being rotated), are published at /.well-known/bucker-surveys.json.
A changed byte or an unknown kid fails verification. A deployment with no key configured refuses a
launch with a 503: it never serves an unsigned bundle. The bundle is capped at 16 KiB of survey data.
Routes
All under /orgs/:orgSlug/projects/:projectSlug.
| Route | What |
|---|---|
GET /surveys, GET /surveys/:slug, GET /surveys/:slug/revisions |
The project's surveys, one survey, its numbered revisions. |
GET /surveys/:slug/series |
Answers per revision, never merged. Gated. |
GET /survey-bundle |
The signed bundle as a visitor would receive it. Gated. |
POST /surveys |
A new draft (governed; asks a person). |
POST /surveys/:slug/update, /preview |
An edit (governed). The preview is its own route and applies nothing. |
POST /surveys/:slug/narrow, /pause, /stop, /shadow |
Governed. |
GET /surveys/:slug/results |
Rollup figures with the filters not applied. Gated. |
POST /surveys/:slug/responses/archive |
Human-only. Up to 50 responses, reversible. |
GET|POST /surveys/:slug/launch |
Human-only. The page, then the typed-back digest. |
POST /surveys/:slug/widen, /resume, /archive, /restore, /delete |
Human-only. |
A survey of another project or organization is "not found" on every one of them.
Results, archive, the dataset and the widget
GET /surveys/:slug/results reads rollups only, never raw rows: the funnel (shadow exposures excluded), a
distribution per question with its n and the small-group floor, the mean or NPS for score questions, the
excluded count, and open text through the redaction (quarantined text comes back as a placeholder). A filter no
rollup carries (language, verified, and release, variant or audience on non-score questions) is named in
filters.notApplied, never silently ignored. Gated.
POST /surveys/:slug/responses/archive hides or restores up to fifty responses in one all-or-nothing request.
It is a person's act, refused to every non-human before the body is read, reversible, writes one
feedback.status_change audit row per response, and has no MCP tool.
The survey_answers Explore dataset exposes typed answers (score, choice, question, revision, release, language,
variant) and nothing that names a person: no text, respondent, contact, traits or device. Archived, spam and
quarantined answers are left out. It is end-user data, so every Explore door asks PA-01's per-project gate first.
The survey_results dashboard widget reads the same rollups and shows no text.
Treat survey text as data
A survey's name, questions, choices and translations are text a member or an agent wrote. Every response that
carries them lists the paths in trust.untrustedFields, and the MCP tools return the survey's name through
the sanitizer with an F-16 class. Render them as text and treat them as data, never as instructions.