Опросы

Управляйте опросами, работайте со скрытыми переменными и настройками

Обзор

API позволяет не только получать список опросов, но и полностью управлять их жизненным циклом: создавать опросы, настраивать структуру вопросов, менять темы, настраивать логику переходов, публиковать, архивировать и работать со скрытыми переменными. Все эндпоинты требуют авторизации через Bearer токен.

Быстрая навигация

Обзор Создание и редактирование Список опросов Данные опроса Вопросы опроса Скрытые переменные Управление Архивные опросы

Скачайте markdown‑версию раздела «Опросы (Quizzes)» для использования в ChatGPT / других LLM:

AI Markdown

/static/api/quizzes.md

AI Markdown

Создание и редактирование опроса

Полный цикл: создать опрос → добавить и настроить вопросы (типы, настройки) → сохранить → применить тему → опубликовать. Ниже — эндпоинты, типы вопросов и их параметры.

1. Создать опрос

POST /quiz

Создаёт новый опрос в указанной папке рабочего пространства текущего пользователя. Проверяются наличие воркспейса, папки и дневной лимит создания опросов.

Тело запроса (JSON)

Поле	Тип	Обязательное	Описание
folder_id	integer	Да	ID папки рабочего пространства, в которой будет создан опрос.

Пример запроса

curl -X POST "https://api.webask.io/api/v3/service/quiz" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id": 5}'

Пример успешного ответа (201)

Основные поля

{
  "id": 124,
  "workspace_id": 1,
  "name": "Опрос #12",
  "virtual_id": "abc12xyz",
  "url_preview": "https://example.com/quiz/124/preview",
  "url_shared": "https://example.com/q/abc12xyz",
  "is_published": false
}

Основные ошибки

HTTP	Код	Описание
400	`workspace_not_found`, `folder_not_found`	Не найдено рабочее пространство пользователя или указанная папка.
401	`user_not_authenticated`	Не передан или недействителен токен авторизации.
403	`quiz_limit_today`	Превышен дневной лимит создания опросов для пользователя.
422	`validation_error`	Ошибка валидации тела запроса (например, не указан `folder_id`).

2. Вопросы опроса (типы и настройки)

После POST /quiz опрос пустой. Вопросы добавляются и редактируются через POST /quiz/{id}/save: передаёте ids (порядок) и entities (конфигурация каждого вопроса). Рекомендуется брать структуру из GET /quiz/{id} (поле widgets), вносить изменения и отправлять обратно.

POST /quiz/{id}/save

Сохраняет структуру вопросов опроса: передаётся массив ids (порядок экранов) и объект entities (конфигурация каждого вопроса). Формат совпадает с полем widgets в ответе GET /quiz/{id}. Рекомендуется брать текущую структуру из ответа, вносить изменения и отправлять обратно.

Тело запроса (JSON)

Поле	Тип	Обязательное	Описание
ids	array	Да	Порядок ID экранов/вопросов (см. ниже)
entities	object	Да	Конфигурация каждого вопроса: ключ = ID из ids

Параметр ids

Порядок элементов задаёт порядок показа вопросов респонденту.

Значение	Описание
welcome	Экран приветствия (начальный)
submit	Экран завершения с кнопкой отправки
UUID	ID обычного вопроса (например a1b2c3d4-e5f6-7890-abcd-ef1234567890)

Основные поля (есть во всех вопросах)

Поле	Тип	Описание
type	string	Обязательно. Тип вопроса (см. таблицу ниже)
title	string	Заголовок вопроса
withTitle	boolean	Показывать заголовок (default: true)
description	string	Описание под заголовком
withDescription	boolean	Показывать описание (default: true)
isRequired	boolean	Обязательный ответ (default: false)
isBlocked	boolean	Вопрос заблокирован (default: false)
multimedia	object \\| null	Картинка/видео/аудио в заголовке (см. ниже)
filling_time_enabled	boolean	Таймер на ответ
filling_time_seconds	integer	Время на ответ в секундах

Типы вопросов

