Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.questra.ai/llms.txt

Use this file to discover all available pages before exploring further.

Survey events fire when IR changes are recorded against a specific survey — when the AI produces or revises the platform-native representation, when a user manually edits the platform IR, and when changesets are created or completed. Subscribe to these events to stream live programming progress into your UI or react to any IR change.

​
Changesets

Changeset events track every grouped mutation to a survey’s platform IR — AI programming, agent-driven revisions, manual edits, platform pulls, and reverts. Each event includes the survey ID so you can route deliveries to the right handler.

​
changeset-started

Fires when a new changeset begins processing. 
{
  "event": "changeset-started",
  "timestamp": "2025-04-01T10:03:00Z",
  "data": {
    "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "survey_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "type": "ai_prompt",
    "status": "in_progress",
    "title": "Applied agent revision"
  }
}
typeDescription
initial_programmingFirst-time AI programming from a questionnaire file
ai_promptAgent-driven revision of the platform IR
revertRollback to a previous IR state
manualManual edit via PUT or PATCH on the platform IR
platform_pullIR synced from the connected platform

​
changeset-completed

Fires when all operations in a changeset have been applied successfully. 
{
  "event": "changeset-completed",
  "timestamp": "2025-04-01T10:05:00Z",
  "data": {
    "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "survey_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "type": "ai_prompt",
    "status": "complete",
    "title": "Applied agent revision"
  }
}

​
changeset-failed

Fires when a changeset encounters an error. 
{
  "event": "changeset-failed",
  "timestamp": "2025-04-01T10:04:00Z",
  "data": {
    "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "survey_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "type": "ai_prompt",
    "status": "error",
    "title": "Applied agent revision"
  }
}

​
changeset-awaiting-approval

Fires when a changeset requires user review before changes are committed — for example, when an agent has produced a pending revision that the user must accept or reject in the diff overlay. 
{
  "event": "changeset-awaiting-approval",
  "timestamp": "2025-04-01T10:04:30Z",
  "data": {
    "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "survey_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "type": "ai_prompt",
    "status": "awaiting_approval",
    "title": "Applied agent revision"
  }
}

​
changeset-operation-added

Fires each time an operation is recorded within an in-progress changeset (for example, as the AI streams changes). 
{
  "event": "changeset-operation-added",
  "timestamp": "2025-04-01T10:03:15Z",
  "data": {
    "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "survey_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "operation_count": 5
  }
}

​
change-recorded (real-time only)

Individual change records are published to a dedicated per-changeset real-time channel as they are written. These events are not delivered via webhooks because of their volume during AI streaming. Channel: org:{orgId}:history:{changesetId} 
{
  "event": "change-recorded",
  "data": {
    "id": "b5c6d7e8-f9a0-1234-bcde-567890123456",
    "changeset_id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "survey_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
    "resource_type": "platformIr",
    "operation": "update",
    "before": { "...": "previous IR snapshot" },
    "after": { "...": "updated IR snapshot" },
    "message": "Applied agent revision",
    "created_at": "2025-04-01T10:03:15Z",
    "order": 0
  }
}
FieldDescription
resource_typeplatformIr — all IR changes are captured against the platform IR blob
operationcreate, update, or delete
before / afterSnapshots of the IR before and after the change
messageHuman-readable description of the change
orderZero-based index within the changeset
Subscribe to the per-changeset channel org:{orgId}:history:{changesetId} to stream individual IR change records in real time. This is useful for building live history feeds.