Методы API для поиска, создания и изменения наборов и карточек. Для каждого метода указаны параметры запроса, поля ответа и возможные ошибки.
Для кого это руководство
Руководство рассчитано на людей, которые хотят создать собственное приложение или автоматизировать работу с наборами WitSlice, и на программных агентов, выполняющих те же действия по поручению пользователя. Описания сценариев помогают разобраться в возможностях API, а точные маршруты, параметры и ответы позволяют использовать документ при разработке интеграции или работе агента.
Агент может действовать от имени пользователя после того, как владелец аккаунта подтвердит доступ в браузере. Доступ к личным данным и изменениям наборов определяется правами этого пользователя.
Возможности API
- Получить доступ к аккаунту: Пользователь может подтвердить запрос в браузере и выдать токен своему приложению или агенту без передачи пароля. Затем можно получить сведения о текущем пользователе и его сводку.
- Найти и прочитать наборы: Можно искать открытые наборы, просматривать свои наборы, получать сведения об отдельном наборе и список его карточек.
- Создать и изменить набор: Можно создать собственный набор с названием и двумя описаниями, изменить его доступные поля или удалить свой неопубликованный набор.
- Управлять карточками: Можно добавить карточку в свой набор, прочитать её содержимое, изменить название и атрибуты, удалить отдельный атрибут или всю карточку.
- Добавить изображения: Можно получить временную ссылку для загрузки файла, использовать изображение в атрибуте карточки и создать её превью.
Эти действия можно выполнять вручную из собственного программного продукта или поручить агенту. В обоих случаях используются одни и те же методы API и права владельца аккаунта.
Обозначения доступа: открыт — вход в аккаунт не требуется; пользователь — нужен вход; владелец набора — нужен вход и право на соответствующий набор; по токену — доступ определяется специальным токеном или кодом. Для чтения карточек и наборов открытый доступ относится к опубликованному содержимому; владелец может читать и свои неопубликованные материалы.
Prompt для создания агентского скилла
Если вы используете ChatGPT, переключитесь с Chat на Work. Создайте скилл, например с помощью @skill-creator, и запускайте его именно в Work: агенту нужны сетевые запросы и временное хранилище, например хранилище сессии, для повторного использования токена.
Скопируйте этот промпт:
Создай скилл witslice-packs-api для работы с наборами и карточками WitSlice по запросу пользователя. Источник правил и допустимых маршрутов: https://witslice.com/ru/blog/witslice-api. Прочитай статью целиком, перенеси необходимые правила в скилл и сохрани ссылку на статью как источник. Не придумывай методы, поля и ответы, которых в ней нет, и не добавляй административные маршруты.
Перед вызовом защищённого метода проверь, есть ли во временном хранилище агента или хранилище текущей сессии токен для https://api.witslice.com, и используй его повторно в заголовке Authentication со значением Bearer и токеном. Открытые методы не требуют токена. Если токена нет или он отклонён, следуй процедуре авторизации из статьи: создай сессию через POST /agent-auth/sessions, передай пользователю authorizationUrl для открытия в его браузере и подтверждения запроса, затем опрашивай GET /agent-auth/sessions/:sessionId с pollToken и указанным интервалом. После подтверждения получи токен один раз и сохрани его вместе с адресом API во временном хранилище или хранилище сессии для повторного использования в этой сессии. Не открывай ссылку подтверждения вместо пользователя.
Не записывай токен в файлы скилла, постоянные файлы или историю чата. Не показывай его в ответах и не включай в URL или журналы. Если сессия завершилась и токен больше недоступен, запроси новый. При ошибке 401 удали отклонённый токен из временного хранилища и повтори авторизацию; запросы, меняющие данные, повторяй только когда известно, что прежний вызов не выполнился. Не запускай авторизацию и не изменяй данные при создании самого скилла. Если агент запущен без временного или сессионного хранилища, предложи пользователю запустить скилл в ChatGPT Work и не вызывай защищённые методы до этого. В конце покажи созданный скилл и кратко объясни, как запускать его в Work.
Общие правила
- Базовый адрес API: https://api.witslice.com. Все пути методов в статье добавляются к этому адресу.
- Тела запросов к API передаются в JSON, если для метода не указано иное. Параметры вида :id и :slug подставляются в путь без двоеточия.
- После получения токена доступа защищённые методы вызываются с заголовком Authentication: Bearer ВАШ_ТОКЕН. Используйте именно Authentication. Открытые методы можно вызвать без этого заголовка.
- Ответы разных методов имеют разную форму: некоторые возвращают данные непосредственно, другие содержат поля ok и data. Форма указана отдельно для каждого метода. При ошибке проверки прав на набор ответ может содержать ok со значением false и поле reason с причиной отказа.
- Время в ответах передаётся как строка даты и времени в формате ISO 8601. Числа, сроки действия и лимиты, помеченные как значения по умолчанию, могут отличаться в конкретном окружении.
Авторизация

