Versions API

View the publish history and version snapshots of your forms.

The Versions API lets you view the publish history of a form. Every time you publish a form, NueForm creates a versioned snapshot containing the complete form configuration and all questions at that point in time. Versions also include a changelog summarizing what changed since the previous publish.

All response bodies use snake_case field names.

Endpoints

GET/api/v1/forms/:id/versions

List Form Versions

GET/api/v1/forms/:id/versions

Returns all published versions of a form, ordered by version number (most recent first). Each version includes the full form snapshot and a changelog of what was modified.

Path Parameters

idstringrequired

The form ID

Response Fields

idstring

Unique version ID

form_idstring

The form this version belongs to

versioninteger

Sequential version number (1, 2, 3, ...)

published_bystring

User ID of the person who published this version

published_by_namestring

Display name of the person who published

created_atstring

ISO 8601 timestamp of when this version was published

changelogarray

List of changes since the previous version

changelog[].typestring

Change type (see Changelog Entry Types below)

changelog[].descriptionstring

Human-readable description of the change

snapshotobject

Complete form state at publish time (includes all form fields and questions)

Changelog Entry Types

form_createdstring

The form was initially created

publishedstring

A publish event (includes version number)

question_addedstring

A new question was added

question_updatedstring

An existing question was modified

question_deletedstring

A question was removed

question_reorderedstring

Questions were reordered

theme_changedstring

A theme property was modified

settings_changedstring

A form setting was modified

title_changedstring

The form title was changed

description_changedstring

The form description was changed

Response

json

{
  "versions": [
    {
      "id": "66c3d4e5f6a7b8c9d0e1f2a3",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "version": 3,
      "published_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "published_by_name": "Alice Johnson",
      "created_at": "2026-02-28T14:00:00.000Z",
      "changelog": [
        {
          "type": "question_updated",
          "description": "Updated question: \"How did you hear about us?\""
        },
        {
          "type": "question_added",
          "description": "Added question: \"Would you recommend us to a friend?\""
        },
        {
          "type": "theme_changed",
          "description": "Changed theme color from #6366f1 to #2563eb"
        }
      ],
      "snapshot": {
        "title": "Customer Feedback Survey",
        "description": "Help us improve our product",
        "theme_color": "#2563eb",
        "background_color": "#ffffff",
        "show_progress_bar": true,
        "questions": [
          {
            "id": "66a1b2c3d4e5f6a7b8c9d001",
            "type": "short_text",
            "title": "What is your name?",
            "required": true,
            "order": 0,
            "properties": {}
          },
          {
            "id": "66a1b2c3d4e5f6a7b8c9d002",
            "type": "multiple_choice",
            "title": "How did you hear about us?",
            "required": true,
            "order": 1,
            "properties": {
              "choices": [
                { "label": "Search engine" },
                { "label": "Social media" },
                { "label": "Friend or colleague" },
                { "label": "Other" }
              ]
            }
          },
          {
            "id": "66a1b2c3d4e5f6a7b8c9d004",
            "type": "yes_no",
            "title": "Would you recommend us to a friend?",
            "required": false,
            "order": 2,
            "properties": {}
          }
        ]
      }
    },
    {
      "id": "66c2d3e4f5a6b7c8d9e0f1a2",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "version": 2,
      "published_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "published_by_name": "Alice Johnson",
      "created_at": "2026-02-15T10:30:00.000Z",
      "changelog": [
        {
          "type": "question_added",
          "description": "Added question: \"How did you hear about us?\""
        }
      ],
      "snapshot": { ... }
    },
    {
      "id": "66c1d2e3f4a5b6c7d8e9f0a1",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "version": 1,
      "published_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "published_by_name": "Alice Johnson",
      "created_at": "2026-01-15T10:30:00.000Z",
      "changelog": [
        {
          "type": "form_created",
          "description": "Created form"
        }
      ],
      "snapshot": { ... }
    }
  ]
}

Code Examples

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/versions" \
  -H "Authorization: Bearer YOUR_API_KEY"

How Versioning Works

Edit -- Make changes to your form (add questions, update theme, modify settings). The form's has_unpublished_changes flag is set to true.
Publish -- Call POST /api/v1/forms/:id/publish to create a new version. NueForm takes a snapshot of the current form state, records the changelog, and increments the version number.
Live form -- Respondents always see the latest published version. The published_version_id on the form points to the active version.
Unpublish -- Call DELETE /api/v1/forms/:id/publish to take the form offline. The version history is preserved.

The current form state (editable via the Forms API) may differ from the latest published version if edits have been made since the last publish.

Error Responses

Standard error responses returned by this endpoint.

Error Codes

401Unauthorized

Missing or invalid API key

403Forbidden

Insufficient permissions for team forms

404Not Found

Form not found

500Server Error

Internal server error

Error Example

json

{
  "error": "Form not found"
}

Last updated: May 23, 2026