Public REST API

Платформа МАК Карты Онлайн открывает REST API для двух типов клиентов:

ИИ-агенты и интеграции – читают список колод, тянут случайные карты для самостоятельной работы, получают картинки с водяным знаком.
Магазины и партнёры – генерируют, проверяют и отзывают пригласительные коды на доступ к колодам.

Обе аудитории работают через один и тот же контракт. Где он отличается, мы это явно отмечаем.

Если вы делаете ИИ-агента

Минимальный сценарий – ChatGPT, скрипт на Python, MCP-сервер, бот в Slack, любая интеграция, которой нужны карты для саморефлексии или ассоциативной работы.

Зайдите на сайт МАК Карт Онлайн → меню профиля → раздел «Доступ для ИИ и интеграций» (для магазинов – «API Key»).
Создайте ключ mk_live_…. Скопируйте сразу: после показа второй раз его не видно.
Импортируйте в ChatGPT или свой инструмент безопасную для ИИ спецификацию: https://app.makcards.online/api/v1/public/openapi.ai.json. Эта версия без операций трат жемчуга – ИИ не сможет случайно сгенерировать платный пригласительный код от вашего имени.

Первый вызов:

curl -X POST https://app.makcards.online/api/v1/public/draw \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"any","count":1,"image_width":1024}'

Ответ содержит drawn[0].image_url – подписанная ссылка на PNG карты (срок жизни 15 минут). Запросите её обычным GET без дополнительной авторизации – это не понадобится, токен встроен в URL.

Параметры /draw:

scope: deck (одна колода – нужно deck_id), any (любая доступная), favorites (только избранные).
count: 1..3 на Free тарифе, 1..5 на Premium. Каждая карта считается отдельным запросом в лимите.
exclude_ids: массив {deck_id}:{card_id} – чтобы не повторять карты внутри серии вытяжек.
image_width: 512 (по умолчанию) или 1024.

Если вы магазин или партнёр

Сценарий: вы продаёте доступ к колоде на своём сайте – генерируете invite-код после оплаты, передаёте покупателю, тот вводит его в МАК Картах. Бизнес-правила (рефанды, цены жемчуга, пограничные случаи при изменении статуса колоды) описаны в разделе Жемчужины и маркетплейс.

Включите выплату жемчугом за каждую сгенерированную колоду – это контекст для расчёта стоимости кода.
Сгенерируйте ключ так же, как и ИИ-агент, в разделе «Доступ для ИИ и интеграций».

После оплаты вашим клиентом выпустите код:

curl -X POST https://app.makcards.online/api/v1/public/invite-codes/generate \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"deck_id":"<UUID>","access_type":"private","target_email":"buyer@example.com"}'

Передайте code покупателю.
Если оплата не прошла или нужен возврат – отозвите код:
```
curl -X POST https://app.makcards.online/api/v1/public/invite-codes/revoke \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"code":"..."}'
```
Жемчуг возвращается на ваш баланс, если код ещё не активирован.

Авторизация

Три способа авторизоваться, в порядке популярности:

API-ключ – Authorization: Bearer mk_live_…. Тот же ключ работает на каждом методе из этого документа. Управление: Профиль → Доступ для ИИ и интеграций.
MCP-серверы (размещённые у нас или локальные) – мы держим мост Model Context Protocol для Claude Desktop, ChatGPT-плагинов и подобных клиентов. Выберите хост по бренду аккаунта:
- mcp.makcards.online (RU-бренд)
- mcp.journalingapp.app (глобальный бренд)
Размещённый мост принимает тот же ключ mk_live_…. Для изолированной сети или локального использования – установите Node-пакет @maccards/mcp и выставите MAKCARDS_API_KEY в его конфиге. Оба говорят на Streamable HTTP и предоставляют четыре инструмента: list_decks, get_deck, draw_card, get_usage. 3. OAuth 2.1 – для веб-агентов, которые хотят, чтобы пользователь нажал «Подключить» вместо вставки ключа. ChatGPT.com и Claude.ai идут этим путём. Пользователь попадает на наш consent-экран, видит, какие разрешения (read, draw) запрашивает агент, и может отозвать доступ из Профиль → Доступ для ИИ и интеграций → Подключённые приложения в любой момент. Refresh-токены обновляются по скользящей схеме; при подозрении на компрометацию вся цепочка отзывается и пользователь получает уведомление.