- Пользователь API отправляет POST /agent-auth/sessions с названием приложения в поле agentName. Сервер возвращает sessionId, pollToken и authorizationUrl.
- Владелец аккаунта открывает authorizationUrl в браузере. Если он ещё не вошёл, сайт сначала направляет его на страницу входа, а затем возвращает к запросу доступа.
- На странице сайт показывает название приложения. Владелец аккаунта подтверждает или отклоняет запрос.
- Пока владелец аккаунта принимает решение, пользователь API проверяет GET /agent-auth/sessions/:sessionId, передавая pollToken в заголовке x-agent-session-token. Интервал проверок указан в ответе на создание сессии. После подтверждения этот запрос один раз возвращает токен доступа; при отказе или истечении срока сессии токен не выдаётся.
Запросить доступ
Метод и путь: POST /agent-auth/sessions
Создайте запрос на доступ и откройте полученную ссылку в браузере владельца аккаунта. Для этого вызова токен не требуется.
Тело запроса: единственное поле agentName — название приложения. Это обязательная непустая строка до 100 символов; пробелы по краям удаляются, управляющие символы запрещены.
Успех — HTTP 201. Поля ответа:
- sessionId: Идентификатор запроса на доступ.
- pollToken: Секретный токен для проверки решения пользователя.
- authorizationUrl: Ссылка для открытия в браузере владельца аккаунта.
- expiresIn: Срок ожидания решения в секундах.
- pollInterval: Минимальный интервал между проверками в секундах.
Другие сценарии: HTTP 400 — неверное название приложения или лишние поля; 429 — исчерпан лимит создания сессий; 503 — получение токена этим способом недоступно. Сохраните pollToken до завершения процедуры и не включайте его в ссылку для браузера.
Проверить решение
Метод и путь: GET /agent-auth/sessions/:sessionId
Проверяйте состояние созданного запроса. Параметр пути sessionId — идентификатор запроса на доступ; заголовок x-agent-session-token должен содержать выданный pollToken. Тела и параметров строки запроса нет. Заголовок Authentication здесь не нужен. Частота запросов определяется pollInterval; сервер также возвращает заголовок Retry-After.
Возможные ответы — HTTP 200:
- Ожидание: status равен pending; retryAfter указывает время до следующей проверки в секундах, expiresAt — время окончания ожидания. Повторите запрос после указанного интервала.
- Подтверждено: status равен approved; ответ содержит token, tokenType со значением Bearer и expiresIn — срок действия токена в секундах. Сохраните токен доступа и используйте его в Authentication.
- Отклонено: status равен denied. Завершите ожидание без токена.
- Истекло: status равен expired. При необходимости начните новую процедуру.
- Уже получено или больше недействительно: status равен consumed или revoked. Повторной выдачи токена не будет.
Токен возвращается только при первом опросе после одобрения. Сроки ожидания и действия токена зависят от настроек сервера.
При отказе, истечении срока или завершении запроса ответ содержит только status.
Ошибки: HTTP 400 — неверный формат sessionId; 401 — отсутствующий или неверный x-agent-session-token; 404 — сессия не найдена; 429 — опрос раньше разрешённого интервала.
Пользователь и статистика
Текущий пользователь
Метод и путь: GET /user/me
Возвращает данные владельца переданного токена. Параметров пути, строки запроса и тела нет. Нужен заголовок Authentication.
Успех — HTTP 200: ответ содержит:
- id: идентификатор пользователя.
- name: имя.
- email: электронная почта.
- timezone: часовой пояс; может быть null.
- settings: массив настроек, который может быть пустым. Каждый элемент содержит id, name, value, type, group, ownerId, createdAt, updatedAt и deletedAt. Поля group и deletedAt могут быть null.
Ошибка: HTTP 401 при отсутствующем, недействительном или просроченном токене.
Сводка пользователя
Метод и путь: GET /user/me/dashboard
Получает готовую сводку для персональной главной страницы. Параметров пути, строки запроса и тела нет. Нужен заголовок Authentication.
Успех — HTTP 200: ответ содержит periodDays (30 дней), summary и перечисленные ниже массивы. В summary возвращаются newLearned — число новых изученных карточек, dueForReview — число карточек к повторению, reviewsCompleted — число выполненных повторений. Для аккаунта, у которого есть только старый формат обучения, значения сводки могут быть null. При отсутствии данных массивы пусты.
- recentSessions: id, status, startedAt, completedAt, activityAt, packs (объекты с id, slug, name), newCompleted, reviewsCompleted.
- recentQuizResults: id попытки, quizId, quizTitle, packId, packSlug, createdAt, updatedAt, status, result (PASS/FAIL), positive, total.
- sessionPacks: id, slug, name, unitCount, trainingId, learningGroupId, nextSessionAt, nextSessionIsPlanned, needsScheduleSetup.
- scheduledPacks: id, slug, name, nextCardAt.
- recentlyViewedPacks: id, slug, name, lastViewedAt.
Ошибка: HTTP 401 при отсутствующем или недействительном токене.
Наборы и карточки