type	Название	Описание
welcome	Экран приветствия	Начальный экран
yesno	Да/Нет	Бинарный выбор
choice	Выбор варианта	Один или несколько вариантов
dropdown	Выпадающий список	Выбор из списка
ranking	Ранжирование	Расположение по приоритету
slider	Слайдер	Значение на шкале
rating	Рейтинг	Звёзды, сердечки и т.д.
scale	Шкала	Числовая шкала
input	Текстовый ввод	Произвольный текст
email	Email	Ввод email
phone	Телефон	Ввод телефона
datetime	Дата/время	Выбор даты
matrix	Матрица	Табличный выбор
message	Сообщение	Информационный блок
file	Загрузка файла	Загрузка файлов
html	HTML блок	Произвольный HTML
submit	Экран завершения	Кнопка отправки

Объект multimedia (медиа в заголовке)

Поле	Описание
type	img, video, audio
imgUrl	URL изображения
videoUrl	URL видео
imgLocation	blocks (внутри) или background (фоном)
videoSettings	controls, autoplay

Поля по типам вопросов

welcome (экран приветствия): welcomeLabel, welcomeWithResponseTime, welcomeWithQuestionCount

submit (экран завершения): submitLabel, submitShowText, submitNextUrl, submitTerms, submitTermsTitle, submitTermsText

choice (выбор): choiceType (text/image), choiceMultiple, choiceRandomize, choiceTextOther; choiceTextIds + choiceTextEntities (UUID → {label, score, isCorrect}); choiceImageIds + choiceImageEntities

yesno: yesNoTextIds, yesNoTextEntities (UUID → {type: yes|no, label, score, isCorrect})

dropdown: dropdownIds, dropdownEntities (UUID → текст), dropdownScores

ranking: rankingIds, rankingEntities, rankingRandomize, swapActive

slider: sliderMin, sliderMax, sliderStep, sliderValue

rating: ratingCount, ratingFigure (star/heart/thumb/smile), ratingValue, ratingWithNumber, ratingScores

scale: scaleCount, scaleStartValue (0/1), scaleLabelLeft/Central/Right, scaleLabelLeftValue, scaleLabelCentralValue, scaleLabelRightValue, scaleScores

input (текст): inputPlaceholder, inputIsTextarea, inputWidth, inputHeight, inputLimit, inputLimitMin, inputLimitMax

email: emailPlaceholder, emailWidth

phone: phonePlaceholder, phoneWidth, phoneIsLimit, phoneLimitMin, phoneLimitMax

datetime: dateTimeType (dateAndTime/date/time), dateTimeFormatOfDate, dateTimeFormatOfTime (12/24), dateTimeSeparator (dot/slash/dash)

matrix: matrixChoiceType (radio/checkbox/text), matrixIsAllRequired, matrixRowIds, matrixColIds, matrixRowEntities, matrixColEntities, matrixTranspose

message: messageLabel, messageWithButton

html: htmlCode, htmlIsEmbedded

Валидация

Каждый ID в ids уникален
Каждый ID из ids есть в entities как ключ
Каждый ключ entities присутствует в ids
У каждого вопроса обязательно поле type (строка)

Пример: добавить вопрос с рейтингом

curl -X POST "https://api.webask.io/api/v3/service/quiz/123/save" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["welcome", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "submit"],
    "entities": {
      "welcome": { "type": "welcome", "title": "Добро пожаловать", "welcomeLabel": "Начать" },
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890": { "type": "rating", "title": "Оцените сервис", "ratingCount": 5, "ratingFigure": "star" },
      "submit": { "type": "submit", "submitLabel": "Отправить" }
    }
  }'

Ошибки

HTTP	Описание
400	Опрос не найден (not_found)
401	Не авторизован
403	Нет доступа к опросу
422	Ошибка валидации ids/entities или полей вопроса
500	Ошибка при сохранении на сервере

Получить список опросов

GET /quiz

Получает список всех ваших опросов. В API v3 поддерживаются сортировка и пагинация.

Query‑параметры

Параметр	Тип	Обязательный	Описание
sort	string	Нет	Поле сортировки: `created_at`, `updated_at`, `name`, `id`
order	string	Нет	Направление сортировки: `desc`, `asc` (по умолчанию: desc)
limit	integer	Нет	Количество записей (минимум 1). По умолчанию — все.
offset	integer	Нет	Смещение для пагинации (минимум 0, по умолчанию 0).

Пример запроса

curl -X GET "https://api.webask.io/api/v3/service/quiz?sort=name&order=asc&limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ API

