Skip to content
bucker

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.