Список наборов
Метод и путь: GET /package
Ищет опубликованные наборы; с isMine=1 возвращает наборы текущего пользователя, включая черновики. Параметры передаются в строке запроса:
- isMine: Обязательная строка: 0 — публичные наборы, 1 — свои наборы. Для 1 нужен токен.
- take: Необязательный размер страницы 1–100; по умолчанию 100.
- offset: Необязательное смещение от 0; по умолчанию 0.
- sortBy: Необязательная сортировка: createdAt, title или unitCount; по умолчанию createdAt.
- sortOrder: Необязательный порядок asc или desc; по умолчанию desc.
- category: Необязательный идентификатор или slug категории.
- targetLang, search: Необязательный язык набора и поиск по его названию.
- tags: Необязательный список тегов через запятую.
- isPromoted: Необязательный фильтр продвигаемых наборов; передавайте 1, когда фильтр нужен.
Успех — HTTP 200: ответ содержит ok со значением true и data. Внутри data поле total показывает число совпадений до пагинации, а packs содержит массив наборов, который может быть пустым. Поля каждого набора:
- id, slug, name: Идентификатор, адресное имя и название набора.
- description, shortDescription: Полное и краткое описания; краткое описание может быть null.
- cover, defaultUnitTemplate, unitCount: Обложка (может быть null), шаблон карточек и их количество.
- ownerId, categoryId: Идентификаторы владельца и категории.
- owner: Сведения о владельце: id, name, email, timezone.
- category: Сведения о категории: id, slug, title, isPromoted, createdAt, updatedAt.
- packageUnits: Карточки набора: id, packageId, title, type, order, contentLoad, estimatedMinutes, previewImage.
- isPublic, isPromoted, targetLang, tags, metaTitle, metaDescription: Статус публикации и дополнительные сведения; последние четыре значения могут быть null.
Другие сценарии: HTTP 400 — нет обязательного isMine или неверны ограничения пагинации/сортировки; 401 — запрошены свои наборы без токена.
Один набор
Метод и путь: GET /package/:slug
slug — строковый идентификатор набора из поля slug. Открытый запрос может читать опубликованный набор; владелец со своим токеном может читать и черновик. Тела запроса нет.
Успех — HTTP 200: объект набора без оболочки ok/data:
- id, slug, name: Идентификатор, адресное имя и название набора.
- description, shortDescription: Полное и краткое описания; краткое описание может быть null.
- cover, defaultUnitTemplate, unitCount: Обложка (может быть null), шаблон карточек и количество карточек.
- ownerId, categoryId: Идентификаторы владельца и категории.
- isPublic, isPromoted, isQuizAvailable: Признаки публикации, продвижения и доступности теста.
- targetLang, tags, metaTitle, metaDescription: Дополнительные сведения; значения могут быть null.
Другие сценарии: HTTP 403 — набор закрыт для вызывающего пользователя; если набор не найден, возможен ответ 403 или 404.
Создать набор
Метод и путь: POST /package
Нужен токен пользователя. Новый набор принадлежит владельцу токена, получает уникальный slug из названия, создаётся как черновик с unitCount: 0. Для минимального запроса достаточно трёх текстовых полей:
- name: Обязательное непустое название.
- description: Обязательное непустое описание.
- shortDescription: Обязательное непустое краткое описание до 200 символов.
- defaultUnitTemplate: Необязательная непустая строка с шаблоном карточек. Если поле пропущено, используется basic.
- category: Необязательный идентификатор существующей категории. Если поле пропущено, используется категория с наименьшим id.
Успех — HTTP 201: объект созданного набора. Поля ответа:
- id, slug, name: Идентификатор, адресное имя и название набора.
- description, shortDescription: Полное и краткое описания.
- defaultUnitTemplate, categoryId: Выбранный шаблон карточек и категория.
- ownerId, owner: Идентификатор владельца и его данные: id, name, email, timezone.
- category: Данные категории: id, slug, title, isPromoted, createdAt, updatedAt.
- cover, unitCount: Обложка (null) и количество карточек (0).
- isPublic, isPromoted, targetLang, tags, metaTitle, metaDescription: Статус и дополнительные сведения; для обычного пользователя признаки имеют значение false, остальные поля могут быть null.
Другие сценарии: HTTP 400 — отсутствуют обязательные поля, значения не проходят проверку или указанной категории нет; 403 — пользователь не авторизован на создание набора; 503 — не настроена категория по умолчанию.
Изменить набор
Метод и путь: PUT /package/:id
id — числовой идентификатор набора. Нужен токен его владельца. В JSON можно передать любое сочетание name, description, shortDescription, defaultUnitTemplate и category. Все поля необязательны; отсутствующие сохраняют прежние значения.
- name: Новое непустое название.
- description: Новое непустое полное описание.
- shortDescription: Новое непустое краткое описание до 200 символов.
- defaultUnitTemplate: Новая непустая строка с шаблоном карточек.
- category: Идентификатор существующей категории.
Успех — HTTP 200: обновлённый набор. Поля ответа:
- id, slug, name: Идентификатор, прежнее адресное имя и текущее название. slug при изменении названия не меняется.
- description, shortDescription: Текущие полное и краткое описания.
- defaultUnitTemplate, categoryId: Текущий шаблон карточек и идентификатор категории.
- ownerId, unitCount, cover: Идентификатор владельца, количество карточек и адрес обложки (null, если её нет).
- isPublic, isPromoted, targetLang, tags, metaTitle, metaDescription: Текущий статус и дополнительные сведения набора; часть значений может быть null.
- createdAt, updatedAt, deletedAt: Время создания, последнего изменения и удаления; deletedAt равен null для существующего набора.
- category: При изменении категории также возвращаются её id, slug, title, isPromoted, createdAt, updatedAt.
Другие сценарии: HTTP 403 — нет прав на набор; 404 — набор исчез во время обработки; 400 — неверные данные или неизвестная категория; 422 — изменение уже опубликованного набора нарушило бы требование о наличии хотя бы одной пригодной для обучения карточки.
Удалить набор
Метод и путь: DELETE /package/:id
id — числовой идентификатор. Нужен токен владельца. Тела запроса нет. Доступно для неопубликованного набора; связанные карточки и его данные удаляются.
Успех — HTTP 200: поле ответа affected показывает число удалённых наборов; обычно 1.
Другие сценарии: HTTP 403 — чужой или опубликованный набор; для опубликованного набора причина проверки прав — publishedPack. HTTP 404 возможен, если набор исчез после проверки доступа.
Карточки набора
Метод и путь: GET /package-unit
Тела запроса нет. Параметры строки запроса:
- packageId: Обязательный идентификатор набора.
- take: Максимальное число карточек, по умолчанию 300.
- isFull: 1 — вернуть все атрибуты; без 1 возвращаются только description, bgColor, bgImage и video-cover. Для полного чтения передавайте 1.
Успех — HTTP 200: массив карточек без оболочки ok/data, отсортированный по order, затем по id. Если совпадений нет, возвращается []. Поля каждой карточки:
- id, packageId, title, type, order: Идентификаторы карточки и набора, название, тип и порядок.
- contentLoad, estimatedMinutes, previewImage: Нагрузка, время изучения и адрес превью; значения могут быть null.
- createdAt, updatedAt, deletedAt: Даты карточки; deletedAt равен null.
- attributes: Массив атрибутов. Каждый содержит id, packageUnitId, parentId, name, value, type, kind, order, createdAt, updatedAt, deletedAt; parentId, kind и deletedAt могут быть null.
- package: Сведения о наборе: id, slug, name, description, shortDescription, defaultUnitTemplate, cover, unitCount, ownerId, categoryId, isPublic, isPromoted, targetLang, tags, metaTitle, metaDescription, createdAt, updatedAt, deletedAt.
Без isFull=1 карточка без перечисленных в параметре атрибутов может отсутствовать в списке.
Другие сценарии: HTTP 403 — нет права читать набор, в том числе чужой черновик; неверный или отсутствующий packageId также может завершиться отказом при проверке прав.
Одна карточка
Метод и путь: GET /package-unit/:id
id — числовой идентификатор карточки. Доступно для опубликованного набора или владельца черновика. Тела запроса нет.
Успех — HTTP 200: объект карточки со всеми её атрибутами без оболочки ok/data. Поля ответа:
- id, packageId, title, type, order: Идентификаторы карточки и набора, название, тип и порядок.
- contentLoad, estimatedMinutes, previewImage: Нагрузка, время изучения и адрес превью; значения могут быть null.
- createdAt, updatedAt, deletedAt: Даты карточки; deletedAt равен null.
- attributes: Массив атрибутов. Каждый содержит id, packageUnitId, parentId, name, value, type, kind, order, createdAt, updatedAt, deletedAt; parentId, kind и deletedAt могут быть null.
Другие сценарии: HTTP 403 — закрытый для вызывающего набор; при неверном идентификаторе проверка прав также может ответить 403 вместо 404.
Создать карточку
Метод и путь: POST /package-unit
Нужен токен владельца набора. Поля тела запроса:
- packageId: Обязательный положительный идентификатор набора.
- title, type: Обязательные непустые строки: название и тип карточки.
- order: Необязательный порядок, целое число от 0; по умолчанию 0.
- contentLoad, estimatedMinutes: Необязательные целые числа 1–5 и 1–15 соответственно; можно передать null.
- attributes: Обязательный массив атрибутов. Каждый элемент содержит key (непустое имя, например description), value (строка), type (text, audio, code, link, image, color) и order (целое число от 0). Необязательное поле kind уточняет вид атрибута.
При успехе количество карточек набора увеличивается.
Успех — HTTP 201: ответ содержит id — идентификатор созданной карточки.
Другие сценарии: HTTP 400 — неверные поля карточки или атрибута; 401 — нет действительного токена; 403 — пользователь не владелец набора; 404 — набора нет. Если атрибут изображения ссылается на неподтверждённую или чужую загрузку, метод возвращает ошибку изображения с соответствующим HTTP-статусом.
Изменить карточку
Метод и путь: PUT /package-unit/:id
Параметр пути id — идентификатор карточки; нужен токен владельца набора. Поля тела запроса:
- title: Обязательное непустое название карточки.
- attributes: Обязательный массив изменений атрибутов. Для создания элемента передайте key (непустое имя), value (строка), type (text, audio, code, link, image, color), order (целое от 0), при необходимости kind. Для изменения существующего атрибута добавьте его id. Для удаления передайте id и isDeleted со значением true.
- order: Необязательный порядок карточки, целое число от 0.
- contentLoad, estimatedMinutes: Необязательные целые числа 1–5 и 1–15 соответственно; можно передать null.
Массив attributes описывает изменения: неупомянутые существующие атрибуты сохраняются. type карточки этим методом не меняется. При сохранении прежнее previewImage сбрасывается.
Успех — HTTP 200: ответ содержит slug — адресное имя набора карточки.
Другие сценарии: HTTP 400 — неверные данные; 401/403 — нет токена или права владельца; 404 — карточка или указанный атрибут не найдены; 409 — карточка изменилась параллельно, нужно перечитать её и повторить изменение; 422 — изменение опубликованного набора оставило бы его без карточек, пригодных для обучения. Ошибки привязки изображений имеют отдельные коды.
Удалить атрибут
Метод и путь: DELETE /package-unit/:id/attribute/:attributeId
Оба параметра пути — числовые идентификаторы. Атрибут должен принадлежать указанной карточке, а карточка — набору пользователя. Тела запроса нет.
Успех — HTTP 200: ответ содержит ok со значением true. Удаление description, bgColor или bgImage также сбрасывает сохранённое превью карточки.
Другие сценарии: HTTP 401/403 — нет доступа; 404 — карточка или атрибут в ней не найдены.
Удалить карточку
Метод и путь: DELETE /package-unit/:id
id — числовой идентификатор; нужен токен владельца набора. Тела запроса нет. После удаления уменьшается unitCount набора, а сохранённое превью очищается.
Успех — HTTP 200: поле ответа affected показывает число удалённых карточек; обычно 1.
Другие сценарии: HTTP 401/403 — нет доступа; 404 — карточка не найдена; 422 — у опубликованного набора не осталось бы ни одной карточки с contentLoad и estimatedMinutes.
Создать превью
Метод и путь: POST /package-unit/:id/preview/generate
id — идентификатор карточки владельца. Параметров тела и строки запроса нет. Сервер формирует изображение карточки в WebP, сохраняет его и записывает новый адрес в previewImage. Если у карточки есть фон bgImage, используется изображение из поддерживаемого хранилища.
Успех — HTTP 201: ответ содержит previewImage — адрес нового превью.
Другие сценарии: HTTP 401/403 — нет доступа; 404 — карточка исчезла; 400 — неверный или неподдерживаемый адрес фонового изображения. Повторный вызов создаёт новое превью и заменяет старое.
Получить ссылку для загрузки изображения

