empirio.ai

Create a new unpublished survey draft. Prefer `mode: "ai"` when the user describes the survey goal, audience, or intent; use `mode: "manual"` when the user has already provided the exact survey content. The server assigns question and option IDs automatically; `question_id` is refused in a question payload. To wire up logic or translations in this same call, give a question a `ref` and reference it from `logic_rules` and `translations`. Use `survey_edit` for later targeted changes, then `survey_publish` to make the survey live. For `text-rating`, put the required answer-button labels in `matrix_columns`; `matrix_rows` is unsupported. For `multiple-choice` and `image-multiple-choice`, omitting `subtitle` materializes a locale-specific multi-select hint and sets `show_subtitle: true`; send `show_subtitle: false` to hide it.

survey_create

Cross-tabulate answers between two non-matrix survey questions. Matrix questions are rejected because the two-axis contract cannot select an individual matrix row.

responses_crosstab

Owner only. Delete responses by `response_ids` (the stable `resp_`/`part_` identifiers returned by `responses_list`, webhook deliveries and exports), by `row_numbers` from `responses_list`, or all responses for a survey. Prefer `response_ids`: row numbers rank the *surviving* rows, so a concurrent deletion shifts them onto different responses. Deleted responses stop being returned by every read surface immediately and cannot be recovered through the API.

responses_delete

Delete a survey and its responses. This cannot be undone through the API: the survey answers 404 from the moment this returns, and its responses, logic rules and translations go with it.

survey_delete

Create a copy of an existing survey (unpublished draft). Owner only: the copy is a new survey owned by the caller, so it leaves the source survey's collaboration entirely. Question, option, matrix-axis and logic-rule IDs are regenerated, and logic references are remapped to those new IDs. The copy has no publication schedule. Counts against the same creation quota as survey_create (10 per hour, 50 per day per account).

survey_duplicate

Update the survey working draft without publishing it. Prefer `mode: "ai"` for prompt-based edits; use `mode: "manual"` when the caller is sending explicit section updates. Re-sending an edit whose result already matches the draft is safe: it answers **200** with an empty `applied_changes` and a warning saying nothing was changed, rather than a conflict. A `409` from this operation means a genuine concurrent modification. Manual edits accept only the sections being changed. Reference existing questions by `question_id`, logic rules by `rule_id`, and options by `option_id` from `survey_get`. For `text-rating`, put the required answer-button labels in `matrix_columns`; `matrix_rows` is unsupported. For `multiple-choice` and `image-multiple-choice`, omitting `subtitle` materializes a locale-specific multi-select hint and sets `show_subtitle: true`; send `show_subtitle: false` to hide it.

survey_edit

Export unlocked survey charts in one of six formats: `pptx` (native editable PowerPoint), `pptx_images` (PowerPoint with raster slides), `pdf`, `docx`, `zip_images` (ZIP of PNG charts), or `chart_json` (structured chart data). Every format answers with the finished export in one call: `chart_json` inline, the other five as a temporary signed download URL valid for one hour plus the actual `file_extension` (`pptx_images` → `pptx`, `zip_images` → `zip`). Rendering takes seconds on a typical survey and about a minute on the largest ones. In `chart_json`, a question's `totalAnswers` is the number of plotted bucket mentions; for multiple-choice this means selections, not respondents. Question types with configured options or a bounded scale keep their complete chart axis, including unused configured values with `count: 0`; historical answered values remain visible after the configured domain changes. Chart exports do not return a row count. A survey with no answers yet has nothing to chart and is refused with `no_chartable_data`.

responses_export_charts

Export unlocked survey responses as CSV, XLSX, JSON, or SPSS and return a temporary signed download URL plus the actual `file_extension`. SPSS is a ZIP bundle. By default, only completed participations are exported unless `include_incomplete_participations=true`.

responses_export

Get aggregate statistics for survey questions. Buckets are sparse: values with no responses are omitted instead of returned with `count: 0`. Percentages use respondents who answered the question (`totalAnswered`) as their denominator, so multi-select percentages can sum above 100%; `totalSelections` reports their selection count. NPS questions also include the computed score and promoter/passive/detractor groups.

responses_aggregates

Get both complete states of a survey: `draft` is the current working draft and `published` is the most recently published definition, or null when the survey has never been published. The top-level status and schedule describe current respondent access. Options, matrix_rows, and matrix_columns in both states are returned as `{option_id, label}` objects. Use `draft` as the basis for edits and `published.questions[].question_id` for response analytics. Translation entries with `status: "pending"` may contain master-locale text as an editable placeholder; that text is not a completed target-locale translation.

survey_get