Методы выдачи картинок также принимают короткоживущий подписанный токен из ответа /draw или /decks – передавайте в query ?token=… или в заголовке X-Image-Token. Это механика только для них, она не заменяет ни один из трёх способов выше.

Любой ключ или refresh-токен – это пароль. Не вставляйте в публичные репозитории, чаты с поддержкой, скриншоты. При компрометации сразу перегенерируйте API-ключ из Доступа для ИИ и интеграций или отзовите OAuth-подключение из Подключённых приложений – старые учётные данные перестанут работать через минуту.

Лимиты запросов

Окно	Free	Premium
Карт в минуту (`draws_per_min`)	30	120
Карт в час (`draws_per_hour`)	200	2000
Карт в сутки (`draws_per_day`)	500	10 000
Запросов к `/decks` в минуту	30	120
Запросов к картинкам в минуту	60	240

Текущее состояние вашего расхода: GET /api/v1/public/usage. Кроме счётчиков по окнам там есть by_endpoint_today – сколько раз сегодня вы вызвали каждый метод.

В ответах присутствуют заголовки RFC 9331:

RateLimit-Limit – лимит самого «жмущего» окна.
RateLimit-Remaining – сколько осталось.
RateLimit-Reset – секунд до сброса.

При превышении – HTTP 429 с Retry-After. ИИ-агентам стоит просто подождать.

Картинки карт и водяной знак

Все картинки отдаются с водяным знаком – название домена платформы (makcards.online или journalingapp.app) тонкой полосой сверху и снизу с прозрачностью 6%. Снимать водяной знак – нарушение условий использования.

Ширина 512 или 1024 пикселя. Большего размера через API мы не отдаём принципиально – это часть IP-защиты авторов.

Карта одной колоды может выглядеть в API цельным изображением, даже если в редакторе для неё включена защита от копирования (картинка хранится разрезанной на тайлы). Сервер собирает её и накладывает водяной знак на лету.

Лицензия и использование

Каждая карта в ответе /draw несёт license:

type=user – пользовательская колода автора (UGC). По умолчанию персональное использование, коммерческое – нет, перераспределение – нет.
type=community – публичная одобренная колода. Аналогично – персональное использование.
type=invite_private / invite_public – доступ через купленный invite-код. Условия определяет автор колоды.

Поле effective_constraints в ответе суммирует условия по всем картам выдачи – удобно для агента, чтобы быстро принять решение «можно ли публиковать этот раскладик».

Главное правило: даже если ваш сценарий – это «помочь пользователю поразмышлять», не используйте карты в маркетинговых материалах, не публикуйте отдельные карты как «обои» или «контент дня», не делайте экспортных «галерей». Платформа отслеживает прямые запросы картинок через pub_api_draws; за массовый сбор аккаунт блокируется.

Полный справочник методов

Машиночитаемая спецификация:

Полная: https://app.makcards.online/api/v1/public/openapi.json – для разработчиков и магазинов.
Безопасная для ИИ: https://app.makcards.online/api/v1/public/openapi.ai.json – для ChatGPT Custom GPT и других ИИ-агентов, импортирующих один документ. Здесь нет операций с пригласительными кодами, поэтому пользователь не сможет случайно дать чату право тратить жемчуг.

Краткая таблица:

Метод	Назначение	Кто использует
`GET /me`	Профиль владельца ключа, уровень, локаль	оба
`GET /decks?scope=…`	Список доступных колод	оба
`GET /decks/{id}`	Детали колоды + groups + signed back_url	оба
`POST /draw`	Случайная карта(ы)	ИИ
`GET /decks/{id}/cards/{cid}/image`	Карта картинкой (с водяным знаком)	ИИ
`GET /decks/{id}/back`	Рубашка колоды	оба
`GET /decks/{id}/groups/{gid}/back`	Рубашка группы	оба
`GET /usage`	Текущие квоты	оба
`POST /invite-codes/generate`	Сгенерировать код	магазины
`POST /invite-codes/apply`	Активировать код от лица пользователя	магазины
`POST /invite-codes/check`	Узнать статус кода	магазины
`POST /invite-codes/revoke`	Отозвать неактивированный код	магазины
`GET /invite-codes`	Список выпущенных кодов	магазины

Привязка к бренду

Каждый API-ключ, OAuth-токен и MCP-сессия привязаны к одному бренду – тому хосту, на котором вы их создали. mk_live_…, выпущенный на app.makcards.online, вернёт 403, если направить его на app.journalingapp.app, и наоборот. То же самое с OAuth refresh-токенами. Кросс-бренд-сессий нет: если вы работаете с обоими брендами – генерируйте два ключа и направляйте каждую интеграцию на свой хост. Бренд определяется по заголовку Host автоматически, так что достаточно выбрать правильное имя хоста.

Forensics утечек карт (только для модерации)

Если автор колоды сообщает, что карта с водяным знаком появилась там, где не должна, у модераторов есть инструмент, который определяет, какой API-вызов её вытянул. Инструмент живёт на POST /api/v1/public/mod/forensics/identify и доступен только членам команды модерации. Загружаете утёкшую картинку – сервер анализирует водяной знак и возвращает кандидатов по API-ключам плюс время вытяжки. Это аудит, а не самостоятельный инструмент.

Если вы заметили утечку – сообщите через Профиль → Уведомления → Отправить жалобу или письмом на moderation@makcards.online.

Формат ошибок

Все ответы об ошибках идут в едином envelope:

{
  "error": {
    "code": "deck_not_playable",
    "message": "This deck is not in a playable status.",
    "request_id": "019e3aa4-5c4d-709a-9606-9d9751461fd1"
  }
}

code – машиночитаемый идентификатор. Перечень: unauthorized, invalid_api_key, invalid_token, forbidden, not_found, invalid_request, rate_limited, no_cards_available, deck_not_playable, content_blocked, payload_too_large, internal_error, service_unavailable.
request_id – UUID v7, совпадает с заголовком X-Request-Id. Прислать его в поддержку – мы быстро находим конкретный запрос в логах.

Часто задаваемые вопросы

Можно ли тянуть карту из колоды, которая ещё в черновике (draft)? Нет. Даже владелец колоды не может тянуть из неё, пока статус – draft. Вернётся 422 deck_not_playable. Опубликуйте колоду как private или дальше – и API сразу заработает.

Зачем разные OpenAPI документа? Чтобы ИИ-инструменты (ChatGPT Custom GPT, например) не могли случайно потратить ваш жемчуг через /invite-codes/generate. Подмножество для ИИ физически не содержит этих операций – ИИ про них просто не знает.

Хочу увидеть только свои колоды, без публичных и купленных. По умолчанию /decks возвращает всё доступное (scope=accessible): свои + публично одобренные + купленные. Чтобы получить только свой каталог, передайте ?scope=owned.

Можно ли получить оригинал картинки без водяного знака? Нет. Это принципиальная позиция – API всегда отдаёт PNG с водяным знаком шириной 512 или 1024 с белой рамкой, скруглёнными углами и прозрачным фоном за рамкой. Без водяного знака карту видно только внутри игры на доске.

Что делать, если ключ скомпрометирован? Перегенерируйте в «Доступ для ИИ и интеграций». Старый ключ перестаёт работать в течение минуты.

Куда смотреть дальше

Жемчужины и маркетплейс – бизнес-правила для магазинов-партнёров: рефанды, расчёт стоимости в жемчуге, пограничные случаи.
Аккаунт и профиль – где находится «Доступ для ИИ и интеграций», управление ключом и Premium.
/openapi.json – машиночитаемый контракт (полный).
/openapi.ai.json – машиночитаемый контракт (подмножество, безопасное для ИИ).