[
  {
    "id": "ID опроса",
    "name": "название",
    "url_shared": "адрес опроса",
    "is_published": true,
    "folder": {
      "id": 384,
      "workspace_id": 384,
      "user_id": 12,
      "name": "Мои опросы",
      "pos": 1,
      "is_default": true,
      "created_at": "2022-04-01T08:37:14.000000Z",
      "updated_at": "2022-04-27T15:46:27.000000Z",
      "deleted_at": null
    }
  }
]

Получить данные опроса

GET /quiz/{id}

Получает детальную информацию о конкретном опросе.

Пример запроса

curl -X GET https://api.webask.io/api/v3/service/quiz/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ API

{
  "id": "ID опроса",
  "answer_count": "количество ответов",
  "name": "название",
  "url_shared": "адрес опроса",
  "widgets": "структура вопросов (ids, entities)",
  "hidden_options": "скрытая переменная",
  "folder": {
    "id": 384,
    "workspace_id": 384,
    "user_id": 12,
    "name": "Мои опросы",
    "pos": 1,
    "is_default": true,
    "created_at": "2022-04-01T08:37:14.000000Z",
    "updated_at": "2022-04-27T15:46:27.000000Z",
    "deleted_at": null
  }
}

Скрытые переменные

Получить список скрытых переменных

GET /quiz/{id}/hidden/options

Получает список скрытых переменных для опроса.

Пример запроса

curl -X GET https://api.webask.io/api/v3/service/quiz/123/hidden/options \
  -H "Authorization: Bearer YOUR_TOKEN"

Создать скрытую переменную

POST /quiz/{id}/hidden/options/create

Создает новую скрытую переменную для опроса.

Параметры запроса

Параметр	Тип	Обязательный	Описание
name	string	Да	Название скрытой переменной
value	string	Да	Значение скрытой переменной

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/hidden/options/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "productType",
    "value": "clientShop"
  }'

Обновить скрытую переменную

POST /quiz/{id}/hidden/options/update/{opt_id}

Обновляет существующую скрытую переменную.

Параметры запроса

Параметр	Тип	Обязательный	Описание
name	string	Да	Новое название скрытой переменной
value	string	Да	Новое значение скрытой переменной

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/hidden/options/update/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "productType",
    "value": "updatedValue"
  }'

Удалить скрытую переменную

POST /quiz/{id}/hidden/options/delete/{opt_id}

Удаляет скрытую переменную.

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/hidden/options/delete/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Скрытые переменные в вопросах

Получить скрытую переменную в вопросе

GET /quiz/{id}/widgets/hidden/options

Получает список скрытых переменных для конкретного вопроса.

Пример запроса

curl -X GET https://api.webask.io/api/v3/service/quiz/123/widgets/hidden/options \
  -H "Authorization: Bearer YOUR_TOKEN"

Отправить скрытую переменную в вопросе

POST /quiz/{id}/widgets/hidden/options/create

Создает новую скрытую переменную для конкретного вопроса.

Параметр	Тип	Описание	Обязательный
name	string	Название скрытой переменной	Да
value	string	Значение скрытой переменной	Да
widget_uuid	string	UUID вопроса	Да

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/widgets/hidden/options/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "productType",
    "value": "clientShop",
    "widget_uuid": "c63b9a88-2f1b-4735-a7ab-0b5fd84c90c2"
  }'

Обновить скрытую переменную в вопросе

POST /quiz/{id}/widgets/hidden/options/update/{opt_id}

Обновляет существующую скрытую переменную в вопросе.

Параметр	Тип	Описание	Обязательный
name	string	Новое название скрытой переменной	Да
value	string	Новое значение скрытой переменной	Да

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/widgets/hidden/options/update/123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "productType",
    "value": "clientShop"
  }'

Удалить скрытую переменную в вопросе

POST /quiz/{id}/widgets/hidden/options/delete/{opt_id}

Удаляет скрытую переменную из вопроса.

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/widgets/hidden/options/delete/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Управление опросами

Ниже приведён полный жизненный цикл опроса через API: от настройки структуры вопросов до применения темы, публикации и настройки логики переходов.

Полный цикл опроса (кратко)

POST /quiz/{id}/save

Сохраняет структуру вопросов опроса: порядок экранов (ids) и их конфигурацию (entities). Формат совпадает с полем widgets в ответе GET /quiz/{id}. Рекомендуется брать текущую структуру, вносить изменения и отправлять обратно.

Пример запроса

