Программный доступ (API)

Нужно собирать квизы скриптом или агентом, без кликов по холсту. Для этого у проекта есть API-токены.

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

Токен — это машинный доступ, не вход человека в панель и не замена приглашения участника.

Где взять токен

Страница проекта → «Настройки» → вкладка «API-токены» (видна только владельцу проекта).

Подсказка в интерфейсе: токен даёт доступ к квизам этого проекта; храните его как пароль.

Нажмите «Создать токен» (диалог «Новый API-токен»):

Поле	Зачем
Название	Обязательно
Описание	По желанию
Срок действия	По умолчанию «Без срока»; можно указать дату
Права	Те же чекбоксы, что в модалке «Новая роль»: проект; квизы, сертификаты, интеграции, промокоды и сегменты заявок (смотреть, редактировать, создавать, удалять); заявки — смотреть и удалять

Над чекбоксами — «Заполнить из роли»: копирует права выбранного пресета. Токен не получит больше прав, чем есть у вас (владельца).

Публикация входит в право «Квизы — Редактировать», отдельного переключателя нет.

По умолчанию: проект «Открыть», квизы «Смотреть + Редактировать + Создавать».

Если создателя токена исключили из проекта, токен перестаёт работать (запросы → ошибка доступа).

Полный ключ сервер покажет один раз (окно вроде «Сохраните токен») — скопируйте и храните как пароль. Ключ начинается с twiqo_. В списке дальше виден только короткий prefix вида twiqo_<8 символов>….

В таблице токенов: название (и описание), Prefix, кем и когда создан, последний запрос, срок. Иконка ключа открывает права токена (только просмотр). Отзыв — отдельной кнопкой в строке.

Отозвать токен можно в любой момент. После отзыва запросы с этим ключом больше не проходят.

Как вызывать API

В заголовке:

Authorization: Bearer <токен>

База — URL API сервиса (тот же хост, что у конструктора). Префикс машинных ручек: /api/v1.

Права токена действуют только внутри этого проекта. Квиз из другого проекта API не найдёт.

Полный список методов и тел запросов — в OpenAPI (/api/docs на сервере API).

Основные ручки:

• GET /api/v1/me
• GET /api/v1/submissions — заявки проекта («Заявки — Смотреть» и «Квизы — Смотреть»); query isComplete=false — в т.ч. незавершённые (открытия), по умолчанию только завершённые
• GET / POST /api/v1/quizzes — в карточке квиза есть opensCount, completionsCount, conversionPercent
• POST /api/v1/templates/:slug/copy — копия шаблона в проект («Квизы — Создавать»)
• GET / PATCH /api/v1/quizzes/:quizId
• GET / PUT /api/v1/quizzes/:quizId/draft (query strict=1 или true)
• GET /api/v1/quizzes/:quizId/published
• POST /api/v1/quizzes/:quizId/validate
• POST /api/v1/quizzes/:quizId/publish (нужно «Квизы — Редактировать»)

Минимальный сценарий: создать квиз → записать черновик графа (блоки и связи) → проверить → при необходимости опубликовать.

curl -sS "$API_URL/api/v1/me" \
  -H "Authorization: Bearer <токен>"