Джасп — это таск-менеджер, платформа мастер-данных, MCP-сервер и API для ваших идей. Всё, что делает интерфейс, доступно снаружи: читать и создавать записи, получать изменения в реальном времени, принимать заявки с форм, загружать файлы и подключать своего ИИ-помощника.
Зачем вам API Джаспа
Если вы просто ведёте дела в Джаспе, API вам не нужен — всё уже работает в приложении. API нужен, когда Джасп должен стать частью чего-то ещё.
Например: вы хотите свой сайт со своей вёрсткой, но чтобы контент редактировался в Джаспе. Или мобильное приложение, которое показывает те же карточки. Или чтобы заявки с формы падали не только в проект, но и в вашу 1С. Или чтобы ИИ-ассистент из вашего редактора кода умел заводить задачи. Всё это — один и тот же API.
Модель данных: одна запись на всё
В Джаспе нет отдельных таблиц под задачи, страницы, сообщения и товары. Есть одна сущность, и выглядит она так: { id, type, text, entities }. Задача, страница сайта, сообщение в чате и поле формы — это всё она, отличается только type.
text — массив строк: первая строка это заголовок, дальше описание. entities — массив всего, что к записи прицеплено: теги, проект, вложения, блоки страницы. Именно теги заменяют привычные поля и колонки: статус, исполнитель, дата, категория — всё это записи в entities.
Из-за этого API получается маленьким. Не нужно учить схему под каждый тип объекта — достаточно понять одну.
Точки входа
Всего их пять, и все принимают POST:
Обратите внимание: у /mcp не должно быть слеша в конце — https://jusp.io/mcp/ вернёт 404. Токен можно передавать и параметром ?token=, и заголовком token.
Как получить токен
Авторизация в Джаспе по номеру телефона, не по email. Отправьте телефон и пароль на /api:
В ответе придёт token — сохраните его у себя на клиенте и подставляйте во все последующие запросы. Рядом в body.tag будет ваш профиль: id и title (имя пользователя), их тоже удобно сохранить для отображения.
Токен — это ключ ко всему вашему аккаунту. Не кладите его в код фронтенда: для публичных данных он не нужен (см. раздел про public), а для приватных запросы должны идти через ваш сервер.
Как прочитать записи по HTTP
Чтение и запись идут в один эндпоинт /api, отличается только тело. Чтобы забрать все записи проекта, пришлите фильтр:
Важная особенность, на которой спотыкаются все. По HTTP надёжно работает только эта каноническая форма — фильтр по проекту через $contains. Если добавить в фильтр что-то ещё — type на верхнем уровне, id записи, второй тег внутри $contains — ответ вернётся пустым, хотя записи в базе есть. Причина в том, как считается доступ на HTTP-пути. Поэтому practical-рецепт такой: запрашивайте весь проект канонической формой, а фильтруйте уже у себя в памяти. Если нужна точная выборка на стороне сервера — используйте WebSocket, там фильтры работают полноценно.
Как подписаться на обновления
Это главный способ работы с Джаспом. Вы подписываетесь не на «страницу», а на фильтр: сервер сразу присылает всё, что ему соответствует, а дальше досылает изменения по мере появления. Обновлять и перезапрашивать ничего не нужно.
Ставьте тег проекта первым в $contains. Сервер смотрит именно на первый элемент, чтобы понять, можно ли отдать вам подписку быстрым путём — через общий канал проекта. Если первым идёт обычный тег, подписка всё равно заработает, но уедет на медленный путь с проверкой прав на каждое сообщение.
Про операторы: $contains требует, чтобы на записи были все перечисленные теги (это «и»). $contained срабатывает, если есть хотя бы один из них (это «или»). Их легко перепутать.
По подписке записи приходят в таком виде:
Как создать или изменить запись
Запись создаётся и меняется одним и тем же сообщением — блоком actions. Разница только в флаге $create:
Три правила, которые экономят часы отладки:
1. Поля text, entities и data передаются обёрнутыми в `[{ $set: ... }]`, а не голым значением. Если послать data плоским объектом, сервер обнулит вложенные массивы.
2. $set заменяет значение целиком. Чтобы добавить один тег, прочитайте запись, дополните массив у себя и пришлите его полностью — иначе сотрёте остальные теги.
3. Результат записи берите из done[].to в ответе, а не из того, что отправили. Именно там лежит то, что реально сохранилось.
Удаление — тот же блок с $delete: true.
Теги: как задать свойства записи
Тег — это любой атрибут. Есть несколько разновидностей, и у каждой своя форма:
Тег проекта обязателен в каждой записи — без него она никуда не попадёт. Даты и места — не больше одного на запись.
Ещё одна деталь: чтобы теги отрисовались в текстовом представлении карточки, в text добавляют по одному null на каждый видимый тег — обычно это [...text, ...tags.map(() => null)]. Тег самого проекта в тексте не показывается и null не требует.
Как открыть записи всем
По умолчанию запись видна только участникам проекта, и чтобы её прочитать, нужен токен. Поставьте тег { id: 'public' } — и запись станет доступна анонимно, без токена.
Это правильный способ отдавать данные наружу. Если вы делаете публичный сайт или витрину, публикуйте записи с public и читайте их без авторизации — тогда токен не придётся показывать в браузере.
В ответе придут id файла и cdnPath. Готовый адрес картинки собирается из них: ${cdnPath}/${id}/src.${type}. Чтобы прицепить файл к записи, добавьте в её entities тег { id: '', type: 'media' }.
Вебхуки: когда Джасп сам стучится к вам
Если у вас есть сервер, держать постоянный сокет не обязательно. Зарегистрируйте вебхук — и Джасп сам пришлёт POST, когда появится подходящая запись:
Что важно знать про текущее поведение вебхуков:
— Срабатывают только на создание записи. Изменение существующей вебхук не разбудит.
— В теле приходит { "entity": { "<ключ>": { ...запись } } }, но ключом сейчас оказывается идентификатор самого вебхука (домен и путь вашего URL), а не id записи. Настоящий id берите из тела записи — поле id внутри объекта.
— Заголовок Content-Type на исходящем запросе не выставляется, тело приезжает как text/plain. Если у вас Express, express.json() такое тело пропустит мимо — читайте сырой body и парсите сами.
— Один URL — один вебхук: повторная регистрация того же адреса перезапишет фильтр.
MCP: научить ИИ-помощника работать с Джаспом
У Джаспа есть MCP-сервер. Добавьте его в конфиг своего ассистента — и он сможет искать по вашим проектам, заводить и править карточки, генерировать картинки:
Токен для конфига можно получить тем же запросом авторизации по телефону и паролю.
Ссылки внутри Джаспа
Адреса собираются предсказуемо, их можно строить руками:
Что чаще всего ломается
Пустой ответ на HTTP-чтение. Почти всегда это неканоническая форма фильтра. Запросите весь проект и отфильтруйте в памяти.
Пропали теги после обновления.$set заменяет массив целиком — надо было прислать полный список, а не один новый тег.
Обнулились вложенные данные в `data`. Забыли обёртку [{ $set: ... }].
404 на MCP. Лишний слеш в конце адреса.
Подписка не приходит. Проверьте, что тег проекта стоит первым в $contains, и что вы шлёте wss://, а не https:// — браузерный WebSocket другую схему не примет.
Не видно записей без токена. Нужен тег public.
Разбор понятным языком — что такое теги, фильтры, реалтайм, формы и сайт на своём домене — в карточке «FAQ».