curl -X POST "https://api.webask.io/api/v3/service/quiz/123/save" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["welcome", "question-1", "submit"],
    "entities": {
      "welcome": { "type": "welcome", "...": "..." },
      "question-1": { "type": "choice", "title": "...", "...": "..." },
      "submit": { "type": "submit", "...": "..." }
    }
  }'

POST /quiz/{id}/applyTheme/{theme_id}

Применяет визуальную тему к локальной версии опроса: цвета, фон, шрифты и другие настройки оформления берутся из выбранной темы. Тело запроса не требуется, передаются только параметры пути.

Пример запроса

curl -X POST "https://api.webask.io/api/v3/service/quiz/123/applyTheme/925" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

POST /quiz/{id}/publish

Публикует опрос: копирует текущую локальную версию (вопросы, настройки) в публичную и делает её доступной по публичной ссылке url_shared. Аналог кнопки «Опубликовать» в интерфейсе конструктора.

Пример запроса

curl -X POST "https://api.webask.io/api/v3/service/quiz/123/publish" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

POST /quiz/{id}/conditions

Сохраняет логические условия опроса: переходы между экранами, условия по ответам, баллам и т.п. Тело запроса — объект conditions с сохранённой логикой. Пустой объект очищает логику.

Пример запроса

curl -X POST "https://api.webask.io/api/v3/service/quiz/123/conditions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": {
      "...": "структура логики, как в конструкторе"
    }
  }'

Добавление заметки к опросу

POST /quiz/{id}/note

Добавляет заметку к опросу (максимум 1000 символов).

Параметры запроса

Параметр	Тип	Обязательный	Описание
notes	string	Да	Текст заметки (максимум 1000 символов)

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/note \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Текст заметки (максимум 1000 символов)"
  }'

Ответ API

{
  "status": true,
  "notes": "Текст заметки"
}

Дублирование опроса

POST /quiz/{id}/duplicate

Дублирует опрос с возможностью указать новое название.

Параметры запроса

Параметр	Тип	Обязательный	Описание
name	string	Нет	Название копии (опционально)

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/duplicate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Название копии (опционально)"
  }'

Ответ API

{
  "status": true,
  "quiz": {
    "id": 123,
    "name": "Копия: Название опроса",
    "url_shared": "https://example.com/abc123",
    "is_published": false,
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z",
    "folder": {
      "id": 1,
      "name": "Моя папка"
    }
  }
}

Переименование опроса

POST /quiz/{id}/rename

Переименовывает опрос.

Параметры запроса

Параметр	Тип	Обязательный	Описание
name	string	Да	Новое название опроса

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/rename \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Новое название опроса"
  }'

Ответ API

{
  "status": true,
  "name": "Новое название опроса"
}

Создание шаблона из опроса

POST /quiz/{id}/template

Превращает опрос в шаблон для повторного использования.

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/template \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ API

{
  "status": true
}

Архивирование опроса

POST /quiz/{id}/archive

Архивирует или разархивирует опрос.

Параметры запроса

Параметр	Тип	Обязательный	Описание
archive	boolean	Да	true - архивировать, false - разархивировать

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/archive \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "archive": true
  }'

Ответ API

{
  "status": true,
  "archive_at": "2024-01-01T12:00:00Z",
  "is_archived": true
}

Перемещение опроса

POST /quiz/{id}/move

Перемещает опрос в другую папку.

Параметры запроса

Параметр	Тип	Обязательный	Описание
folder_id	integer	Да	ID папки для перемещения

Пример запроса

curl -X POST https://api.webask.io/api/v3/service/quiz/123/move \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_id": 5
  }'

Ответ API

{
  "status": true,
  "folder_id": 5,
  "folder": {
    "id": 5,
    "name": "Новая папка"
  }
}

Удаление опроса

DELETE /quiz/{id}

Удаляет опрос и все связанные с ним данные.

Пример запроса

curl -X DELETE https://api.webask.io/api/v3/service/quiz/123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ API

{
  "status": true
}

Архивные опросы

GET /quiz/archived

Получает список всех архивных опросов.

Пример запроса

curl -X GET https://api.webask.io/api/v3/service/quiz/archived \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ API

[
  {
    "id": 123,
    "name": "Архивный опрос",
    "url_shared": "https://example.com/abc123",
    "is_published": false,
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z",
    "archive_at": "2024-01-02T12:00:00Z",
    "folder": {
      "id": 1,
      "name": "Моя папка"
    }
  }
]

Предыдущий раздел

Следующий раздел