# Questra Program docs

## Docs

- [Questra](https://docs.staging.questra.ai/index.md): Turn a questionnaire into a logic-ready survey on Decipher, Confirmit, Qualtrics, Alchemer, or Questra.
- [MCP](https://docs.staging.questra.ai/mcp.md): Connect Claude or another MCP client to Questra and program surveys as a signed-in workspace member.
- [Authentication](https://docs.staging.questra.ai/authentication.md): Create a workspace API key and authenticate requests to the Questra Program API.
- [Quickstart](https://docs.staging.questra.ai/quickstart.md): Make your first authenticated request to the Questra Program API.
- [Workflows](https://docs.staging.questra.ai/workflows/overview.md): How Program runs async work — domain starts, generic workflow read/stream, hooks, and tip reconciliation.
- [Live updates](https://docs.staging.questra.ai/workflows/live-updates.md): What each Program workflow publishes for live subscribe — NDJSON World streams, UIMessage SSE, reconnect, and tip reconciliation.
- [Questionnaire clarifications](https://docs.staging.questra.ai/workflows/questionnaire-clarifications.md): survey.questionnaire_clarifications — probe the tip questionnaire and subscribe to identified questions on the run stream.
- [Programming](https://docs.staging.questra.ai/workflows/programming.md): survey.programming — convert a questionnaire into platform content.
- [Content edit](https://docs.staging.questra.ai/workflows/content-edit.md): survey.content_edit — chat over programmed content with AI SDK UIMessage SSE.
- [Review chat](https://docs.staging.questra.ai/workflows/review-chat.md): Browser-SoT coding-agent chat with persisted conversation history.
- [Webhook event types](https://docs.staging.questra.ai/webhooks/event-types.md): Canonical catalog of Program webhook events and their payload schemas. Generated from the storage event registry — do not edit by hand.
- [API overview](https://docs.staging.questra.ai/api-reference/overview.md): REST API for Questra Program.
- [List surveys](https://docs.staging.questra.ai/api-reference/surveys/list-surveys.md): List surveys in the authenticated workspace. Pagination is offset-based (`limit` + `offset`, default 25, max 100) and always applied.
- [Create survey](https://docs.staging.questra.ai/api-reference/surveys/create-survey.md)
- [Get survey](https://docs.staging.questra.ai/api-reference/surveys/get-survey.md)
- [Update survey](https://docs.staging.questra.ai/api-reference/surveys/update-survey.md)
- [Delete survey](https://docs.staging.questra.ai/api-reference/surveys/delete-survey.md)
- [List survey files](https://docs.staging.questra.ai/api-reference/survey-files/list-survey-files.md)
- [Create survey file](https://docs.staging.questra.ai/api-reference/survey-files/create-survey-file.md): Creates a pending file record and returns a presigned upload URL. Upload bytes directly to object storage — not through this API (except local `/_dev/objects` in development). When `content_hash` matches an existing ready file for the survey, returns that file with `existingMatch: true` and no uploa…
- [Get survey file](https://docs.staging.questra.ai/api-reference/survey-files/get-survey-file.md)
- [Update survey file](https://docs.staging.questra.ai/api-reference/survey-files/update-survey-file.md): Partial update for metadata and upload lifecycle (e.g. mark `ready` after upload). Visibility cannot be changed.
- [Delete survey file](https://docs.staging.questra.ai/api-reference/survey-files/delete-survey-file.md): Deletes file metadata and the object blob. Blocked with 409 when any questionnaire revision references the file, unless `force=true` (which removes those revisions first).
- [Create upload URL](https://docs.staging.questra.ai/api-reference/survey-files/create-upload-url.md): Regenerate a presigned PUT URL for a pending or failed file.
- [Create download URL](https://docs.staging.questra.ai/api-reference/survey-files/create-download-url.md): Mint a download URL for a ready file. Private files get a signed URL; public files return the stable public URL.
- [Get latest questionnaire revision](https://docs.staging.questra.ai/api-reference/survey-questionnaire/get-latest-questionnaire-revision.md): Returns the latest questionnaire revision for the survey — a reference to the file set as the current questionnaire copy.
- [Set latest revision](https://docs.staging.questra.ai/api-reference/survey-questionnaire/set-latest-revision.md): Uploads still use the survey file APIs. This endpoint records that a ready file is the latest questionnaire revision. If the latest revision already points at the same `file_id`, returns 200 with the existing revision; otherwise appends a new revision (201).
- [List questionnaire revisions](https://docs.staging.questra.ai/api-reference/survey-questionnaire/list-questionnaire-revisions.md): Newest first. Each revision is a file reference with a monotonic revision number.
- [Get a questionnaire revision](https://docs.staging.questra.ai/api-reference/survey-questionnaire/get-a-questionnaire-revision.md)
- [Get Clarifications session for the tip questionnaire](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/get-clarifications-session-for-the-tip-questionnaire.md): Shortcut for `GET .../questionnaire/revisions/{revision}/clarifications` on the current tip. Side-effect free.
- [Start a clarifications probe on the tip questionnaire](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/start-a-clarifications-probe-on-the-tip-questionnaire.md): Starts a `survey.questionnaire_clarifications` workflow on the tip questionnaire and returns **202** with `workflow_id`, initial `session`, and `stream_url`.
- [Get a tip clarification](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/get-a-tip-clarification.md)
- [Answer or skip a tip clarification](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/answer-or-skip-a-tip-clarification.md): Submit an answer (option shortcut and/or free text) or explicitly skip. Only the tip revision is mutable.
- [Get clarifications probe run status](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/get-clarifications-probe-run-status.md): Thin status for a `survey.questionnaire_clarifications` run (reconcile when the NDJSON stream ends early).
- [Stream clarifications probe chunks (NDJSON)](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/stream-clarifications-probe-chunks-ndjson.md): Projected `QuestionnaireClarificationsStreamChunk` events for this probe run. Reconnect with `startIndex`.
- [Get questionnaire clarifications session for a revision](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/get-questionnaire-clarifications-session-for-a-revision.md): Read-only history for a questionnaire revision. Does not start or advance a probe.
- [Get a clarification for a revision](https://docs.staging.questra.ai/api-reference/survey-questionnaire-clarifications/get-a-clarification-for-a-revision.md): Read-only. Answer/skip only via tip `PATCH .../questionnaire/clarifications/{clarificationId}`.
- [Get current programming status](https://docs.staging.questra.ai/api-reference/survey-programming/get-current-programming-status.md): Survey-scoped programming view. Greenfield runs return lean status plus workflow_id/stream_url (empty phases). Legacy in-flight runs may still include phased product steps. GET is side-effect free.
- [Start programming](https://docs.staging.questra.ai/api-reference/survey-programming/start-programming.md): Creates (or replaces) survey programming via program-from-questionnaire (newest-wins). Cancels any in-flight questionnaire clarifications probe. Returns workflow_id + stream_url for the generic anatomy stream; programming detail is lean (empty phases for greenfield).
- [Set programming target](https://docs.staging.questra.ai/api-reference/survey-programming/set-programming-target.md): Persists the programming target and, when programming is waiting on target selection, resumes that wait. This is the sole client resume path for Compile → Target.
- [Set or skip programming fine-tuning template](https://docs.staging.questra.ai/api-reference/survey-programming/set-or-skip-programming-fine-tuning-template.md): Persists the fine-tuning template on the programming target (`null` clears it and uses the code-owned canonical platform template) and, when programming is waiting on Configure template selection, resumes that wait. Call during Configure before Compile starts.
- [Cancel active programming](https://docs.staging.questra.ai/api-reference/survey-programming/cancel-active-programming.md)
- [Accept partial programming results](https://docs.staging.questra.ai/api-reference/survey-programming/accept-partial-programming-results.md): After transpile, promote the latest platform source to a content tip, stop remaining Fine tune / Verify / Push work, and mark the run completed so the user can Continue to review.
- [Stream programming envelopes (NDJSON)](https://docs.staging.questra.ai/api-reference/survey-programming/stream-programming-envelopes-ndjson.md): Subscribe to StreamEnvelope chunks for this survey’s programming run. Server resolves the World run from the survey binding. Reconnect with `startIndex`.
- [Get latest migration workflow](https://docs.staging.questra.ai/api-reference/survey-migration/get-latest-migration-workflow.md)
- [Start platform migration](https://docs.staging.questra.ai/api-reference/survey-migration/start-platform-migration.md): Creates a new Program survey and starts a `survey.migration` double-compile workflow. Delivery (account or export-only) and the destination survey name are chosen mid-run at the configure gate.
- [Cancel active migration](https://docs.staging.questra.ai/api-reference/survey-migration/cancel-active-migration.md)
- [Get migration run detail](https://docs.staging.questra.ai/api-reference/survey-migration/get-migration-run-detail.md)
- [Stream migration run envelopes (NDJSON)](https://docs.staging.questra.ai/api-reference/survey-migration/stream-migration-run-envelopes-ndjson.md)
- [Resolve a waiting migration hook](https://docs.staging.questra.ai/api-reference/survey-migration/resolve-a-waiting-migration-hook.md): Resume a hook listed on `GET .../migration/runs/{runId}` (e.g. `target_selection`). Prefer `hooks[].resume_path`.
- [List survey audits](https://docs.staging.questra.ai/api-reference/survey-audits/list-survey-audits.md)
- [Start a questionnaire↔survey audit](https://docs.staging.questra.ai/api-reference/survey-audits/start-a-questionnaire↔survey-audit.md): Creates a questionnaire↔survey audit pinned to a saved content revision and starts `survey.audit` (detect only).
- [Get a survey audit](https://docs.staging.questra.ai/api-reference/survey-audits/get-a-survey-audit.md)
- [List audit findings](https://docs.staging.questra.ai/api-reference/survey-audits/list-audit-findings.md)
- [Get an audit finding](https://docs.staging.questra.ai/api-reference/survey-audits/get-an-audit-finding.md)
- [Mark an audit finding resolved or dismissed](https://docs.staging.questra.ai/api-reference/survey-audits/mark-an-audit-finding-resolved-or-dismissed.md)
- [Get the audit proposed source buffer](https://docs.staging.questra.ai/api-reference/survey-audits/get-the-audit-proposed-source-buffer.md)
- [List audit remediations](https://docs.staging.questra.ai/api-reference/survey-audits/list-audit-remediations.md)
- [Start remediations against proposed source](https://docs.staging.questra.ai/api-reference/survey-audits/start-remediations-against-proposed-source.md): Starts `survey.audit.remediate` against this audit’s proposed source (clone of the pinned content revision). Never writes the content tip.
- [Get an audit remediation](https://docs.staging.questra.ai/api-reference/survey-audits/get-an-audit-remediation.md)
- [List conversations](https://docs.staging.questra.ai/api-reference/conversations/list-conversations.md)
- [Create conversation](https://docs.staging.questra.ai/api-reference/conversations/create-conversation.md)
- [Get conversation](https://docs.staging.questra.ai/api-reference/conversations/get-conversation.md)
- [List conversation messages](https://docs.staging.questra.ai/api-reference/conversations/list-conversation-messages.md): Returns persisted AI SDK UIMessages in chronological order for chat history reload.
- [Send conversation messages (AI SDK stream)](https://docs.staging.questra.ai/api-reference/conversations/send-conversation-messages-ai-sdk-stream.md): Streams the survey editor agent as an AI SDK UIMessage SSE response. UIMessages are upserted into this conversation. Tip revisions are created when the client save tool (or Review Save) calls PUT /content — not by this stream itself.
- [Truncate conversation messages from a checkpoint](https://docs.staging.questra.ai/api-reference/conversations/truncate-conversation-messages-from-a-checkpoint.md): Deletes `before_message_id` and every later message so chat history can be restored to the state before that message (e.g. AI Elements checkpoint restore).
- [Get latest content revision](https://docs.staging.questra.ai/api-reference/survey-content/get-latest-content-revision.md): Returns the current Program tip from storage. Does not fetch the linked upstream platform unless `sync=true`. With `sync=true`, best-effort ensure-sync may mint a pull revision; platform fetch failure still returns the last known tip (200) with `upstream_sync.status: unreachable`. Get-by-revision is…
- [Create a new content revision](https://docs.staging.questra.ai/api-reference/survey-content/create-a-new-content-revision.md): When the survey is linked to an upstream platform survey, pushes source there first; tip is written only after a successful push (or when there is no link). After a successful push, re-GETs upstream and persists that document (pull-after-push) so reformatting does not look like drift. Without `force…
- [List content revisions](https://docs.staging.questra.ai/api-reference/survey-content/list-content-revisions.md): Newest first. Pass `include=source` to include full source text.
- [Get a content revision](https://docs.staging.questra.ai/api-reference/survey-content/get-a-content-revision.md)
- [Get workflow](https://docs.staging.questra.ai/api-reference/workflows/get-workflow.md): Lean workflow status for a World run id. Authz: binding must exist in the workspace. Subscribe to raw World NDJSON on `stream_url`.
- [Stream workflow World chunks](https://docs.staging.questra.ai/api-reference/workflows/stream-workflow-world-chunks.md): Raw Workflow SDK default-stream chunks as NDJSON (no domain projection), plus one HTTP `workflow.stream.caught_up` marker after the subscribe-time tail. Reconnect with `startIndex` (omit or `0` to replay from the beginning while the World retains the stream).
- [Resume a workflow hook](https://docs.staging.questra.ai/api-reference/workflows/resume-a-workflow-hook.md): Deliver a JSON payload to a greenfield SDK `createHook` token and resume the run. Configure picker tokens upsert an overwritable draft (POST `{ reset: true }` to reopen a prior step); World resume waits until Configure is awaiting a complete set. Authz: binding must exist for `workflowId` in the wor…
- [List API keys](https://docs.staging.questra.ai/api-reference/api-keys/list-api-keys.md): List API keys for this workspace. Secrets are never included — only `key_hint` is returned.
- [Create API key](https://docs.staging.questra.ai/api-reference/api-keys/create-api-key.md): Create a new API key with explicit scopes. The full `key` is returned once — store it securely; it cannot be retrieved again.
- [Get API key](https://docs.staging.questra.ai/api-reference/api-keys/get-api-key.md): Fetch an API key by id. Does not include the secret.
- [Update API key](https://docs.staging.questra.ai/api-reference/api-keys/update-api-key.md): Update name, enabled state, scopes, or expiry. Does not rotate the secret.
- [Delete API key](https://docs.staging.questra.ai/api-reference/api-keys/delete-api-key.md): Permanently revoke and delete an API key.
- [Rotate API key](https://docs.staging.questra.ai/api-reference/api-keys/rotate-api-key.md): Issues a new secret and invalidates the previous one. Scopes are unchanged. The new `key` is returned once.
- [List integrations](https://docs.staging.questra.ai/api-reference/integrations/list-integrations.md): List workspace integrations for upstream platforms. Credential values are never included — only `credential_fields` names and `credentials_configured`.
- [Create integration](https://docs.staging.questra.ai/api-reference/integrations/create-integration.md): Create a workspace integration with upstream platform credentials. Credential values are write-only: accepted in the request body and **never** returned in the response. Does not call the upstream platform — use `POST /integrations/{id}/test` to verify.
- [Get integration](https://docs.staging.questra.ai/api-reference/integrations/get-integration.md): Fetch an integration by id. Does not include credential values.
- [Update integration](https://docs.staging.questra.ai/api-reference/integrations/update-integration.md): Update name, config, or replace credentials. When `credentials` or `config` is provided, connection test status resets to `untested`. When `credentials` is provided, it replaces the full secret map. Values are write-only and never returned.
- [Delete integration](https://docs.staging.questra.ai/api-reference/integrations/delete-integration.md): Permanently delete an integration and its stored credentials. Blocked with 409 `integration_in_use` when any survey programming target references this integration via `config.integration_id`, unless `force=true` (which unlinks those surveys first — clears delivery keys, keeps platform).
- [Test integration credentials](https://docs.staging.questra.ai/api-reference/integrations/test-integration-credentials.md): Attempt to authenticate with the upstream platform using the stored credentials. Returns success/failure metadata only — never echoes credential values. Updates `last_tested_at` / `last_test_status` only for decisive outcomes (success or credential/auth rejection). Transient network errors do not ch…
- [List integration surveys](https://docs.staging.questra.ai/api-reference/integration-surveys/list-integration-surveys.md): List metadata-only surveys on the upstream platform for this integration. Pagination is always cursor-based (`cursor` + `limit`); Program adapters translate provider-native offset or cursor schemes into opaque `pagination.next_cursor` values. Platforms that cannot catalog-list surveys return 501; lo…
- [Create integration survey](https://docs.staging.questra.ai/api-reference/integration-surveys/create-integration-survey.md): Create a survey on the upstream platform via this integration. Returns metadata only.
- [Get integration survey](https://docs.staging.questra.ai/api-reference/integration-surveys/get-integration-survey.md): Fetch metadata for a single upstream survey.
- [Update integration survey](https://docs.staging.questra.ai/api-reference/integration-surveys/update-integration-survey.md): Update name and/or status on the upstream survey (metadata only).
- [Delete integration survey](https://docs.staging.questra.ai/api-reference/integration-surveys/delete-integration-survey.md): Delete a survey on the upstream platform via this integration.
- [Get latest upstream survey content](https://docs.staging.questra.ai/api-reference/integration-survey-content/get-latest-upstream-survey-content.md): Fetch the tip content revision from the upstream platform. Payload shape matches Program `GET /surveys/{surveyId}/content` (`ContentRevision`).
- [List upstream content revisions](https://docs.staging.questra.ai/api-reference/integration-survey-content/list-upstream-content-revisions.md): Newest first. Pass `include=source` to include full source text. Platforms with queryable history (Questra Publish revisions, Qualtrics survey versions) return multiple revisions. Platforms without API-accessible history (Decipher, ConfirmIt, Alchemer) return a single tip item.
- [Get an upstream content revision](https://docs.staging.questra.ai/api-reference/integration-survey-content/get-an-upstream-content-revision.md): Fetch a single content revision by revision number. For tip-only platforms, only the tip revision number is valid.
- [List integration survey responses](https://docs.staging.questra.ai/api-reference/integration-survey-responses/list-integration-survey-responses.md): List respondent responses for an upstream survey. Returns normalized metadata; pass `include=data` to include opaque platform payloads. Pagination is cursor-based. Results are filtered by workspace `settings/integrations.response_data_access` (default `test` — only `mode: "test"`).
- [Get integration survey response](https://docs.staging.questra.ai/api-reference/integration-survey-responses/get-integration-survey-response.md): Fetch a single respondent response. Returns normalized metadata; pass `include=data` to include the opaque platform payload. Denied when the response `mode` is outside workspace `response_data_access`.
- [List webhook endpoints](https://docs.staging.questra.ai/api-reference/webhook-endpoints/list-webhook-endpoints.md): List workspace-scoped webhook endpoints.
- [Create webhook endpoint](https://docs.staging.questra.ai/api-reference/webhook-endpoints/create-webhook-endpoint.md): Register a URL to receive events. Returns a signing secret once — store it securely. Payloads are signed with Standard Webhooks.
- [Get webhook endpoint](https://docs.staging.questra.ai/api-reference/webhook-endpoints/get-webhook-endpoint.md)
- [Update webhook endpoint](https://docs.staging.questra.ai/api-reference/webhook-endpoints/update-webhook-endpoint.md)
- [Delete webhook endpoint](https://docs.staging.questra.ai/api-reference/webhook-endpoints/delete-webhook-endpoint.md)
- [Rotate webhook signing secret](https://docs.staging.questra.ai/api-reference/webhook-endpoints/rotate-webhook-signing-secret.md): Issues a new signing secret and invalidates the previous one. The new secret is returned once.
- [List deliveries for an endpoint](https://docs.staging.questra.ai/api-reference/webhook-deliveries/list-deliveries-for-an-endpoint.md): Delivery attempts for debugging integrations — status, HTTP responses, and retry history.
- [Get delivery](https://docs.staging.questra.ai/api-reference/webhook-deliveries/get-delivery.md)
- [Redeliver a webhook](https://docs.staging.questra.ai/api-reference/webhook-deliveries/redeliver-a-webhook.md): Enqueue another delivery attempt for this event to this endpoint. Returns 202 when accepted.
- [List events](https://docs.staging.questra.ai/api-reference/events/list-events.md): Immutable event log for reconciliation and backfill. Use event `id` as the consumer idempotency key.
- [Get event](https://docs.staging.questra.ai/api-reference/events/get-event.md)
- [List event types](https://docs.staging.questra.ai/api-reference/events/list-event-types.md): Catalog of event types that webhook endpoints can subscribe to. Sourced from the webhook event registry — see the Event types docs page for payload schemas.
- [Get workspace programming settings](https://docs.staging.questra.ai/api-reference/settings/get-workspace-programming-settings.md)
- [Replace workspace programming settings](https://docs.staging.questra.ai/api-reference/settings/replace-workspace-programming-settings.md)
- [Patch workspace programming settings](https://docs.staging.questra.ai/api-reference/settings/patch-workspace-programming-settings.md)
- [Get default instructions for a platform](https://docs.staging.questra.ai/api-reference/settings/get-default-instructions-for-a-platform.md)
- [Set default instructions for a platform](https://docs.staging.questra.ai/api-reference/settings/set-default-instructions-for-a-platform.md)
- [Get workspace integration settings](https://docs.staging.questra.ai/api-reference/settings/get-workspace-integration-settings.md): Workspace policy for upstream integrations, including which response modes Program may query (`none`, `test`, or `production`).
- [Replace workspace integration settings](https://docs.staging.questra.ai/api-reference/settings/replace-workspace-integration-settings.md): Replace integration settings. `response_data_access: "production"` is not available yet and returns `response_data_access_unavailable`.
- [Patch workspace integration settings](https://docs.staging.questra.ai/api-reference/settings/patch-workspace-integration-settings.md): Partially update integration settings. `response_data_access: "production"` is not available yet and returns `response_data_access_unavailable`.
- [Whoami](https://docs.staging.questra.ai/api-reference/meta/whoami.md): Returns the authenticated user or API-key workspace context.

## OpenAPI Specs

- [program.openapi](https://docs.staging.questra.ai/openapi/program.openapi.json)