Lifecycle & versioning

A survey moves through five states. Edits to a published survey create new versions without disturbing in-flight respondents, and you can roll back to any prior version at any time.

Status transitions

               publish              pause
  ┌─────────┐ ────────► ┌────────┐ ────────► ┌────────┐
  │  DRAFT  │           │ ACTIVE │           │ PAUSED │
  └─────────┘           └────────┘ ◄──────── └────────┘
                             │      resume        │
                             │                    │
                             │     complete       │
                             ▼                    │
                        ┌───────────┐  complete   │
                        │ COMPLETED │ ◄───────────┘
                        └───────────┘
                             │
                             │ archive
                             ▼
                        ┌───────────┐
                        │ ARCHIVED  │
                        └───────────┘

State	Behavior
draft	Not visible to respondents. No public URL. Edits modify the document in place — no version forking until you publish.
active	Live. Respondents can take the survey via any open distribution channel. Edits create a new pending version alongside the live one.
paused	Temporarily stopped. In-flight respondents can finish; new arrivals see a "survey paused" page. Resume reopens collection.
completed	Permanently closed. Responses are final, the public URL serves a closing page. Clone the survey to start a new collection round.
archived	Hidden from default lists but still queryable. Use to keep a long-tail of finished studies tidy without losing the underlying data. Filter listings by status=archived to see them.

Publish

Publishing transitions a survey from draft (or paused) to active. This is the point where the survey becomes available to respondents. The current document is pinned as version 1 and the current_version pointer is set.

Pre-publish validation

The platform runs a quality check before publishing. Issues are returned as warnings but do not block the publish:

• Unknown identifiers in skip logic DSL
• Invalid DSL expressions
• Unreachable questions (skipped by all paths)
• Post-logic identifier references

Run validation explicitly with the spellcheck endpoint beforehand (see Build).

REST API

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/publish \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Response (200 OK):

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "name": "Brand Perception Study Q1 2026",
  "status": "active",
  "current_version": 1,
  "revision": 2,
  "published_at": "2026-05-26T15:30:00Z"
}

Agent

"Publish my survey"

The agent triggers a confirmation prompt before executing — publishing is flagged as a destructive action because subsequent edits create new versions rather than modifying in place.

Pause

Pausing temporarily stops a survey from accepting new responses. Respondents who are mid-survey can finish, but new arrivals see a paused page. The version pointer is unchanged.

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/pause \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

{
  "id": "a1b2c3d4-...",
  "status": "paused"
}

Resume by calling publish again (POST .../publish). No data is lost.

Agent

"Pause the survey"

"Resume the Costco brand study"

Complete

Completing permanently closes response collection. Unlike pause, this is final — the survey becomes read-only. Clone it to start a new collection round.

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/complete \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

{
  "id": "a1b2c3d4-...",
  "status": "completed",
  "completed_at": "2026-06-15T09:00:00Z"
}

Agent

"Close out the survey — we have enough responses"

Versioning model

A survey is a long-lived container. Its content lives in immutable survey_version rows. Each time you change questions, options, or logic on a published survey, a new version is written. The survey's current_version pointer determines what respondents see; edits land in a pending draft until you push them live.

How it works

1. Draft surveys have one version. Edits modify it in place.
2. Published surveys fork on edit. The live version stays live while a new pending version accumulates changes.
3. Push flips the current_version pointer atomically. New respondents see the updated version; respondents already mid-survey finish on the version they started.
4. Responses always reference the version they were collected against, so renaming a question does not rewrite historical data.

List versions

curl https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/versions \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

[
  {
    "id": "ver-001",
    "survey_id": "a1b2c3d4-...",
    "version": 1,
    "document": { "blocks": [ "..." ] },
    "changes_summary": null,
    "changed_by": "f0e1d2c3-...",
    "created_at": "2026-05-26T14:00:00Z"
  },
  {
    "id": "ver-002",
    "survey_id": "a1b2c3d4-...",
    "version": 2,
    "document": { "blocks": [ "..." ] },
    "changes_summary": "Added Q6 NPS question",
    "changed_by": "f0e1d2c3-...",
    "created_at": "2026-05-27T10:15:00Z"
  }
]

Agent

"Show me the version history"

Get a specific version

curl https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/versions/1 \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Returns the full version object including its document snapshot.

