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

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

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

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

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

Страница проекта → «Участники» → блок «API-токены».

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

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

Поле	Зачем
Название	Обязательно
Описание	По желанию
Срок действия	По умолчанию «Без срока»; можно указать дату
Права	Чекбоксы ниже

Права:

• «Чтение квизов и черновика» (quizzes:read)
• «Создание квизов и запись черновика» (quizzes:write)
• «Публикация» (quizzes:publish)
• «Все права (quizzes:admin)» — полный доступ; взаимоисключает набор отдельных прав

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

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

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

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

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

В заголовке:

Authorization: Bearer <токен>

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

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

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

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

• GET /api/v1/me
• GET / POST /api/v1/quizzes
• 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 <токен>"