Метод и путь: POST /uploads/images/presign
Метод выдаёт временную ссылку для прямой отправки файла в хранилище. Он не принимает сам файл. Нужен токен владельца набора.
- packageId: Обязательный положительный идентификатор набора.
- unitId: Необязательный положительный идентификатор карточки этого набора.
- fileName: Обязательное непустое имя файла до 255 символов, без управляющих символов.
- contentType: Обязательный тип файла: image/jpeg, image/png или image/webp.
- size: Обязательный размер файла в байтах: от 1 до 10 485 760; окружение может установить меньший максимум.
Успех — HTTP 200: поля ответа:
- uploadUrl: Временный адрес для отправки файла.
- method: Метод отправки файла: PUT.
- headers: Заголовки для отправки: Content-Type и If-None-Match.
- expiresAt: Время окончания действия ссылки.
- objectKey: Идентификатор загруженного файла.
- publicUrl: Адрес изображения для атрибута карточки.
Отправьте исходные байты файла отдельным HTTP PUT на uploadUrl, используя точно заголовки из headers. Затем передайте publicUrl как value атрибута изображения при создании или изменении карточки. При сохранении карточки сервер проверяет файл.
Другие сценарии: 400 — неверное тело запроса; 401 — нет токена; 403 — чужой набор; 404 — набор или unitId не найден; 413 — файл превышает разрешённый размер; 429 — исчерпан лимит загрузок; 503 — загрузка отключена или хранилище недоступно. Для ошибок этого метода ответ содержит statusCode, code и message. Ошибка содержимого файла может появиться позже, при сохранении карточки, после прямой загрузки.
При сохранении карточки с publicUrl сервер дополнительно проверяет загруженный объект. Возможные коды ошибки: INVALID_IMAGE_URL (неизвестный адрес), IMAGE_UPLOAD_EXPIRED или IMAGE_UPLOAD_UNAVAILABLE (загрузка больше не пригодна), IMAGE_TOO_LARGE (размер), IMAGE_TYPE_UNSUPPORTED (тип файла), IMAGE_CONTENT_INVALID (файл повреждён, не совпадает с заявленным размером/типом или не проходит проверку изображения).
Текущие методы набора не присваивают publicUrl полю cover. Описанный сценарий загрузки применяется к атрибутам карточки.