Compare versions

The agent's compare_versions tool diffs two versions by question label, showing what was added, removed, or modified.

"What changed between version 1 and version 3?"

The diff output structure:

{
  "version_a": 1,
  "version_b": 3,
  "added": [
    { "label": "Q6", "text": "How likely are you to recommend us?", "type": "nps", "block": "Evaluation" }
  ],
  "removed": [],
  "modified": [
    {
      "label": "Q2",
      "before": { "text": "Which brands have you used?", "type": "select", "block": "Screener" },
      "after":  { "text": "Which brands have you purchased in the last 6 months?", "type": "select", "block": "Screener" }
    }
  ],
  "total_changes": 2
}

Push a version live

After editing a published survey, the pending version does not go live until you explicitly push it.

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/versions/2/push \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Response: the full survey detail with the updated document.

Agent

"Push the changes live"

The agent confirms before pushing, since this changes what respondents see.

Create a draft from the live version

For published surveys without a pending draft, fork the live version into an editable copy:

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/draft \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

This is idempotent: if a pending draft already exists, the existing draft is returned.

Restore a previous version

Restoring rolls back a bad change. It copies the old version's document into a new version — versions are immutable, so "undo" is always a new row. History is preserved.

"Go back to version 1"

After restoring, you get a new version with the old content. Push it live to make respondents see it.

Agent

"Undo the last change"

"Restore version 2"

Version record fields

Every version row records:

Field	Description
version	Monotonically increasing integer per survey
document	Full survey document snapshot (blocks, questions, logic)
changes_summary	Short description of what changed (auto-filled by agent, editable)
changed_by	UUID of the user who created this version
created_at	Timestamp

Clone

Cloning creates an exact copy of a survey as a new draft. The clone gets all questions, logic, and settings from the source's current version. Responses do not carry over.

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/clone \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID" \
  -d '{ "name": "Brand Study Wave 2" }'

Response (201 Created): the full survey detail of the new draft.

Use cases:

• Reopen collection on a completed survey (the original stays read-only as a historical record)
• Create an A/B variant with different question orderings
• Hand off a design to a colleague as a starting point

Agent

"Clone the brand study as Brand Study Wave 2"

Translate

Translation creates a new survey (via clone) with all user-facing text translated to the target language. The translation is AI-powered and preserves question labels, DSL logic conditions, and document structure. The original survey is untouched.

curl -X POST https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID/translate \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID" \
  -d '{
    "target_language": "Spanish",
    "new_name": "Estudio de Percepcion de Marca Q1 2026"
  }'

{
  "original_survey_id": "a1b2c3d4-...",
  "translated_survey_id": "e5f6a7b8-...",
  "translated_survey_name": "Estudio de Percepcion de Marca Q1 2026",
  "language": "Spanish",
  "texts_translated": 47
}

What gets translated: question text, option text, block names, helper text on Van Westendorp/conjoint/percent-sum inputs, and conjoint attribute and level labels. What stays unchanged: question labels (Q1, S2), DSL conditions (Q2 == `6` ), IDs, and structural configuration.

Agent

"Translate my sneaker survey to Japanese"

Delete

Soft-deletes the survey. Data is preserved for audit purposes but the survey no longer appears in listings or accepts responses. This cannot be undone through the API.

curl -X DELETE https://surveys.flashpoint.ai/api/v1/surveys/$SURVEY_ID \
  -H "X-Service-Token: $TOKEN" \
  -H "X-Team-ID: $TEAM_ID" \
  -H "X-User-ID: $USER_ID"

Response: 204 No Content.

Things to know

• Publish requires at least one question. An empty draft returns an error.
• Pausing does not cancel email sends in flight. Queued email invitations still go out — recipients who click through see the paused page.
• Completed is terminal. Reopen collection by cloning to a new draft.
• Versions are immutable. You cannot delete or rewrite a version. Use restore to roll back.
• Each save is one version. Rapid edit-save loops on a published survey produce a chain of small versions. This is expected and cheap.
• Mutations are locked. Concurrent REST mutations on the same survey are serialized via a Redis lock. Agent-side operations use optimistic concurrency with automatic retry.

Next steps

• Build the survey content: Build
• Start from a pre-built design: Templates
• Hand it to respondents: Distribute
• Analyze results: Analyze